Get Alerts

Overview

This endpoint retrieves a paginated list of raw security alerts. Use query parameters to filter, sort, and define a time range for your query. To retrieve all results for a large query, you must follow the next link in the response until it is null. Use this API as the foundation for data ingestion pipelines. It's the ideal source for forwarding all raw security alerts to a SIEM for correlation, a data lake for long-term archival, or a custom detection engine that operates on granular event data.

Authentication

Authentication type: Bearer Token, API Key.

You can create a token using client credentials obtained through the developer portal. The API Key (x-api-key) is provided in your onboarding email or on the API Access Management page.

Path (or URL)

<HTTPS Method>
GET https://{Trellix EDR_gateway_URL}/edr/v2/alerts

Request

Request headers

Authorization: Bearer <your_bearer_token>
Content-Type: application/vnd.api+json
x-api-key: <your_api_key>
Accept-Encoding: gzip

Authorization: This header is used to authenticate your request. You need to replace <your_bearer_token> with the actual token you generate.
Content-Type: This header tells the server that the request body format is json:api. Even though this specific call has no request body, the API requires this header.
x-api-key: This is a custom header required by the Trellix API for authentication. You'll need to replace <your_api_key> with the key from your onboarding email or the API Access Management page.
Accept-Encoding: This is an optional header you can include to tell the server you can accept a compressed response (using gzip), which can make the data transfer faster.

Request parameters

Parameters	Data type/Values	Description
sort	string	Specifies the order (ascending/descending) for the returned results.
from	integer	Sets the start of the time frame to search, in epoch milliseconds.
to	integer	Sets the end of the time frame to search, in epoch milliseconds.
filter	string	Narrows down results based on criteria like severity, name, or rank.
page[offset]	integer	Skips a specified number of records; used for pagination.
page[limit]	integer	Sets the maximum number of records to return per page.

Response

Response parameters

Parameters	Data type	Description
Trace_Id	string	Autogenerated GUID for the event.
Parent_Trace_Id	string	TraceId of the parent process event.
Root_Trace_Id	string	Root trace ID of the entire process group.
DetectionDate	string	Time of detection in EDR cloud.
Event_Date	string	Earliest timestamp from related traces (endpoint clock, UTC).
Activity	string	Evet type
Severity	string (enum: s0–s5)	BANF rule severity. For details, see Security levels.
Score	integer	BANF rule confidence score.
Detection_Tags	array[string]	MITRE ATT&CK tactic and technique IDs.
Related_Trace_Id	array[string]	TraceIds of events responsible for the detection.
RuleId	string	BANF rule ID that triggered the alert.
Rank	integer	TA calculated rank
Pid	integer	Process ID
Version	string	Version information
Parents_Trace_Id	array[string]	TraceIds of all ancestor processes (first = parentTraceId).
ProcessName	string	Name of the process that triggered the rule.
User	object	User name and domain: { `"domain": "...", "name": "..."` }.
CommandLine	string	Full command line of the triggering process.
Hash_Id	string	Detection ID — identical across identical detections (same data, different date/traceId).
Host_OS	string	Host OS: windows, linux, or mac.
Host_Name	string	Host name of the device.
MAGUID	string	Endpoint MA (formerly McAfee Agent) GUID — uniquely identifies the device.
Artifact	string	Event artifact type

Response example

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {},
  "data": [
    {
      "type": "alerts",
      "id": "01b51c67-0904-c5cf-002a-7003d125b2a2.346565425a0b6b2b7174aa555f67a043",
      "attributes": {
        "Trace_Id": "71d3a718-9095-494c-ada5-7134dbeaa564",
        "Parent_Trace_Id": "ffc4c8eb-6cf9-4b59-8416-b14d55d290dd",
        "Root_Trace_Id": "ffc4c8eb-6cf9-4b59-8416-b14d55d290dd",
        "DetectionDate": "2024-06-19T07:44:55.708+00:00",
        "Event_Date": "2024-06-19T07:43:17.567Z",
        "Activity": "Threat Detected",
        "Severity": "s0",
        "Score": 25,
        "Detection_Tags": [
          "@ATA.Execution",
          "@ATA.Persistence",
          "@ATA.PrivilegeEscalation",
          "@ATE.T1059",
          "@ATE.T1547.009",
          "@MSI._file_sysscript"
        ],
        "Related_Trace_Id": [
          "22ee44a6-3b26-4bb5-811e-c5e399069a64"
        ],
        "RuleId": "_file_sysscript",
        "Rank": 25,
        "Pid": 6600,
        "Version": "undefined",
        "Parents_Trace_Id": [
          "ffc4c8eb-6cf9-4b59-8416-b14d55d290dd",
          "5824f090-791e-47d5-a5ba-3abcb4f9d2b9",
          "599463c2-7f27-41c0-a096-21de1018bfa8",
          "5e910e15-c8d4-4724-af28-09be2b48abd9"
        ],
        "ProcessName": "SDXHelper.exe",
        "User": {
          "domain": "CDA",
          "name": "cdaauto"
        },
        "CommandLine": "\"C:\\Program Files\\Microsoft Office\\Root\\Office16\\SDXHelper.exe\" -Embedding",
        "Hash_Id": "h7GhOs3Jm6Buj+LuzOOHBg==",
        "Host_OS": "windows",
        "Host_Name": "302W1022H264",
        "MAGUID": "ADB3C24C-232B-11EF-3D71-005056AC48D2",
        "Artifact": "Threat"
      }
    }
  ],
  "links": {
    "self": "/edr/v2/alerts?page[offset]=5&page[limit]=1",
    "first": "/edr/v2/alerts?page[offset]=0&page[limit]=1",
    "prev": "/edr/v2/alerts?page[offset]=4&page[limit]=1",
    "next": "/edr/v2/alerts?page[offset]=6&page[limit]=1"
  }
}

Response codes

Status	Response	Description
200	OK	Your request was processed successfully. The server has returned the requested data.
400	Bad request	The server couldn't understand your request, likely due to a syntax error or an invalid parameter.
401	Access denied request	Your request was rejected because it lacks valid authentication credentials. Check your API key and token.
403	Forbidden	You are not authorized to access this resource. While your credentials may be valid, you don't have the necessary permissions.
404	Not Found	The specific resource or endpoint you requested does not exist.
415	Unsupported Media Type	The server rejected your request because the data format `(Content-Type)` is not supported.
429	Too Many Requests	You've exceeded the rate limit by sending too many requests in a short period. The `Retry-After` header in the response will tell you how long to wait before trying again.
500	Internal Server Error	Something went wrong on the server's end. This is not an issue with your request.