Run detections query¶

POST/queries/detections

Run a query on the detections. The default time range is one day.

Required permissiondetections.queries.detections:create

Parameters¶

Name	In	Type	Required	Description
`X-Tenant-ID`	header	string (uuid)	Yes	Tenant ID.

Request body¶

Content type: application/json

Request body fields

detectionRulestring

The Detection rule ID.
Must match the pattern ^[\p{L}0-9\s_-]*$. Must be 0–300 characters long.

deviceNamestring

The device name.
Must match the pattern ^[\p{L}0-9\s_-]*$. Must be 0–200 characters long.

severityarray of integer

Filter detections by the severity level.
Items must be unique. Each item must be ≥ 0 and ≤ 10.

typearray of string

Filter detections by the type.
Items must be unique. Each item must be one of: process, threat, vulnerability.

categoryarray of string

Filter detections by the category.
Items must be unique. Each item must be one of: cloud, endpoint, email, firewall, iam, network, compound, backupAndRecovery.

sourcestring

The detection source.
Must match the pattern ^[\p{L}0-9\s]*$. Must be 0–200 characters long.

mitreAttackTacticsarray of string

Filter detections by the MITRE ATT&CK tactic name.
Items must be unique. Each item must be one of: collection, commandControl, credentialAccess, defenseEvasion, discovery, execution, exfiltration, impact, initialAccess, lateralMovement, persistence, privilegeEscalation, reconnaissance, resourceDevelopment, undefined.

mitreAttackstring

Case-insensitive text field that allows partial matching to filter by the MITRE ATT&CK technique ID, technique name, or tactic.

userNamearray of string

Filter detections by the username (exact match).
Must contain at most 10 items. Items must be unique. Each item must match the pattern ^[\p{L}\s_-]*$. Each item must be 0–300 characters long.

entityTypestring

The entity type.
Must match the pattern ^[\p{L}\s]*$. Must be 0–200 characters long.

locationstring

The location.
Must match the pattern ^[\p{L}\s.-]*$. Must be 0–200 characters long.

observablestring

Case-insensitive text field that allows partial matching to filter by the raw data.

operatingSystemarray of string

Filter detections by the operating system (exact match).
Must contain at most 10 items. Items must be unique. Each item must match the pattern ^[\p{L}\s]*$. Each item must be 0–100 characters long.

operatingSystemNamestring

The operating system name.
Must match the pattern ^[\p{L}0-9\s._-]*$. Must be 0–200 characters long.

idsarray of string

Filter detections by the ID.
Must contain at most 10 items. Items must be unique. Each item must match the pattern ^[A-Fa-f0-9_-]+$. Each item must be at most 150 characters long.

showSuppressedboolean

Show suppressed detections, if true. False by default.

sortarray of object

Defines how to sort the data.

Show child attributesHide child attributes

fieldstring

Detection field that supports sorting.
Must be one of: category, detectionRule, entity, severity, source, time, type, mitreAttack, id, sensorGeneratedAt.

directionstring

Order of the results.
Must be one of: asc, desc.

fromstring (date-time)

Start of time range that is applied when retrieving detections. The default value is one day before the current date and time.

tostring (date-time)

End of time range that is applied when retrieving detections. The default value is the current date and time.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X POST "https://api-<data-region>.central.sophos.com/detections/v1/queries/detections" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"detectionRule\": \"MS-SEC-GRAPH-open\",
  \"severity\": [
    7,
    8,
    9,
    10
  ],
  \"sort\": [
    {
      \"field\": \"severity\",
      \"direction\": \"asc\"
    }
  ],
  \"from\": \"2021-11-10T12:23:54.780Z\",
  \"to\": \"2021-11-17T12:23:54.780Z\"
}"

import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/detections/v1/queries/detections",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'detectionRule': 'MS-SEC-GRAPH-open',
    'severity': [7, 8, 9, 10],
    'sort': [{'field': 'severity', 'direction': 'asc'}],
    'from': '2021-11-10T12:23:54.780Z',
    'to': '2021-11-17T12:23:54.780Z'},
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "detectionRule": "MS-SEC-GRAPH-open",
  "severity": [
    7,
    8,
    9,
    10
  ],
  "sort": [
    {
      "field": "severity",
      "direction": "asc"
    }
  ],
  "from": "2021-11-10T12:23:54.780Z",
  "to": "2021-11-17T12:23:54.780Z"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/detections/v1/queries/detections" -Headers $headers -Body $body -ContentType "application/json"

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/detections/v1/queries/detections", strings.NewReader(`{
  "detectionRule": "MS-SEC-GRAPH-open",
  "severity": [
    7,
    8,
    9,
    10
  ],
  "sort": [
    {
      "field": "severity",
      "direction": "asc"
    }
  ],
  "from": "2021-11-10T12:23:54.780Z",
  "to": "2021-11-17T12:23:54.780Z"
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    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/detections/v1/queries/detections", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "detectionRule": "MS-SEC-GRAPH-open",
  "severity": [
    7,
    8,
    9,
    10
  ],
  "sort": [
    {
      "field": "severity",
      "direction": "asc"
    }
  ],
  "from": "2021-11-10T12:23:54.780Z",
  "to": "2021-11-17T12:23:54.780Z"
}),
});
const data = await response.json();
console.log(data);

Responses¶

`201` — Successful creation of detections query.¶

Response fields

idstring (uuid)

ID of the run.

createdAtstring (date-time)

Timestamp when the run started.

expiresAtstring (date-time)

Timestamp when the run expired.

finishedAtstring (date-time)

Timestamp when the run finished.

resultCountinteger

The total number of items across all pages.

resultstring

Result of a query run on groups or detections.
Must be one of: succeeded, canceled, failed, notAvailable, timedOut.

statusstring

Status of a query run on groups or detections.
Must be one of: finished, pending, started.

Errors¶

Status	Meaning
`400`	Bad Request.
`401`	Unauthorized.
`403`	Forbidden.
`429`	Too Many Requests.
`500`	Unexpected error.

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

Response examples¶

`201`¶

{
  "id": "4a9bb69a-c7f1-4a59-b912-7fe4ba70b751",
  "createdAt": "2023-11-22T18:55:33.811Z",
  "expiresAt": "2023-11-23T18:55:33.811Z",
  "finishedAt": "2023-11-22T18:55:35.716Z",
  "resultCount": 100,
  "result": "succeeded",
  "status": "finished"
}

See the guide for a narrative walkthrough of this API.