Start an XQL Query

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.

Note

To ensure you don't surpass your quota, Cortex XDR allows you to run up to four API queries in parallel.

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

Accept-Encoding

String

For retrieving a compressed gzipped response

Example: acceptEncoding_example

Default: gzip

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: authorization_example'
          -H
          'x-xdr-auth-id: xXdrAuthId_example'
          -H
          'Accept-Encoding: acceptEncoding_example'
      
      'https://api-yourfqdn/public_api/v1/xql/start_xql_query'
    
      -d
      ''

import http.client

conn = http.client.HTTPSConnection("api-yourfqdn")

payload = "{\"request_data\":{\"query\":\"dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3\",\"tenants\":[],\"timeframe\":{\"from\":\"1598907600000\",\"to\":\"1599080399000\"}}}"

headers = {
    'Authorization': "SOME_STRING_VALUE",
    'x-xdr-auth-id': "SOME_STRING_VALUE",
    'Accept-Encoding': "SOME_STRING_VALUE",
    'content-type': "application/json"
    }

conn.request("POST", "/public_api/v1/xql/start_xql_query", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-yourfqdn/public_api/v1/xql/start_xql_query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'SOME_STRING_VALUE'
request["x-xdr-auth-id"] = 'SOME_STRING_VALUE'
request["Accept-Encoding"] = 'SOME_STRING_VALUE'
request["content-type"] = 'application/json'
request.body = "{\"request_data\":{\"query\":\"dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3\",\"tenants\":[],\"timeframe\":{\"from\":\"1598907600000\",\"to\":\"1599080399000\"}}}"

response = http.request(request)
puts response.read_body

const data = JSON.stringify({
  "request_data": {
    "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3",
    "tenants": [],
    "timeframe": {
      "from": "1598907600000",
      "to": "1599080399000"
    }
  }
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-yourfqdn/public_api/v1/xql/start_xql_query");
xhr.setRequestHeader("Authorization", "SOME_STRING_VALUE");
xhr.setRequestHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
xhr.setRequestHeader("Accept-Encoding", "SOME_STRING_VALUE");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/v1/xql/start_xql_query")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("x-xdr-auth-id", "SOME_STRING_VALUE")
  .header("Accept-Encoding", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"request_data\":{\"query\":\"dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3\",\"tenants\":[],\"timeframe\":{\"from\":\"1598907600000\",\"to\":\"1599080399000\"}}}")
  .asString();

import Foundation

let headers = [
  "Authorization": "SOME_STRING_VALUE",
  "x-xdr-auth-id": "SOME_STRING_VALUE",
  "Accept-Encoding": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = ["request_data": [
    "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3",
    "tenants": [],
    "timeframe": [
      "from": "1598907600000",
      "to": "1599080399000"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/xql/start_xql_query")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-yourfqdn/public_api/v1/xql/start_xql_query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"request_data\":{\"query\":\"dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3\",\"tenants\":[],\"timeframe\":{\"from\":\"1598907600000\",\"to\":\"1599080399000\"}}}",
  CURLOPT_HTTPHEADER => [
    "Accept-Encoding: SOME_STRING_VALUE",
    "Authorization: SOME_STRING_VALUE",
    "content-type: application/json",
    "x-xdr-auth-id: SOME_STRING_VALUE"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-yourfqdn/public_api/v1/xql/start_xql_query");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "x-xdr-auth-id: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "Accept-Encoding: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "content-type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"request_data\":{\"query\":\"dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3\",\"tenants\":[],\"timeframe\":{\"from\":\"1598907600000\",\"to\":\"1599080399000\"}}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/xql/start_xql_query");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
request.AddHeader("Accept-Encoding", "SOME_STRING_VALUE");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"request_data\":{\"query\":\"dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3\",\"tenants\":[],\"timeframe\":{\"from\":\"1598907600000\",\"to\":\"1599080399000\"}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

application/json

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).

frominteger

Use for an absolute timeframe in Unix timestamp.

tointeger

Use for an absolute timeframe in Unix timestamp.

relativeTimestring

Use for a relative Unix timestamp.

REQUEST

{
  "request_data": {
    "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3",
    "tenants": [
      "431509831",
      "401387390"
    ],
    "timeframe": {
      "from": 1598907600000,
      "to": 1599080399000
    }
  }
}

Responses

Successful response

Body

application/json

replystring

RESPONSE

{
  "reply": "ad21c1e1492d4c_667_inv"
}

Bad Request. Invalid JSON.

Body

application/json

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

application/json

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

application/json

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

application/json

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

application/json

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
    }
  }
}