Start an XQL Query

Cortex XDR REST API

post /public_api/v1/xql/start_xql_query

Execute an XQL query.

For more information on how to run XQL queries, see Running XQL Query APIs.

Required license: Cortex XDR Pro per Endpoint or Cortex XDR Pro per GB

Request headers
Authorization
String
required
API Key
Example: authorization_example
x-xdr-auth-id
String
required
API Key ID
Example: xXdrAuthId_example
Body parameters
request_dataObjectrequired
queryString

String of the XQL query.

tenantsArray[string]

Note: This is only used when querying tenants managed by Managed Security Services Providers (MSSP).

List of strings used for running APIs on local and Managed Security tenants. Valid values: - For single tenant (local tenant) query, enter a single-item list with your tenant_id. Additional valid values are, empty list ([]) or null (default). - For multi-tenant investigations (Managed Security parent who investigate children and/or local), enter multi-item list with the required tenant_id. List of IDs can contain the parent, children, or both parent and children.

timeframeObject

Integer in timestamp epoch milliseconds. Valid values include: - Absolute Unix timestamp representing a date period: {"from" : 1598907600000, "to" : 1599080399000} = date period: 31/08/20 09:00:00 PM UTC - 02/09/20 8:59:59 PM UTC - Relative Unix timestamp representing the last 24 hours: {"relativeTime": 86400000} = (246060*1000 = 86400000).

fromString

Use for an absolute timeframe in Unix timestamp.

toString

Use for an absolute timeframe in Unix timestamp.

relativeTimeString

Use for a relative Unix timestamp.

REQUEST BODY
{ "request_data": { "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3", "tenants": [ "431509831", "401387390" ], "timeframe": { "from": "1598907600000", "to": "1599080399000" } } }
CURL
curl -X 'POST'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: authorization_example' -H 'x-xdr-auth-id: xXdrAuthId_example'
'https://api-yourfqdn/public_api/v1/xql/start_xql_query'
-d ''
Responses

Successful response

Body
replyString
RESPONSE
{ "reply": "ad21c1e1492d4c_667_inv" }

Bad Request. Invalid JSON.

Body
replyObject
err_codeInteger
err_msgString
err_extraObject
err_msgString
query_costInteger
remaining_quotaInteger
total_daily_running_queriesInteger

The number of daily active queries.

total_daily_concurrent_rejected_queriesInteger

The number of daily queries rejected due to too many concurrent XQL queries being run through the API.

RESPONSE
{ "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } }

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Body
replyObject
err_codeInteger
err_msgString
err_extraObject
err_msgString
query_costInteger
remaining_quotaInteger
total_daily_running_queriesInteger

The number of daily active queries.

total_daily_concurrent_rejected_queriesInteger

The number of daily queries rejected due to too many concurrent XQL queries being run through the API.

RESPONSE
{ "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } }

Unauthorized access. User does not have the required license type to run this API.

Body
replyObject
err_codeInteger
err_msgString
err_extraObject
err_msgString
query_costInteger
remaining_quotaInteger
total_daily_running_queriesInteger

The number of daily active queries.

total_daily_concurrent_rejected_queriesInteger

The number of daily queries rejected due to too many concurrent XQL queries being run through the API.

RESPONSE
{ "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } }

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Body
replyObject
err_codeInteger
err_msgString
err_extraObject
err_msgString
query_costInteger
remaining_quotaInteger
total_daily_running_queriesInteger

The number of daily active queries.

total_daily_concurrent_rejected_queriesInteger

The number of daily queries rejected due to too many concurrent XQL queries being run through the API.

RESPONSE
{ "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } }

Internal server error. A unified status for API communication type errors.

Body
replyObject
err_codeInteger
err_msgString
err_extraObject
err_msgString
query_costInteger
remaining_quotaInteger
total_daily_running_queriesInteger

The number of daily active queries.

total_daily_concurrent_rejected_queriesInteger

The number of daily queries rejected due to too many concurrent XQL queries being run through the API.

RESPONSE
{ "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } }