Run query¶

POST/queries/runs

Run a query against the Sophos Data Lake, passing the SQL code as the value of a field in the request JSON. The schema reference is available here.

Required permissionxdr.query:execute

Parameters¶

Name	In	Type	Required	Description
`X-Tenant-ID`	header	string (uuid)	No	Tenant ID.

Request body¶

Content type: application/json

Request body fields

savedQueryobject

A saved query to run. Required if an ad hoc query isn't supplied.

Show child attributesHide child attributes

categoryIdstring (uuid)

(Optional) Query category ID.

queryIdstring (uuid)required

Saved query ID.

adHocQueryobject

Ad hoc query to run. Required if a saved query isn't supplied.

Show child attributesHide child attributes

namestring

(Optional) Name for the ad hoc query.
Must be 1–300 characters long.

templatestringrequired

SQL statement for the query. This can contain replacement variables wrapped in $$ (double dollar sign) delimiters.
Must be 15–50000 characters long.

variablesarray of object

Values of variables to be replaced in the template SQL.

Query variable.

Show child attributesHide child attributes

namestringrequired

Variable name.
Must be 1–100 characters long.

dataTypestringrequired

Data types supported for EDR Data Lake queries.
Must be one of: double, integer, text, dateTime, boolean.

valuestring

String value of the variable.
Must be 1–5000 characters long.

pivotTypestring

The meaning of an input parameter of a query.
Must be one of: deviceId, deviceName, sophosPid, ipAddress, username, sha256, filePath, registryKey, url.

matchEndpointsobject

Criteria to select endpoints.

Show child attributesHide child attributes

filtersarray of objectrequired

Filters to select specific endpoints. Currently, only filtering by endpoint IDs is supported, and it must be supplied.
Must contain exactly 1 item.

Find endpoints matching criteria.

Show child attributesHide child attributes

idsarray of string (uuid)

Find endpoints with the specified IDs.
Must contain 1–1000 items.

fromstring

Start of time range that is applied when running the query (inclusive). It can be in ISO duration format, full UTC timestamp or date only.
Must be at most 24 characters long.

tostring

End of time range that is applied when running the query (inclusive). It can be in ISO duration format, full UTC timestamp or date only.
Must be at most 24 characters long.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X POST "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"adHocQuery\": {
    \"template\": \"select * from \\\"xdr_data\\\" limit 10\"
  },
  \"from\": \"2022-01-01T12:02:01.000Z\",
  \"to\": \"2022-01-21T12:02:01.700Z\"
}"

import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'adHocQuery': {'template': 'select * from "xdr_data" limit 10'},
    'from': '2022-01-01T12:02:01.000Z',
    'to': '2022-01-21T12:02:01.700Z'},
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "adHocQuery": {
    "template": "select * from \"xdr_data\" limit 10"
  },
  "from": "2022-01-01T12:02:01.000Z",
  "to": "2022-01-21T12:02:01.700Z"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs" -Headers $headers -Body $body -ContentType "application/json"

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs", strings.NewReader(`{
  "adHocQuery": {
    "template": "select * from \"xdr_data\" limit 10"
  },
  "from": "2022-01-01T12:02:01.000Z",
  "to": "2022-01-21T12:02:01.700Z"
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

const response = await fetch("https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "adHocQuery": {
    "template": "select * from \"xdr_data\" limit 10"
  },
  "from": "2022-01-01T12:02:01.000Z",
  "to": "2022-01-21T12:02:01.700Z"
}),
});
const data = await response.json();
console.log(data);

Responses¶

`201` — Query run created.¶

Response fields

idstringrequired

Query run ID.

createdAtstring (datetime)required

When the query run was started.

createdByobject

Principal reference.

Show child attributesHide child attributes

idstring (uuid)required

Principal ID. This is the client ID for service principals.

typestring (enum)required

Principal type.
Must be one of: user, service.

namestring

Principal name. This doesn't apply to service principals.

accountIdstring (uuid)

Account ID.

accountTypestring

Account type.
Must be one of: partner, tenant, organization.

expiresAtstring (datetime)

When the query run expires or expired.

finishedAtstring (datetime)

When the query run completed.

resultstringrequired

Overall result of a query run.
Must be one of: notAvailable, succeeded, failed, canceled, timedOut.

statusstringrequired

Status of a query run.
Must be one of: started, pending, finished.

namestring

Query name.

queryobject

Reference to a query.

Show child attributesHide child attributes

idstring (uuid)required

Query ID.

namestring

Query name.

codestring

Identifier for query name.

categoryobject

Reference to a query category.

Show child attributesHide child attributes

idstring (uuid)required

Category ID.

namestring

Category name.

codestring

Identifier for category name. This is available only for 'canned' categories.

templatestring

Query SQL template.

variablesarray of object

Query template replacement variables.

Query variable.

Show child attributesHide child attributes

namestringrequired

Variable name.
Must be 1–100 characters long.

dataTypestringrequired

Data types supported for EDR Data Lake queries.
Must be one of: double, integer, text, dateTime, boolean.

valuestring

String value of the variable.
Must be 1–5000 characters long.

pivotTypestring

The meaning of an input parameter of a query.
Must be one of: deviceId, deviceName, sophosPid, ipAddress, username, sha256, filePath, registryKey, url.

matchEndpointsobject

Criteria to select endpoints.

Show child attributesHide child attributes

filtersarray of objectrequired

Filters to select specific endpoints. Currently, only filtering by endpoint IDs is supported, and it must be supplied.
Must contain exactly 1 item.

Find endpoints matching criteria.

Show child attributesHide child attributes

idsarray of string (uuid)

Find endpoints with the specified IDs.
Must contain 1–1000 items.

fromstring (date-time)

Start of time range that was applied when the query was run.

tostring (date-time)

End of time range that was applied when the query was run.

Errors¶

Status	Meaning
`400`	Bad request.
`500`	Unexpected error.

All error responses share the same shape — see the error response object.

Response examples¶

`201`¶

{
  "id": "string",
  "createdAt": "string",
  "createdBy": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "user",
    "name": "string",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "accountType": "partner"
  },
  "expiresAt": "string",
  "finishedAt": "string",
  "result": "notAvailable",
  "status": "started",
  "name": "string",
  "query": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "code": "string"
  },
  "category": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "code": "string"
  },
  "template": "string",
  "variables": [
    {
      "name": "string",
      "dataType": "double",
      "value": "string",
      "pivotType": "deviceId"
    }
  ],
  "matchEndpoints": {
    "filters": [
      {
        "ids": [
          "00000000-0000-0000-0000-000000000000"
        ]
      }
    ]
  },
  "from": "2021-10-01T00:00:00.000Z",
  "to": "2021-10-02T00:00:00.000Z"
}

See the guide for a narrative walkthrough of this API.

Run query¶

Parameters¶

Request body¶

Request samples¶

Responses¶

201 — Query run created.¶

Errors¶

Response examples¶

201¶

`201` — Query run created.¶

`201`¶