Skip to content

Get query run

GET/queries/runs/{runId}

Live Discover API · Query Run

Get a query run by ID.

Required permissionlive-discover.query:execute

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
runId path string (uuid) Yes Query run ID.
fields query array of string No The fields to return in a partial response.

Request samples

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

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

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

Response examples

200

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