GET - Threats by ID

Overview

This endpoint retrieves the complete details for a single threat using its unique ID. Target a threat by its threat_id in the path to get all its attributes and relationships. You can also use the include parameter to fetch related data, like detections and affectedhosts, in the same call. Use this API as a primary data gathering step in an incident response workflow. After an alert provides a threat_id, call this endpoint to get the rich context—such as file hashes and affected endpoints—needed for deeper investigation or to inform a remediation decision.

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/threats/{threat_id}GET {Trellix EDR_gateway_URL}/edr/v2/threats/{threat_id}

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
include	string	This is an optional parameter. Use this to get additional information, such as `detections` or `affectedhosts`.

Response

Response parameters

Parameter	Data Type	Description
aggregationKey	string	Internal ID / key used to aggregate related threat events.
severity	string (enum: s0–s5)	Severity rating of the threat. For details, see Security levels.
rank	integer	Priority rank order of the threat.
score	integer	Numerical risk or confidence score.
name	string	Name of the detected threat or malware family.
type	string (enum)	Classification type such as `pe`, `non-pe-file`, `non-pe-cmd`, `user`, `host`.
status	string (enum)	Lifecycle status of threat triage: new, updated, viewed, handled, expired.
firstDetected	string (date-time)	Timestamp of when the threat was first seen (UTC, ISO-8601).
lastDetected	string (date-time)	Timestamp of the most recent occurrence (UTC, ISO-8601).
edrUiUrl	string	Deep link to the threat in the EDR UI console.
hashes.sha256	string	SHA-256 cryptographic checksum of the malicious payload.
hashes.sha1	string	SHA-1 checksum
hashes.md5	string	MD5 checksum
interpreter.name	string	Script interpreter name, (for example, PowerShell, Python) — omitted if null.
interpreter.hashes	object	Hashes (sha256, sha1, md5) of the interpreter binary.
relationships.affectedhosts	object	Embedded affected hosts (when include=affectedhosts).
relationships.detections	object	Embedded detections (when include=detections).
threat_id	string	A unique identifier to a specific, aggregated threat incident. It serves as the primary record key. This key links a single malicious entity, such as the POWERSHELL_56039776.EXE file, to its associated host detections, execution traces, and metadata.

Response example

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "totalResourceCount": 1
  },
  "data": {
    "type": "threats",
    "id": "182612",
    "attributes": {
      "aggregationKey": "P_6E2918727CBB836F4D8E3404BDE9AEAF5D4DED5DD1F6916AAD3F3B956E6D8A17",
      "severity": "s4",
      "rank": 270,
      "score": 70,
      "name": "POWERSHELL_56039776.EXE",
      "type": "pe",
      "status": "new",
      "firstDetected": "2023-08-27T05:34:29Z",
      "lastDetected": "2023-08-27T05:34:29Z",
      "edrUiUrl": "https://xconsole.trellix.com/edr/#/monitoring/#/workspace/2160,TOTAL_THREATS,8112",
      "hashes": {
        "sha256": "6E2918727CBB836F4D8E3404BDE9AEAF5D4DED5DD1F6916AAD3F3B956E6D8A17",
        "sha1": "D9FBB3BD6269FE3D5F349A7569964DCD1AA229B5",
        "md5": "6FEE39009EA5B1110C5DA6DF2B7BDC43"
      }
    },
    "relationships": {
      "affectedhosts": {
        "data": [
          {
            "type": "affected-hosts",
            "id": "649889",
            "attributes": {
              "detectionsCount": 1,
              "severity": "s4",
              "rank": 270,
              "firstDetected": "2023-08-27T05:34:29Z",
              "host": {
                "os": {},
                "netInterfaces": [],
                "traceExtendedVisibility": 0,
                "hostOs": "",
                "aGuid": "6D0A37A8-B5B7-4414-9444-A2B17721642B"
              }
            }
          }
        ],
        "links": {
          "self": "/edr/v2/threats/182612/affectedhosts?page[offset]=0&page[limit]=100",
          "first": "/edr/v2/threats/182612/affectedhosts?page[offset]=0&page[limit]=100",
          "prev": "/edr/v2/threats/182612/affectedhosts?page[offset]=0&page[limit]=100",
          "next": "/edr/v2/threats/182612/affectedhosts?page[offset]=0&page[limit]=100",
          "last": "/edr/v2/threats/182612/affectedhosts?page[offset]=0&page[limit]=100"
        }
      },
      "detections": {
        "data": [
          {
            "type": "detections",
            "id": "652404",
            "attributes": {
              "traceId": "9a718cc6-d8f6-46da-b3cc-fc4dbbd60151",
              "firstDetected": "2023-08-27T05:34:29Z",
              "severity": "s4",
              "rank": 270,
              "tags": [
                "@ATA.DefenseEvasion",
                "@ATA.PrivilegeEscalation",
                "@MSI._reg_ep0130_imageexecution_high",
                "@ATE.T1546.012",
                "@ATE.T1112",
                "@ATA.Persistence"
              ],
              "host": {
                "os": {},
                "netInterfaces": [],
                "traceExtendedVisibility": 0,
                "hostOs": "",
                "aGuid": "6D0A37A8-B5B7-4414-9444-A2B17721642B"
              },
              "sha256": "6E2918727CBB836F4D8E3404BDE9AEAF5D4DED5DD1F6916AAD3F3B956E6D8A17"
            }
          }
        ],
        "links": {
          "self": "/edr/v2/threats/182612/detections?page[offset]=0&page[limit]=100",
          "first": "/edr/v2/threats/182612/detections?page[offset]=0&page[limit]=100",
          "prev": "/edr/v2/threats/182612/detections?page[offset]=0&page[limit]=100",
          "next": "/edr/v2/threats/182612/detections?page[offset]=0&page[limit]=100",
          "last": "/edr/v2/threats/182612/detections?page[offset]=0&page[limit]=100"
        }
      }
    }
  }
}

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.