Skip to content

Get endpoints

GET/queries/runs/{runId}/endpoints

Live Discover API · Query Run

Get statuses of endpoints in the query run.

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.
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.
match query array of string No Combination of query run status, result, and "with data" filter, delimited with a : (colon) symbol. For example, finished:succeeded:withData, finished:succeeded:withoutData.

Request samples

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

Responses

200 — Endpoint statuses.

Response fields

itemsarray of objectrequired
List of endpoint status objects.
Status of an endpoint in a query run.
Show child attributesHide child attributes
idstring (uuid)required
Endpoint ID.
typestringrequired
Endpoint type. Please note securityVm is deprecated and will be removed soon.
Must be one of: computer, server, securityVm.
hostnamestringrequired
Endpoint hostname.
osobject
OS information.
Show child attributesHide child attributes
isServerboolean
Whether the OS is a server OS.
platformstringrequired
OS platform type.
Must be one of: windows, linux, macOS.
namestringrequired
OS name as reported by the endpoint.
majorVersioninteger
OS major version.
minorVersioninteger
OS minor version.
buildinteger
OS build.
ipv4Addressesarray of string
List of IPv4 addresses.
ipv6Addressesarray of string
List of IPv6 addresses.
statusstringrequired
Status of a query run.
Must be one of: pending, started, finished.
resultstring
Overall result of a query run.
Must be one of: notAvailable, succeeded, failed, timedOut.
statusCodestring
Status code returned by the query running on the endpoint.
statusMessagestring
Message returned by the query running on the endpoint.
performanceobject
Query run metrics for an endpoint.
Show child attributesHide child attributes
scorestring
Live Discover query performance score.
Must be one of: excellent, good, fair, poor, notEvaluated.
dataTransferredInBytesinteger
Total size of the query results returned by the endpoints.
executionTimeInMillisinteger
Time the query took to execute on the endpoint.
resultCountinteger
Number of rows of results returned by the endpoint.
createdAtstring (datetime)
When the endpoint sent the first status.
finishedAtstring (datetime)
When the endpoint finished running the query.
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.
404 Can't find query run.
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",
      "type": "computer",
      "hostname": "string",
      "os": {
        "isServer": true,
        "platform": "windows",
        "name": "string",
        "majorVersion": 0,
        "minorVersion": 0,
        "build": 0
      },
      "ipv4Addresses": [
        "string"
      ],
      "ipv6Addresses": [
        "string"
      ],
      "status": "pending",
      "result": "notAvailable",
      "statusCode": "string",
      "statusMessage": "string",
      "performance": {
        "score": "excellent",
        "dataTransferredInBytes": 0,
        "executionTimeInMillis": 0
      },
      "resultCount": 0,
      "createdAt": "string",
      "finishedAt": "string"
    }
  ],
  "pages": {
    "current": 0,
    "size": 0,
    "total": 0,
    "items": 0,
    "maxSize": 0
  }
}

See the guide for a narrative walkthrough of this API.