Skip to content

Get query

GET/queries/{queryId}

Live Discover API · Query

Get a query by ID.

Required permissionlive-discover.query-catalog:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
queryId path string (uuid) Yes Query 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/<queryId>" -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/<queryId>",
    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/<queryId>" -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/<queryId>", 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/<queryId>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — Query found.

Response fields

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.

Errors

Status Meaning
403 Forbidden.
404 Can't find query.
500 Unexpected error.

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

Response examples

200

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

See the guide for a narrative walkthrough of this API.