Run query¶

POST/queries/runs

Run a saved EDR query or an ad hoc query on remote endpoints.

Required permissionlive-discover.query:execute

Parameters¶

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

Request body¶

Content type: application/json

Request body fields

savedQueryobject

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 Live Discover queries.
Must be one of: double, integer, text, dateTime, boolean.

valuestring

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

pivotTypestring

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

matchEndpointsobjectrequired

Criteria to select endpoints.

Show child attributesHide child attributes

allboolean

Whether to include all endpoints.

filtersarray of object

Filters to select specific endpoints. If present, must contain between one and five filter objects.
Must contain 1–5 items.

Find endpoints matching criteria.

Show child attributesHide child attributes

healthStatusarray of string

Find endpoints by health status.
Each item must be one of: good, suspicious, bad, unknown.

typearray of string

Find endpoints by type.
Each item must be one of: computer, server, securityVm.

tamperProtectionEnabledboolean

Find endpoints by whether Tamper Protection is turned on.

lockdownStatusarray of string

Find endpoints by lockdown status.
Each item must be one of: creatingWhitelist, installing, locked, notInstalled, registering, starting, stopping, unavailable, uninstalled, unlocked, locking.

idsarray of string (uuid)

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

lastSeenBeforestring

Find endpoints that were last seen before the given date and time (UTC) or a duration relative to the current date and time (exclusive).

lastSeenAfterstring

Find endpoints that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive).

hostnameContainsstring

Find endpoints where the hostname contains the given string.

associatedPersonContainsstring

Find endpoints where the name of the person associated with the endpoint contains the specified string.

groupNameContainsstring

Find endpoints where the name of the group the endpoint is in contains the given string. We are temporarily stopping support for groupNameContains until further notice.

osarray of object

Matches endpoints with any of the supplied operating system versions.

Matches where operating system platform, type, and version match.

Show child attributesHide child attributes

platformstring

OS platform type.
Must be one of: windows, linux, macOS.

typestring

Endpoint type. Please note securityVm is deprecated and will be removed soon.
Must be one of: computer, server, securityVm.

versionobject

Specifies the criteria for a version match.

Show child attributesHide child attributes

matchstring

Exact version match. Takes precedence over 'from' and 'to' range options.

fromstring

Match versions greater than or equal to this value.

tostring

Match versions less or equal to this value.

ipAddressesarray of string

Find endpoints by IP addresses.

searchstring

Term to search for in the specified search fields.

searchFieldsarray of string

List of search fields for finding the given search term. Defaults to all applicable fields.
Each item must be one of: hostname, groupName, associatedPersonName, ipAddresses, osName.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X POST "https://api-<data-region>.central.sophos.com/live-discover/v1/queries/runs" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"savedQuery\": {
    \"categoryId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",
    \"queryId\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"
  },
  \"variables\": [
    {
      \"name\": \"ExecutionName\",
      \"dataType\": \"integer\",
      \"value\": \"123\",
      \"pivotType\": \"deviceId\"
    }
  ],
  \"matchEndpoints\": {
    \"all\": false,
    \"filters\": [
      {
        \"healthStatus\": [
          \"good\"
        ],
        \"type\": [
          \"computer\"
        ],
        \"tamperProtectionEnabled\": true,
        \"lockdownStatus\": [
          \"creatingWhitelist\"
        ],
        \"ids\": [
          \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"
        ],
        \"lastSeenBefore\": \"2020-05-13T21:00:01.000\",
        \"hostnameContains\": \"example\",
        \"associatedPersonContains\": \"person\",
        \"groupNameContains\": \"group\",
        \"os\": [
          {
            \"platform\": \"windows\",
            \"type\": \"computer\",
            \"version\": {
              \"match\": \"10\"
            }
          }
        ],
        \"ipAddresses\": [
          \"10.50.100.100\"
        ],
        \"search\": \"example\",
        \"searchFields\": [
          \"hostname\"
        ]
      }
    ]
  }
}"

