Skip to content

Query alerts (POST)

POST/alerts/search

Common API · Alerts

Get alerts matching request.

Required permissionalerts:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
groupKey query string No Alert group key. You can filter by group key.
from query string (datetime) No You can find alerts that were raised on or after this time.
to query string (datetime) No You can find alerts that were raised before this time.
sort query array of string No Defines how to sort the data.
Each item must match the pattern (^[^:]+$)|(^[^:]+:([aA]|[dD][eE])[sS][cC]$).
product query array of string No Alerts for a product. You can query by product types.
Each item must be one of: other, endpoint, server, mobile, encryption, emailGateway, webGateway, phishThreat, wireless, firewall, ztna, cswitch, secureWebservice.
category query array of string No Alert category. You can query by different categories.
Each item must be one of: adSync, applicationControl, appReputation, azure, blockListed, connectivity, credentialManager, criticalAttackWarning, cswitch, cwg, denc, deviceAndPlatformHealth, dnsProtectionLocation, downloadReputation, endpointFirewall, fenc, forensicSnapshot, general, integrations, isolation, malware, mobiles, mtr, policy, protection, pua, runtimeDetections, security, smc, systemHealth, uav, uncategorized, updating, utm, virt, wireless, xgEmail, ztnaAuthentication, ztnaGateway, ztnaResource.
severity query array of string No Alerts for a specific severity level. You can query by severity levels.
Each item must be one of: high, medium, low.
ids query array of string (uuid) No List of IDs.
fields query array of string No The fields to return in a partial response.
pageSize query integer No The size of the page requested.
pageFromKey query string No The key of the item from where to fetch a page.
pageTotal query boolean No Whether the number of pages should be calculated and returned in the response.

Request body

Content type: application/json

Request body fields

