Skip to content

Get query run

GET/queries/runs/{runId}

XDR Query API · Runs

Get a query run by ID.

Required permissionxdr.query:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) No Tenant ID.
runId path string (uuid) Yes Query run ID.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/xdr-query/v1/queries/runs/<runId>" -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/<runId>",
    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/<runId>" -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/<runId>", 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/<runId>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — Query run found.

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
403 Forbidden.
404 Can't find query run.
500 Unexpected error.

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

Response examples

200

{
  "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.