Background Tasks API

Creating a Background Task

The general request format for starting a background task:

POST _sme/async_requests/request
{
  "query" : "source sysmon_operational-* qsize=5 ",
  "dtFieldName": "@timestamp",
  "dtStart": "now-1d",
  "dtEnd": "now",
  "calculateStats": true,
  "calculateExecutionCost": "DEBUG"
}

Name	Syntax	Required	Default	Description
query	<string>	Required		Search query.
dtFieldName	<string>	No	specified in the cluster setting sme.core.global_dt_params.dt_field_name	The name of the field containing the timestamp.
dtStart	<string>	No	specified in the cluster setting sme.core.global_dt_params.dt_start	The start timestamp for the search.
dtEnd	<string>	No	specified in the cluster setting sme.core.global_dt_params.dt_end	The end timestamp for the search.
calculateStats	<bool>	No	false	When set to true, calculates sidebar and timeline.
calculateExecutionCost	<string>	No	OFF	Calculates query execution statistics. Can take values OFF, INFO, DEBUG.

info

The sidebar and timeline values will always be calculated using java.

Requesting the Result of a Background Task

GET _sme/async_requests/response/{id}?from={from}&to={to}

Name	Syntax	Required	Default	Description
id	<string>	Yes		The ID of the background task.
from	<int>	No	unlimited	The starting index of the results (inclusive).
to	<int>	No	unlimited	The ending index of the results (exclusive).

Example request to get all results of a background task:

GET _sme/async_requests/response/12345

Example request to get results with indices from 100 to 199:

GET _sme/async_requests/response/12345?from=100&to=200

Requesting Logs of a Background Task

GET _sme/async_requests/logs/{id}

Name	Syntax	Required	Default	Description
id	<string>	Yes		The ID of the background task.

Example request to get logs of a background task:

GET _sme/async_requests/logs/12345

Requesting the Status of a Background Task

GET _sme/async_requests/status/{id}

Name	Syntax	Required	Default	Description
id	<string>	Yes		The ID of the background task. If no ID is specified, returns the statuses of all background tasks available to the user.

Example request to get the status of a specific background task:

GET _sme/async_requests/status/12345

Example request to get the status of all background tasks:

GET _sme/async_requests/status/

Stopping a Background Task

info

This request only works for unfinished background tasks.

POST _sme/async_requests/break/{id}

Name	Syntax	Required	Default	Description
id	<string>	Yes		The ID of the background task. If no ID is specified, cancels all active background tasks available to the user.

Example request to cancel a specific background task:

POST _sme/async_requests/break/12345

Example request to cancel all active background tasks:

POST _sme/async_requests/break/

Deleting the Result of a Background Task

DELETE _sme/async_requests/delete/{id}

Name	Syntax	Required	Default	Description
id	<string>	Yes		The ID of the background task.

Example request to delete the result of a background task from disk:

DELETE _sme/async_requests/delete/12345

Exporting the Result of a Background Task to a File

The general request format for obtaining a file with the results of a background task:

POST _sme/async_requests/file_download/{id}
{
  "file_name": "my_file",
  "file_type": "json",
  "compress_results": false,
  "download_all_results": false,
  "download_results_size": 1000
}

Name	Syntax	Required	Default	Description
id	<string>	Yes		The ID of the background task.
file_name	<int>	Yes		The name of the result file.
file_type	<int>	Yes		The type of the result file (json, csv, xlsx).
compress_results	<bool>	No	false	When set to true, creates a .zip archive.
download_all_results	<bool>	No	false	When set to true, exports all events.
download_results_size	<int>	No	10000	Used when download_all_results=false.