categoryarray of string
Alert category.
Each item must be one of: adSync, applicationControl, appReputation, azure, blockListed, connectivity, credentialManager, criticalAttackWarning, cswitch, cwg, denc, deviceAndPlatformHealth, dnsProtectionLocation, downloadReputation, endpointFirewall, fenc, forensicSnapshot, general, integrations, isolation, malware, mobiles, mtr, policy, protection, pua, runtimeDetections, security, smc, systemHealth, uav, uncategorized, updating, utm, virt, wireless, xgEmail, ztnaAuthentication, ztnaGateway, ztnaResource.
groupKeystring
Alert group key.
fieldsarray of string
Fields to return in a partial response.
fromstring (datetime)
You can find alerts that were raised on or after this time.
idsarray of string (uuid)
Alert IDs.
productarray of string
Product that triggered the alert.
Each item must be one of: other, endpoint, server, mobile, encryption, emailGateway, webGateway, phishThreat, wireless, firewall, ztna, cswitch, secureWebservice.
severityarray of string
Severity level of the alert.
Each item must be one of: high, medium, low.
tostring (datetime)
You can find alerts that were raised before this time.
pageFromKeystring
Key of the item from where to fetch a page.
pageSizeinteger
Size of the page requested.
pageTotalboolean
Whether the number of pages should be calculated and returned in the response.
sortarray of string
Each item must match the pattern (^[^:]+$)|(^[^:]+:(asc|desc)$).

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/common/v1/alerts/search" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"category\": [
    \"malware\",
    \"mobiles\",
    \"policy\",
    \"protection\"
  ],
  \"fields\": [
    \"severity\",
    \"groupKey\",
    \"allowedActions\"
  ],
  \"from\": \"2021-02-12T10:00:00.000Z\",
  \"groupKey\": \"MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs\",
  \"ids\": [
    \"533a799a-9914-4a6f-ae4c-45cb36fa3672\",
    \"8c26a3db-9a72-45be-8bfa-1e032209a50b\",
    \"6289af43-ba34-4b59-b3de-23c90fbe9080\"
  ],
  \"pageFromKey\": \"2000818931339\",
  \"pageSize\": 50,
  \"pageTotal\": true,
  \"product\": [
    \"mobile\",
    \"wireless\",
    \"endpoint\"
  ],
  \"severity\": [
    \"high\",
    \"medium\"
  ],
  \"sort\": [
    \"raisedAt:desc\"
  ],
  \"to\": \"2021-02-13T10:00:00.000Z\",
  \"status\": [
    \"open\",
    \"closed\"
  ],
  \"action\": [
    \"acknowledge\"
  ],
  \"managedAgentNameContains\": \"server\",
  \"personNameContains\": \"john\",
  \"search\": \"malware\",
  \"searchFields\": [
    \"personName\",
    \"managedAgentName\"
  ],
  \"locale\": \"en-US\",
  \"updatedFrom\": \"2021-02-01T00:00:00.000Z\",
  \"updatedTo\": \"2021-02-28T23:59:59.999Z\",
  \"type\": [
    \"Event::Endpoint::Malware::Detection\"
  ],
  \"severityFilterMode\": \"exact\"
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/common/v1/alerts/search",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'category': ['malware', 'mobiles', 'policy', 'protection'],
    'fields': ['severity', 'groupKey', 'allowedActions'],
    'from': '2021-02-12T10:00:00.000Z',
    'groupKey': 'MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs',
    'ids': [   '533a799a-9914-4a6f-ae4c-45cb36fa3672',
               '8c26a3db-9a72-45be-8bfa-1e032209a50b',
               '6289af43-ba34-4b59-b3de-23c90fbe9080'],
    'pageFromKey': '2000818931339',
    'pageSize': 50,
    'pageTotal': True,
    'product': ['mobile', 'wireless', 'endpoint'],
    'severity': ['high', 'medium'],
    'sort': ['raisedAt:desc'],
    'to': '2021-02-13T10:00:00.000Z',
    'status': ['open', 'closed'],
    'action': ['acknowledge'],
    'managedAgentNameContains': 'server',
    'personNameContains': 'john',
    'search': 'malware',
    'searchFields': ['personName', 'managedAgentName'],
    'locale': 'en-US',
    'updatedFrom': '2021-02-01T00:00:00.000Z',
    'updatedTo': '2021-02-28T23:59:59.999Z',
    'type': ['Event::Endpoint::Malware::Detection'],
    'severityFilterMode': 'exact'},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "category": [
    "malware",
    "mobiles",
    "policy",
    "protection"
  ],
  "fields": [
    "severity",
    "groupKey",
    "allowedActions"
  ],
  "from": "2021-02-12T10:00:00.000Z",
  "groupKey": "MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs",
  "ids": [
    "533a799a-9914-4a6f-ae4c-45cb36fa3672",
    "8c26a3db-9a72-45be-8bfa-1e032209a50b",
    "6289af43-ba34-4b59-b3de-23c90fbe9080"
  ],
  "pageFromKey": "2000818931339",
  "pageSize": 50,
  "pageTotal": true,
  "product": [
    "mobile",
    "wireless",
    "endpoint"
  ],
  "severity": [
    "high",
    "medium"
  ],
  "sort": [
    "raisedAt:desc"
  ],
  "to": "2021-02-13T10:00:00.000Z",
  "status": [
    "open",
    "closed"
  ],
  "action": [
    "acknowledge"
  ],
  "managedAgentNameContains": "server",
  "personNameContains": "john",
  "search": "malware",
  "searchFields": [
    "personName",
    "managedAgentName"
  ],
  "locale": "en-US",
  "updatedFrom": "2021-02-01T00:00:00.000Z",
  "updatedTo": "2021-02-28T23:59:59.999Z",
  "type": [
    "Event::Endpoint::Malware::Detection"
  ],
  "severityFilterMode": "exact"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/common/v1/alerts/search" -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/common/v1/alerts/search", strings.NewReader(`{
  "category": [
    "malware",
    "mobiles",
    "policy",
    "protection"
  ],
  "fields": [
    "severity",
    "groupKey",
    "allowedActions"
  ],
  "from": "2021-02-12T10:00:00.000Z",
  "groupKey": "MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs",
  "ids": [
    "533a799a-9914-4a6f-ae4c-45cb36fa3672",
    "8c26a3db-9a72-45be-8bfa-1e032209a50b",
    "6289af43-ba34-4b59-b3de-23c90fbe9080"
  ],
  "pageFromKey": "2000818931339",
  "pageSize": 50,
  "pageTotal": true,
  "product": [
    "mobile",
    "wireless",
    "endpoint"
  ],
  "severity": [
    "high",
    "medium"
  ],
  "sort": [
    "raisedAt:desc"
  ],
  "to": "2021-02-13T10:00:00.000Z",
  "status": [
    "open",
    "closed"
  ],
  "action": [
    "acknowledge"
  ],
  "managedAgentNameContains": "server",
  "personNameContains": "john",
  "search": "malware",
  "searchFields": [
    "personName",
    "managedAgentName"
  ],
  "locale": "en-US",
  "updatedFrom": "2021-02-01T00:00:00.000Z",
  "updatedTo": "2021-02-28T23:59:59.999Z",
  "type": [
    "Event::Endpoint::Malware::Detection"
  ],
  "severityFilterMode": "exact"
}`))
    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/common/v1/alerts/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "category": [
    "malware",
    "mobiles",
    "policy",
    "protection"
  ],
  "fields": [
    "severity",
    "groupKey",
    "allowedActions"
  ],
  "from": "2021-02-12T10:00:00.000Z",
  "groupKey": "MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs",
  "ids": [
    "533a799a-9914-4a6f-ae4c-45cb36fa3672",
    "8c26a3db-9a72-45be-8bfa-1e032209a50b",
    "6289af43-ba34-4b59-b3de-23c90fbe9080"
  ],
  "pageFromKey": "2000818931339",
  "pageSize": 50,
  "pageTotal": true,
  "product": [
    "mobile",
    "wireless",
    "endpoint"
  ],
  "severity": [
    "high",
    "medium"
  ],
  "sort": [
    "raisedAt:desc"
  ],
  "to": "2021-02-13T10:00:00.000Z",
  "status": [
    "open",
    "closed"
  ],
  "action": [
    "acknowledge"
  ],
  "managedAgentNameContains": "server",
  "personNameContains": "john",
  "search": "malware",
  "searchFields": [
    "personName",
    "managedAgentName"
  ],
  "locale": "en-US",
  "updatedFrom": "2021-02-01T00:00:00.000Z",
  "updatedTo": "2021-02-28T23:59:59.999Z",
  "type": [
    "Event::Endpoint::Malware::Detection"
  ],
  "severityFilterMode": "exact"
}),
});
const data = await response.json();
console.log(data);

