Skip to content

Get queries

GET/queries

Live Discover API · Query

Get queries matching the given filters.

Required permissionlive-discover.query-catalog:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
categoryId query string (uuid) No Category ID.
search query string No Search for items that match the given terms.
searchFields query array of string No Search only within the specified fields.
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.
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" -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",
    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" -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", 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", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — List of queries.

Response fields

itemsarray of objectrequired
List of queries.
Saved Live Discover query.
Show child attributesHide child attributes
idstring (uuid)required
Query ID.
namestringrequired
Query name.
codestring
Identifier for query name. This is available only for pre-defined queries.
descriptionstring
Query description.
templatestringrequired
SQL statement for a query. This can contain replacement variables wrapped in $$ (double dollar sign) delimiters.
variablesarray of objectrequired
Variables embedded in the value of template.
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.
supportedOSesarray of stringrequired
Supported endpoint operating systems.
Each item must be one of: linuxServer, macOSComputer, windowsComputer, windowsServer.
categoriesarray of objectrequired
Categories the query belongs to.
Represents a referenced object.
Show child attributesHide child attributes
idstring (uuid)required
The ID of the referenced object.
performanceobject
Query performance metrics based on historical data from query runs.
Show child attributesHide child attributes
scorestring
Live Discover query performance score.
Must be one of: excellent, good, fair, poor, notEvaluated.
averageExecutionTimeInMillisinteger
Average of all the execution times of historical executions in milliseconds.
averageDataTransferredInBytesinteger
Average of all the data transfer sizes of historical executions in bytes.
typestringrequired
Query type.
Must be one of: canned, custom.
tenantobject
Represents a referenced object.
Show child attributesHide child attributes
idstring (uuid)required
The ID of the referenced object.
createdAtstring (datetime)
When the query was created.
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.
updatedAtstring (datetime)
When the query was last updated.
updatedByobject
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.
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",
      "name": "string",
      "code": "string",
      "description": "string",
      "template": "string",
      "variables": [
        {
          "name": "string",
          "dataType": "double",
          "value": "string",
          "pivotType": "deviceId"
        }
      ],
      "supportedOSes": [
        "linuxServer"
      ],
      "categories": [
        {
          "id": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "performance": {
        "score": "excellent",
        "averageExecutionTimeInMillis": 0,
        "averageDataTransferredInBytes": 0
      },
      "type": "canned",
      "tenant": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "createdAt": "string",
      "createdBy": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "user",
        "name": "string",
        "accountType": "partner"
      },
      "updatedAt": "string",
      "updatedBy": {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "user",
        "name": "string",
        "accountType": "partner"
      }
    }
  ],
  "pages": {
    "current": 0,
    "size": 0,
    "total": 0,
    "items": 0,
    "maxSize": 0
  }
}

See the guide for a narrative walkthrough of this API.