--- title: "POST request" slug: "post-request-4" tags: ["EDR", "Endpoint Security", "Product Usage"] updated: 2026-11-05T06:45:17Z published: 2026-11-05T06:45:17Z canonical: "docs.trellix.com/post-request-4" --- > ## 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. # POST request ### Overview This endpoint starts an asynchronous search of historical telemetry from managed endpoints. Define the search with a query, `startTime`, and `endTime` to receive a job ID for polling status and retrieving results. Use this API to investigate past events and hunt for threats. It is the primary tool for querying historical data to find indicators of compromise (IOCs) or to reconstruct incident timelines. ### 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)* ```plaintext POST https://{Trellix EDR_gateway_URL}/edr/v2/searches/historical ``` You can get the gateway URL from the Trellix on-boarding email. For example, `https://api.manage.trellix.com` ### Request ###### Request headers ```plaintext Authorization: Bearer Content-Type: application/vnd.api+json x-api-key: ``` - **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. ###### Request parameters | Parameters | Data type/Values | Description | | --- | --- | --- | | | | | | query | string | Define the query. | | startTime and endTime | string | The time period for the results to be fetched. Format: `YYYY-MM-DDThh:mm:ssZ`. > [!NOTE] > Note > > The error code returns for the invalid timestamp format. | | sort | string | Single column to be sorted by value. Default sort field: `Time`. Below is the list of allowed values for the sort request parameter: \| - 'Time', 'DetectionDate', 'Activity', 'DeviceName', 'Tags', 'Process_Name' - 'User_Name', 'File_Path', 'Network_Protocol', 'Network_DstIp', 'Network_DstPort', 'Registry_KeyValue_Path' - 'Registry_KeyValueName', 'RelatedProcess_ProcessName', 'Api_Name', 'Dns_Name', 'Pipe_Name', 'Score', 'Module_Name' - 'SchedTask_Name', 'Service_Name', 'Ppid', 'Pid', 'Integrity', 'Author', 'Command_Line', 'File_MD5', 'Process_MD5' - 'File_Sha256', 'Process_Sha256', 'Module_Sha256', 'File_Sha1', 'Process_Sha1', 'File_Name', 'File_Size', 'Network_AccessType' - 'Network_Direction', 'Network_DnsName', 'ScheduledTask_Commands', 'Action', 'Registry_KeyValue', 'Registry_KeyValueType', 'Registry_KeyOldValue' - 'Logon_Success', 'User_Domain', 'Logon_LogonType', 'Logon_Domain', 'Logon_Name', 'Logon_LogonId', 'Logon_Ip', 'Logon_Port' - 'Logon_WorkstationName', 'Api_Arguments', 'Api_Result', 'Api_ModuleName', 'Api_TargetPid', 'Modules', 'RuleId', 'Parent_Process_Name' - 'Service_Executable_Path', 'Service_Username', 'ScheduledTask_User', 'File_Type', 'File_NewPath', 'Registry_Key_Name', 'Injection_Apis' - 'Network_HTTP_URL', 'Network_HTTP_Request', 'Network_HTTP_Response' - 'Network_Sent_Bytes', 'Network_Received_Bytes', 'Process_Path', 'Process_Original_Name', 'Service_Action', 'ScheduledTask_Action' - 'User_Logon_Name', 'Process_TargetPid', 'Process_TargetTraceID', 'Process_Type', 'Process_Status', 'Process_TargetProcessName', 'ComApis' \| \| --- \| | | - 'Time', 'DetectionDate', 'Activity', 'DeviceName', 'Tags', 'Process_Name' - 'User_Name', 'File_Path', 'Network_Protocol', 'Network_DstIp', 'Network_DstPort', 'Registry_KeyValue_Path' - 'Registry_KeyValueName', 'RelatedProcess_ProcessName', 'Api_Name', 'Dns_Name', 'Pipe_Name', 'Score', 'Module_Name' - 'SchedTask_Name', 'Service_Name', 'Ppid', 'Pid', 'Integrity', 'Author', 'Command_Line', 'File_MD5', 'Process_MD5' - 'File_Sha256', 'Process_Sha256', 'Module_Sha256', 'File_Sha1', 'Process_Sha1', 'File_Name', 'File_Size', 'Network_AccessType' - 'Network_Direction', 'Network_DnsName', 'ScheduledTask_Commands', 'Action', 'Registry_KeyValue', 'Registry_KeyValueType', 'Registry_KeyOldValue' - 'Logon_Success', 'User_Domain', 'Logon_LogonType', 'Logon_Domain', 'Logon_Name', 'Logon_LogonId', 'Logon_Ip', 'Logon_Port' - 'Logon_WorkstationName', 'Api_Arguments', 'Api_Result', 'Api_ModuleName', 'Api_TargetPid', 'Modules', 'RuleId', 'Parent_Process_Name' - 'Service_Executable_Path', 'Service_Username', 'ScheduledTask_User', 'File_Type', 'File_NewPath', 'Registry_Key_Name', 'Injection_Apis' - 'Network_HTTP_URL', 'Network_HTTP_Request', 'Network_HTTP_Response' - 'Network_Sent_Bytes', 'Network_Received_Bytes', 'Process_Path', 'Process_Original_Name', 'Service_Action', 'ScheduledTask_Action' - 'User_Logon_Name', 'Process_TargetPid', 'Process_TargetTraceID', 'Process_Type', 'Process_Status', 'Process_TargetProcessName', 'ComApis' | | export | boolean | Applicable only for specific related historical/device searches. If set to `True`, this parameter must be used in the following APIs: - `/edr/vv2/searches/historical` - `/edr/v2/searches/queue-jobs/{searchId}` - `/edr/v2/searches/historical/{searchId}/results` Default value: `False`. | | maxResults | integer | The maximum number of rows to include in the response. Default value: `5000`. Available values: `5000`, `10000`, `25000`, `50000`, and `100000`. | **Request body fields** | Field | Data type | Description | | --- | --- | --- | | data.type | string | Must be **historicalSearches** | | data.attributes.query | string | Search query (1–20000 chars). Supports filtering search queries by process ID (`pid`) and parent process ID (`ppid`). Examples: `DeviceName equals "W7x64" CommandLine contains "exe"` `pid = 1996` `ppid != 2007` | | data.attributes.startTime | string (date-time) | Start of time range (ISO 8601) | | data.attributes.endTime | string (date-time) | End of time range (ISO 8601) | | data.attributes.maguid | string (uuid) | The Agent GUID uniquely identifies the device. | ###### Request example **Example 1: Standard Historical Search** ```plaintext {  "data": {    "type": "historicalSearches",    "attributes": {      "query": "IpAddress contains 10",      "startTime": "2021-07-05",      "endTime": "2021-12-15"    }  } } ``` **Example 2: Historical Search by PID** ```plaintext {    "data": {        "type": "historicalSearches",        "attributes": {            "query": "Pid = 1996",            "startTime": "2026-07-16T09:40:21Z",            "endTime": "2026-10-09T09:40:21Z"        }    } } ``` **Example 3: Historical Search by PPID** ```plaintext {    "data": {        "type": "historicalSearches",        "attributes": {            "query": "Ppid != 2004",            "startTime": "2026-07-16T09:40:21Z",            "endTime": "2026-10-09T09:40:21Z"        }    } } ``` **Example 4: Device Search with maguid** > [!NOTE] > Note > > For **Device Search**, include the **DeviceName** collector in the query with an optional maguid parameter. ```plaintext {  "data": {    "type": "historicalSearches",    "attributes": {      "query": "DeviceName contains DESKTOP",      "startTime": "2021-07-05T02:00:28Z",      "endTime": "2021-12-15T06:00:28Z",      "maguid": "A2C39241-BED9-49F0-BB8B-68F8902EE55C"    }  } } ``` ### Response ###### Response example ```plaintext {  "data": {    "type": "queue-jobs",    "id": "hs-01b5865f-0905-0572-002a-7003d239d812.346565425a0b6b2b7174aa555f67a043",    "attributes": {      "status": "in-progress"    },    "links": {      "self": "/edr/v2/searches/queue-jobs/hs-01b5865f-0905-0572-002a-7003d239d812.346565425a0b6b2b7174aa555f67a043"    }  } } ``` ### Response codes | Status | Response | Description | | --- | --- | --- | | 201 | Created | Your request was successful, and a new resource was created as a result. Your request was successful, and a new resource was created. The response includes details such as the resource ID, which you can use to track or manage the resource. | | 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. |