Responses

200 — Page of alerts.

Response fields

itemsarray of objectrequired
List of alerts.
Must contain at most 100 items.
Alert object.
Show child attributesHide child attributes
idstring (uuid)required
Alert ID.
allowedActionsarray of string
Actions that you can perform on these alerts.
Each item must be one of: acknowledge, cleanPua, cleanVirus, authPua, clearThreat, clearHmpa, sendMsgPua, sendMsgThreat.
categorystring
Alert categories.
Must be one of: adSync, applicationControl, appReputation, azure, blockListed, connectivity, credentialManager, criticalAttackWarning, cswitch, cwg, denc, deviceAndPlatformHealth, dnsProtectionLocation, downloadReputation, endpointFirewall, fenc, forensicSnapshot, general, integrations, isolation, malware, mobiles, mtr, policy, protection, pua, runtimeDetections, security, smc, systemHealth, uav, uncategorized, updating, utm, virt, wireless, xgEmail, ztnaAuthentication, ztnaGateway, ztnaResource.
descriptionstring
Alert description.
groupKeystring
Alert group key.
managedAgentobject
Show child attributesHide child attributes
idstring (uuid)required
Alert source ID.
typestringrequired
Source that triggered the alert.
Must be one of: mobile, computer, server, securityVm, utm, accessPoint, wirelessNetwork, mailbox, slec, xgFirewall, ztnaGateway, sensor.
namestring
Name of alert source.
personobject
Reference to the associated person on the alert source.
Show child attributesHide child attributes
idstring (uuid)required
User ID.
namestring
User name.
productstring
Product types.
Must be one of: other, endpoint, server, mobile, encryption, emailGateway, webGateway, phishThreat, wireless, firewall, ztna, cswitch, secureWebservice.
raisedAtstring (datetime)
When the alert was triggered.
severitystring
Severity levels for alerts.
Must be one of: high, medium, low.
tenantobject
Show child attributesHide child attributes
idstring (uuid)required
Tenant ID for the alert.
namestringrequired
Tenant name.
dataRegionstring
The data region where tenant data is stored.
Must be one of: eu01, eu02, us01, us02, us03, ca01, au01, jp01, in01, br01, ae01.
typestring
Alert type.
pagesobjectrequired
Show child attributesHide child attributes
fromKeystring
The key of the first item in the returned page.
nextKeystring
The key to use when fetching the next page.
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 on all the pages, if pageTotal=true was passed into the request.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
500 Unexpected error.

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

Response examples

200

{
  "items": [
    {
      "id": "a5ded91c-6575-435c-a6b4-64b94f9048ff",
      "allowedActions": [
        "acknowledge"
      ],
      "category": "updating",
      "description": "John-PC is out of date.",
      "groupKey": "MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs",
      "managedAgent": {
        "id": "bb90527d-73a8-4e6e-85c6-20c2e0c5bc6f",
        "type": "computer"
      },
      "person": {
        "id": "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15"
      },
      "product": "endpoint",
      "raisedAt": "2021-02-12T15:04:53.780",
      "severity": "medium",
      "tenant": {
        "id": "79067fa3-e4d0-4769-a5f7-8d6550b3b68b",
        "name": "Acme Corp"
      },
      "type": "Event::Endpoint::OutOfDate",
      "lastCorrelatedAt": "2021-02-12T16:30:45.123Z",
      "updatedAt": "2021-02-12T16:30:45.123Z",
      "eventCount": 5,
      "status": "open"
    },
    {
      "id": "f9415c5f-e0e9-41d7-8126-1956223a66f1",
      "allowedActions": [
        "acknowledge",
        "cleanPua"
      ],
      "category": "updating",
      "description": "Generic reputation PUA detected C:\\Temp\\WinExeSvc.exe",
      "groupKey": "MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs",
      "managedAgent": {
        "id": "bb90527d-73a8-4e6e-85c6-20c2e0c5bc6f",
        "type": "computer"
      },
      "person": {
        "id": "17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15"
      },
      "product": "endpoint",
      "raisedAt": "2021-02-12T15:04:53.780",
      "severity": "medium",
      "tenant": {
        "id": "79067fa3-e4d0-4769-a5f7-8d6550b3b68b",
        "name": "Acme Corp"
      },
      "type": "Event::Endpoint::PUADetected",
      "lastCorrelatedAt": "2021-02-12T15:04:53.780Z",
      "updatedAt": "2021-02-12T15:04:53.780Z",
      "eventCount": 1,
      "status": "open"
    }
  ],
  "pages": {
    "nextKey": "2000818931339",
    "total": 1,
    "items": 2,
    "size": 50,
    "maxSize": 1000
  }
}