Get XQL Query Results

Retrieve XQL query API results.

Synopsis

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

Description

Retrieve results of an executed XQL query API.
Maximum result set size is 1000. The API does not support pagination, therefore, you can set values to determine the result size limitation and how to wait for the results. To view response with greater than 1000 results you must call Get XQL Query Results Stream.

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_id
(
Required
) Integer representing the unique execution ID generated by the response to
Start an XQL Query API
.
You can also enter the execution ID of a query generated in the Cortex XDR app and listed in the Query Center table.
pending_flag
Boolean flag indicating whether the API call should operate in synchronous\blocking mode, or in asynchronous\non-blocking mode. Valid Values:
  • true
    (default)—The call returns immediately with one of the following options:
    • PENDING
      status indicating query hasn't yet completed or results are not yet ready to be returned. Need to execute the API call again.
    • SUCCESS/FAIL
      status
  • false
    —The API will block until query completes and results are ready to be returned.
limit
Integer representing the maximum number of results to return. For example:
  • If
    limit = 100
    and the query produced 1,000 results, only the first 100 results will be returned.
  • If
    limit = 100
    and the query produced 50 results, only 50 results will be returned.
  • If
    limit=null or empty
    (default) all results are returned with the
    Get XQL Query Results Stream
    API. For example, if
    limit=5000
    , only 5,000 results are returned.
In multi-tenant investigations, the parameter value (
x
) returns x result for all tenants, not
x
results for each tenant. For example, if
y
tenants participate in the investigation, the max number of results returned can be
x*y
(up to 1,000,000 limit).
format
String representing the type of response output. Valid values:
  • json
    (default)
  • csv
Request Example
curl -X POST https://api-{fqdn}/public_api/v1/xql/get_query_results/ \ -H "x-xdr-auth-id:{key_id}" \ -H "Authorization:{key}" \ -H "Content-Type:application/json" \ -d '{ "request_data": { "query_id": "executionID", "pending_flag": true, "limit": 100, "format": "json" } }'

Success Response

Upon success, the HTTP response code is 200.
Field
Description
reply
JSON object containing the query result.
status
String representing the status of the API call;
SUCCESS
,
FAIL
, or
PENDING
.
For multi-tenant queries,
PARTIAL_SUCCESS
—At least one tenant failed to execute the query. Only partial results are available.
number_of_results
Integer representing the number of results returned.
query_cost
Float representing the number of query units collected for this API. For example,
{"local_tenant_id": 0.01}
.
For multi-tenant queries, the field displays a value per child tenant. For example,
{"tenant_id_1": 0.01, "tenant_id_2": 2.3}
.
remaining_quota
Float representing the number of query units available for you to use.
results
Displays the API response in either of the following fields according to the number of results:
  • data
    —API results according to defined
    format
    field.
  • stream_id
    —String representing a unique ID of more than 1000 number of results. Use the ID to call Get XQL Results Stream API to retrieve the results.
Success Response Examples
pending_flag
=
true
{ "reply": { "status": "PENDING" } }
Up to 1,000 results, JSON format, Single Tenant Investigation
{ "reply": { "status": "SUCCESS", "number_of_results": 3, "query_cost": {"tenant_id_1": 0.001596388888888889}, "remaining_quota": 4.998403611111111, "results": { "data": [ {"event_id": "eventID1", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL"}, {"event_id": "eventID2", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL"}, {"event_id": "eventID3", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL"} ] } } }
Up to 1,000 results, CSV format, Single Tenant Investigation
{ "reply": { "status": "SUCCESS", "number_of_results": 3, "query_cost": {"tenant_id_1": 0.001596388888888889}, "remaining_quota": 4.998403611111111, "results": { "data": "_vendor,_product,insert_timestamp,event_id1,_time,event_type,event_sub_type\r\nPANW,Fusion,2021-05-20 20:17:05.324000+00:00,eventID,2021-05-20 20:12:03+00:00,STORY,NULL\r\nPANW,Fusion,2021-05-20 20:17:05.326000+00:00,eventID2,2021-05-20 20:12:08+00:00,STORY,NULL\r\nPANW,Fusion,2021-05-20 20:17:05.325000+00:00,eventID3,2021-05-20 20:11:57+00:00,STORY,NULL\r\n" } } }
Up to 1,000 results, JSON format, Multi Tenant Investigation
{ "reply": { "status": "SUCCESS", "number_of_results": 6, "query_cost": {"tenant_id_1": 0.001596388888888889, "tenant_id_2": 0.00179989}, "remaining_quota": 4.995007332222222, "results": { "data": [ {"event_id": "eventID1", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655"}, {"event_id": "eventID2", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655"}, {"event_id": "eventID3", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655"}, {"event_id": "eventID4", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706"}, {"event_id": "eventID5", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706"}, {"event_id": "eventID6", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706"} ] } } }
More then 1,000 results
{ "reply": { "status": "SUCCESS", "number_of_results": 1000000, "query_cost": {"tenant_id_1": 0.011742777777777777}, "remaining_quota": 4.984442777777778, "results": { "stream_id": "streamID" } } }

Unsuccessful Response

Upon an unsuccessful call, the following fields are displayed:
Field
Description
reply
JSON object containing the query result.
status
String representing the status of the API call.
error
Error message describing the reason for an unsuccessful response.
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