POST request

Overview

This endpoint initiates an asynchronous real-time search across all connected endpoints. To use it, you submit a structured query in the request body that specifies what data you want to collect, such as host information or running processes. The API starts the search as a background job and returns a job ID, which you must then use with the status and results endpoints to track the search's progress and retrieve the data once complete.

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)

POST https://{Trellix EDR_gateway_URL}/edr/v2/searches/realtime

You can get the gateway URL from the Trellix on-boarding email. For example, https://api.manage.trellix.com.

Request

Request headers

Authorization: Bearer <your_bearer_token>
Content-Type: application/vnd.api+json
x-api-key: <your_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 page.

Request body

{
  "data": {
    "type": "realTimeSearches",
    "attributes": {
      "query": "Processes name, id where Processes name equals \"csrss\" and Processes name contains \"exe\""
    }
  }
}

For details about the Real-time Search response objects or artifacts to customize your query, see The Real-time Search response objects or artifacts.

Request parameters

There are no request parameters.

Response

Response example

{
  "data": {
    "type": "queue-jobs",
    "id": "rts-5432",
    "attributes": {
      "status": "in-progress"
    },
    "links": {
      "self": "/edr/v2/searches/queue-jobs/rts-5432"
    }
  }
}

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.