Start an XQL Query

Execute an XQL query.

Synopsis

URI
/public_api/v1/xql/start_xql_query/
HTTP Method
POST
Required License
Cortex XDR Pro per Endpoint or Cortex XDR Pro per TB

Description

Execute an XQL query.

Request Fields

The body of this request contains a JSON object with the following fields:
Field
Description
request_data
(
Required
) A dictionary containing the API request fields.
query
(
Required
) String of the XQL query.
tenants
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.
timeframe
Integer in timestamp epoch milliseconds. Cortex XDR calls by default the last 24 hours.
Valid values:
  • 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}
    = (24*60*60*1000 = 86400000).
Request Example
curl -X POST https://api-{fqdn}/public_api/v1/xql/start_xql_query/ \ -H "x-xdr-auth-id:{key_id}" \ -H "Authorization:{key}" \ -H "Content-Type:application/json" \ -d '{ "request_data": { "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3", "tenants": ["tenantID", "tenantID"], "timeframe": {"from": 1598907600000, "to": 1599080399000} } }'

Success Response

Upon success, the HTTP response code is 200.
Field
Description
reply
JSON object containing the query result.
execution_id
An integer representing a unique ID of a successful XQL query execution. The value is used to call the
Get XQL Query Results
API.
Every XQL Public API query is also visible in the
Cortex XDR app
Query Center
Execution ID
table field.
Success Response Example
{ "reply": "executionID" }

Unsuccessful Response

Upon an unsuccessful call, the following fields are displayed:
Field
Description
reply
JSON object containing the query result.
err_msg
Error message describing the reason for an unsuccessful response.
parse_err
Displayed with a bad query syntax.
Represents the line and column number, along with an error message. For example:
{"line": 1, "column": 19, "message": "no viable alternative at input '|alter2'"}
quota_info
Displayed when not enough quota is available.
Lists the amount of used quota and your quota limit.
query_cost
Float representing the number of query units collected for this API. In the case of an unsuccessful response, zero query units are collected.
remaining_quota
Float representing the amount of remaining quota available for use.

Error Response

Upon error, the reply includes an HTTP response code, an error message, and additional information describing the error. The HTTP response code is one of the following:
Field
Description
400
Bad Request. Got an invalid JSON.
401
Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.
402
Unauthorized access. User does not have the required license type to run this API.
403
Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.
500
Internal server error. A unified status for API communication type errors.
Error Response Format
{"reply": {"err_code": STATUS_CODE, "err_msg": GENERAL_MESSAGE, "err_extra": EXTRA_DATA}}

Recommended For You