List query runs¶

GET/queries/runs

Get the list of query runs matching the given filters.

Required permissionlive-discover.query:execute

Parameters¶

Name	In	Type	Required	Description
`X-Tenant-ID`	header	string (uuid)	Yes	Tenant ID.
`pageSize`	query	integer	No	The size of the page requested.
`page`	query	integer	No	The page number to fetch, starting with 1.
`pageTotal`	query	boolean	No	Whether the number of pages should be calculated and returned in the response.
`sort`	query	array of string	No	Defines how to sort the data. Each item must match the pattern `(^[^:]+$)\|(^[^:]+:(asc\|desc)$)`.
`fields`	query	array of string	No	The fields to return in a partial response.
`queryId`	query	string (uuid)	No	Query ID.
`categoryId`	query	string (uuid)	No	Category ID.
`status`	query	array of string	No	One or more values indicating the status of a query run. Each item must be one of: `pending`, `started`, `finished`.
`result`	query	array of string	No	One or more values indicating the overall result of a query run. Each item must be one of: `notAvailable`, `succeeded`, `failed`, `timedOut`.
`createdByPrincipalType`	query	array of string	No	Type of principal that ran the query. Each item must be one of: `service`, `user`.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X GET "https://api-<data-region>.central.sophos.com/live-discover/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/live-discover/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/live-discover/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/live-discover/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/live-discover/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 objectrequired

List of query runs.

Query run.

Show child attributesHide child attributes

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.

pagesobjectrequired

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

See the guide for a narrative walkthrough of this API.

List query runs¶

Parameters¶

Request samples¶

Responses¶

200 — Page of query runs.¶

Errors¶

Response examples¶

200¶

`200` — Page of query runs.¶

`200`¶