Skip to content

List query runs

GET/queries/runs

XDR Query API · Runs

Get the list of query runs matching the given filters.

Required permissionxdr.query:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) No Tenant ID.
statuses query array of string No Query run statuses.
Each item must be one of: started, pending, finished.
page query integer No The page number to fetch, starting with 1.
pageSize query integer No The size of the page requested.
pageTotal query boolean No Whether the number of pages should be calculated and returned in the response.
order query string No Order of results for a query run.
Must be one of: asc, desc.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs" -Headers $headers


package main

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

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    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: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — Page of query runs.

Response fields

itemsarray of object
Page of query runs.
Single instance of a query run.
Show child attributesHide child attributes
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.
pagesobject
Show child attributesHide child attributes
currentintegerrequired
The 1-based page number being returned.
sizeintegerrequired
The size of the page being returned.
totalinteger
(Optional) The total number of pages that exist, if pageTotal=true in the request.
itemsinteger
(Optional) The total number of items across all pages.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
403 Forbidden.
500 Unexpected error.

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

Response examples

200

{
  "items": [
    {
      "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"
    }
  ],
  "pages": {
    "current": 0,
    "size": 0,
    "total": 0,
    "items": 0,
    "maxSize": 0
  }
}

See the guide for a narrative walkthrough of this API.