import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/live-discover/v1/queries/runs",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'savedQuery': {   'categoryId': '3fa85f64-5717-4562-b3fc-2c963f66afa6',
                      'queryId': '3fa85f64-5717-4562-b3fc-2c963f66afa6'},
    'variables': [   {   'name': 'ExecutionName',
                         'dataType': 'integer',
                         'value': '123',
                         'pivotType': 'deviceId'}],
    'matchEndpoints': {   'all': False,
                          'filters': [   {   'healthStatus': ['good'],
                                             'type': ['computer'],
                                             'tamperProtectionEnabled': True,
                                             'lockdownStatus': [   'creatingWhitelist'],
                                             'ids': [   '3fa85f64-5717-4562-b3fc-2c963f66afa6'],
                                             'lastSeenBefore': '2020-05-13T21:00:01.000',
                                             'hostnameContains': 'example',
                                             'associatedPersonContains': 'person',
                                             'groupNameContains': 'group',
                                             'os': [   {   'platform': 'windows',
                                                           'type': 'computer',
                                                           'version': {   'match': '10'}}],
                                             'ipAddresses': ['10.50.100.100'],
                                             'search': 'example',
                                             'searchFields': ['hostname']}]}},
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "savedQuery": {
    "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "queryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "variables": [
    {
      "name": "ExecutionName",
      "dataType": "integer",
      "value": "123",
      "pivotType": "deviceId"
    }
  ],
  "matchEndpoints": {
    "all": false,
    "filters": [
      {
        "healthStatus": [
          "good"
        ],
        "type": [
          "computer"
        ],
        "tamperProtectionEnabled": true,
        "lockdownStatus": [
          "creatingWhitelist"
        ],
        "ids": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ],
        "lastSeenBefore": "2020-05-13T21:00:01.000",
        "hostnameContains": "example",
        "associatedPersonContains": "person",
        "groupNameContains": "group",
        "os": [
          {
            "platform": "windows",
            "type": "computer",
            "version": {
              "match": "10"
            }
          }
        ],
        "ipAddresses": [
          "10.50.100.100"
        ],
        "search": "example",
        "searchFields": [
          "hostname"
        ]
      }
    ]
  }
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/live-discover/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/live-discover/v1/queries/runs", strings.NewReader(`{
  "savedQuery": {
    "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "queryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "variables": [
    {
      "name": "ExecutionName",
      "dataType": "integer",
      "value": "123",
      "pivotType": "deviceId"
    }
  ],
  "matchEndpoints": {
    "all": false,
    "filters": [
      {
        "healthStatus": [
          "good"
        ],
        "type": [
          "computer"
        ],
        "tamperProtectionEnabled": true,
        "lockdownStatus": [
          "creatingWhitelist"
        ],
        "ids": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ],
        "lastSeenBefore": "2020-05-13T21:00:01.000",
        "hostnameContains": "example",
        "associatedPersonContains": "person",
        "groupNameContains": "group",
        "os": [
          {
            "platform": "windows",
            "type": "computer",
            "version": {
              "match": "10"
            }
          }
        ],
        "ipAddresses": [
          "10.50.100.100"
        ],
        "search": "example",
        "searchFields": [
          "hostname"
        ]
      }
    ]
  }
}`))
    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/live-discover/v1/queries/runs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "savedQuery": {
    "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "queryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "variables": [
    {
      "name": "ExecutionName",
      "dataType": "integer",
      "value": "123",
      "pivotType": "deviceId"
    }
  ],
  "matchEndpoints": {
    "all": false,
    "filters": [
      {
        "healthStatus": [
          "good"
        ],
        "type": [
          "computer"
        ],
        "tamperProtectionEnabled": true,
        "lockdownStatus": [
          "creatingWhitelist"
        ],
        "ids": [
          "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ],
        "lastSeenBefore": "2020-05-13T21:00:01.000",
        "hostnameContains": "example",
        "associatedPersonContains": "person",
        "groupNameContains": "group",
        "os": [
          {
            "platform": "windows",
            "type": "computer",
            "version": {
              "match": "10"
            }
          }
        ],
        "ipAddresses": [
          "10.50.100.100"
        ],
        "search": "example",
        "searchFields": [
          "hostname"
        ]
      }
    ]
  }
}),
});
const data = await response.json();
console.log(data);

Responses¶

`201` — Query run created.¶

Response fields

idstring (uuid)required

Query run ID.

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 pre-defined categories.

queryobject

Show child attributesHide child attributes

idstring (uuid)required

Query ID.

namestring

Query name.

codestring

Localization code of the query.

namestringrequired

Query name.

templatestringrequired

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 Live Discover queries.
Must be one of: double, integer, text, dateTime, boolean.

valuestring

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

pivotTypestring

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

statusstringrequired

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

resultstringrequired

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

createdAtstring (datetime)

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.

accountTypestring

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

finishedAtstring (datetime)

When the query run completed.

maxDurationInSecondsintegerrequired

Maximum query duration allowed (in seconds) after which the query is terminated.

timeRemainingInSecondsintegerrequired

Remaining time in seconds.

performanceobject

Overall query performance metrics.

Show child attributesHide child attributes

scorestring

Live Discover query performance score.
Must be one of: excellent, good, fair, poor, notEvaluated.

dataTransferredInBytesobject

Statistics.

Show child attributesHide child attributes

totalinteger

Total value.

mininteger

Min value.

maxinteger

Max value.

medianinteger

Median value.

averageinteger

Average value.

executionTimeInMillisobject

Statistics.

Show child attributesHide child attributes

totalinteger

Total value.

mininteger

Min value.

maxinteger

Max value.

medianinteger

Median value.

averageinteger

Average value.

resultCountinteger

Count of query run results collected.

matchEndpointsobjectrequired

Criteria to select endpoints.

Show child attributesHide child attributes

allboolean

Whether to include all endpoints.

filtersarray of object

Filters to select specific endpoints. If present, must contain between one and five filter objects.
Must contain 1–5 items.

Find endpoints matching criteria.

Show child attributesHide child attributes

healthStatusarray of string

Find endpoints by health status.
Each item must be one of: good, suspicious, bad, unknown.

typearray of string

Find endpoints by type.
Each item must be one of: computer, server, securityVm.

tamperProtectionEnabledboolean

Find endpoints by whether Tamper Protection is turned on.

lockdownStatusarray of string

Find endpoints by lockdown status.
Each item must be one of: creatingWhitelist, installing, locked, notInstalled, registering, starting, stopping, unavailable, uninstalled, unlocked, locking.

idsarray of string (uuid)

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

lastSeenBeforestring

Find endpoints that were last seen before the given date and time (UTC) or a duration relative to the current date and time (exclusive).

lastSeenAfterstring

Find endpoints that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive).

hostnameContainsstring

Find endpoints where the hostname contains the given string.

associatedPersonContainsstring

Find endpoints where the name of the person associated with the endpoint contains the specified string.

groupNameContainsstring

Find endpoints where the name of the group the endpoint is in contains the given string. We are temporarily stopping support for groupNameContains until further notice.

osarray of object

Matches endpoints with any of the supplied operating system versions.

Matches where operating system platform, type, and version match.

Show child attributesHide child attributes

platformstring

OS platform type.
Must be one of: windows, linux, macOS.

typestring

Endpoint type. Please note securityVm is deprecated and will be removed soon.
Must be one of: computer, server, securityVm.

versionobject

Specifies the criteria for a version match.

Show child attributesHide child attributes

matchstring

Exact version match. Takes precedence over 'from' and 'to' range options.

fromstring

Match versions greater than or equal to this value.

tostring

Match versions less or equal to this value.

ipAddressesarray of string

Find endpoints by IP addresses.

searchstring

Term to search for in the specified search fields.

searchFieldsarray of string

List of search fields for finding the given search term. Defaults to all applicable fields.
Each item must be one of: hostname, groupName, associatedPersonName, ipAddresses, osName.

endpointCountsobjectrequired

Count of endpoints grouped by various attributes.

Show child attributesHide child attributes

totalinteger

Total number of endpoints.

typesobject

Number of endpoints of each type.

platformsobject

Number of endpoints by platform.

statusesobject

Count of endpoints grouped by the status of the query running on each endpoint.

Show child attributesHide child attributes

pendingobject

Count of endpoints grouped by whether they are online or not.

Show child attributesHide child attributes

totalinteger

Total number of endpoints.

offlineinteger

Number of endpoints that are offline.

onlineinteger

Number of endpoints that are online.

startedobject

Count of endpoints by whether they have returned any data.

Show child attributesHide child attributes

totalinteger

Total number of endpoints.

withDatainteger

Number of endpoints that have returned some data.

withoutDatainteger

Number of endpoints that have returned no data.

finishedobject

Count of endpoints grouped by the result of the query run on each endpoint.

Show child attributesHide child attributes

succeededobject

Count of endpoints by whether they have returned any data.

Show child attributesHide child attributes

totalinteger

Total number of endpoints.

withDatainteger

Number of endpoints that have returned some data.

withoutDatainteger

Number of endpoints that have returned no data.

failedobject

Count of endpoints by whether they have returned any data.

Show child attributesHide child attributes

totalinteger

Total number of endpoints.

withDatainteger

Number of endpoints that have returned some data.

withoutDatainteger

Number of endpoints that have returned no data.

timedOutobject

Count of endpoints by whether they have returned any data.

Show child attributesHide child attributes

totalinteger

Total number of endpoints.

withDatainteger

Number of endpoints that have returned some data.

withoutDatainteger

Number of endpoints that have returned no data.

Errors¶

Status	Meaning
`403`	Forbidden.
`404`	No resolved endpoints found.
`500`	Unexpected error.

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

Response examples¶

`201`¶

{
  "id": "00000000-0000-0000-0000-000000000000",
  "category": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "code": "string"
  },
  "query": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "code": "string"
  },
  "name": "string",
  "template": "string",
  "variables": [
    {
      "name": "string",
      "dataType": "double",
      "value": "string",
      "pivotType": "deviceId"
    }
  ],
  "status": "pending",
  "result": "notAvailable",
  "createdAt": "string",
  "createdBy": {
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "user",
    "name": "string",
    "accountType": "partner"
  },
  "finishedAt": "string",
  "maxDurationInSeconds": 0,
  "timeRemainingInSeconds": 0,
  "performance": {
    "score": "excellent",
    "dataTransferredInBytes": {
      "total": 0,
      "min": 0,
      "max": 0,
      "median": 0,
      "average": 0
    },
    "executionTimeInMillis": {
      "total": 0,
      "min": 0,
      "max": 0,
      "median": 0,
      "average": 0
    }
  },
  "resultCount": 0,
  "matchEndpoints": {
    "all": false,
    "filters": [
      {
        "healthStatus": [
          "good"
        ],
        "type": [
          "computer"
        ],
        "tamperProtectionEnabled": true,
        "lockdownStatus": [
          "creatingWhitelist"
        ],
        "ids": [
          "00000000-0000-0000-0000-000000000000"
        ],
        "lastSeenBefore": "string",
        "lastSeenAfter": "string",
        "hostnameContains": "string",
        "associatedPersonContains": "string",
        "groupNameContains": "string",
        "os": [
          {
            "platform": "windows",
            "type": "computer",
            "version": {
              "match": "string",
              "from": "string",
              "to": "string"
            }
          }
        ],
        "ipAddresses": [
          "string"
        ],
        "search": "string",
        "searchFields": [
          "hostname"
        ]
      }
    ]
  },
  "endpointCounts": {
    "total": 0,
    "types": {},
    "platforms": {},
    "statuses": {
      "pending": {
        "total": 0,
        "offline": 0,
        "online": 0
      },
      "started": {
        "total": 0,
        "withData": 0,
        "withoutData": 0
      },
      "finished": {
        "succeeded": {
          "total": 0,
          "withData": 0,
          "withoutData": 0
        },
        "failed": {
          "total": 0,
          "withData": 0,
          "withoutData": 0
        },
        "timedOut": {
          "total": 0,
          "withData": 0,
          "withoutData": 0
        }
      }
    }
  }
}

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`¶