--- title: "GET - Threats by ID" slug: "get-threats-by-id-1" tags: ["Product Usage", "EDR", "Endpoint Security"] updated: 2026-09-03T18:14:35Z published: 2026-09-03T18:14:35Z canonical: "docs.trellix.com/get-threats-by-id-1" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.trellix.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://developer.manage.trellix.com/). The API Key (`x-api-key`) is provided in your onboarding email or on the API Access Management page. ### Path *(or URL)* ``` 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 Content-Type: application/vnd.api+json x-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](https://developer.manage.trellix.com/public) 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. |