--- title: List Bits Security Analyst investigations description: List Bits Security Analyst investigations. breadcrumbs: Docs > API > List Bits Security Analyst investigations --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # List Bits Security Analyst investigations ## v2 (latest) {% alert level="warning" %} **Note**: This endpoint is in preview and is subject to change. To request access, contact [Datadog support](https://docs.datadoghq.com/help.md) or your Customer Success Manager. {% /alert %} | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------------------------------------ | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/security_monitoring/security_agent/investigations | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/security_monitoring/security_agent/investigations | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/security_monitoring/security_agent/investigations | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/security_monitoring/security_agent/investigations | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/security_monitoring/security_agent/investigations | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/security_monitoring/security_agent/investigations | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/security_monitoring/security_agent/investigations | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/security_monitoring/security_agent/investigations | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/security_monitoring/security_agent/investigations | ### Overview List Bits Security Analyst investigations. Without `filter[signal_id]`, returns the latest investigation of each signal, filtered, sorted, and paginated. With `filter[signal_id]`, returns every investigation of that signal, newest first. When the signal has no investigation, the first page carries `meta.reason`, which says why. This endpoint requires the `security_monitoring_signals_read` permission. OAuth apps require the `security_monitoring_signals_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#bits-security-analyst) to access this endpoint. ### Arguments #### Query Strings | Field | Type | Description | | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter[signal_id] | string | List every investigation of this signal, newest first. Accepts the signal ID in its V1 form, which starts with `AQ`, or in its longer V3 form, which starts with `Aw`. Investigations carry the V1 form, so their `signal_id` can differ from the ID you pass. Can't be combined with other filters or with `sort`. | | filter[title] | string | Only investigations whose signal title contains this text, case-insensitive. | | filter[from] | string | Only investigations last updated at or after this time, as RFC 3339 or milliseconds since the epoch. | | filter[to] | string | Only investigations last updated at or before this time, as RFC 3339 or milliseconds since the epoch. | | filter[verdict] | string | Only investigations with one of these verdicts: `benign`, `suspicious`, or `malicious`. Comma-separated values; an investigation matches any of them. | | filter[state] | string | Only investigations in one of these states: `investigating` or `completed`. Investigations reported as `failed` match `investigating`. Comma-separated values; an investigation matches any of them. | | filter[rule_id] | string | Only investigations of signals from one of these detection rule IDs. Comma-separated values; an investigation matches any of them. | | filter[rule_type] | string | Only investigations of signals from detection rules of one of these types, as returned by the count with `field=rule_type`. Comma-separated values; an investigation matches any of them. | | filter[signal_severity] | string | Only investigations of signals with one of these severities: `info`, `low`, `medium`, `high`, or `critical`. Comma-separated values; an investigation matches any of them. | | filter[signal_source] | string | Only investigations of signals from one of these sources, as returned by the count with `field=signal_source`. Comma-separated values; an investigation matches any of them. | | filter[tags] | string | Only investigations whose signal has all of these tags, written `key:value`. Comma-separated values; an investigation must have every one of them. | | filter[entity] | string | Only investigations whose signal has all of these entities. Write each entity as `attribute:value`, matching the values returned by the count endpoint with `field=entity`. Comma-separated values; an investigation must have every one of them. | | sort | string | Sort field, prefixed with `-` for descending: `updated_at`, `severity`, `verdict`, `rule_id`, or `signal_title`. Defaults to `-updated_at`. `verdict` sorts by severity (`benign`, `suspicious`, `malicious`), so `-verdict` puts `malicious` first. | | page[number] | integer | Page number, starting at 1. Default: `1`. | | page[size] | integer | Number of investigations per page. Default: `25`. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} A page of investigations. | Parent field | Field | Type | Description | | ------------ | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | The investigations on this page. | | data | attributes [*required*] | object | Attributes of an investigation in a list. To get an investigation's full content, use the get investigation endpoint. | | attributes | created_at | date-time | When the investigation started. | | attributes | is_latest [*required*] | boolean | Whether this is the latest investigation of the signal. Always true when `filter[signal_id]` isn't set. | | attributes | rule_id [*required*] | string | ID of the detection rule that generated the signal. It can be empty while the investigation runs. | | attributes | signal | object | Summary of the signal the investigation is about. | | signal | severity | string | Severity of the signal: `info`, `low`, `medium`, `high`, or `critical`. | | signal | sources | [string] | Sources of the signal. | | signal | tactic | string | MITRE ATT&CK tactic, from the signal's `tactic` tag. | | signal | tags | [string] | Tags of the signal, written `key:value`. | | signal | technique | string | MITRE ATT&CK technique, from the signal's `technique` tag. | | signal | timestamp | string | Time the signal was generated. | | signal | title | string | Title of the signal. | | attributes | signal_id [*required*] | string | ID of the signal, in its V1 form. | | attributes | state [*required*] | enum | State of the investigation: `investigating` while it runs, `completed` after it has a result, or `failed` when it produced no result before its timeout. Allowed enum values: `investigating`, `completed`, `failed`. | | attributes | updated_at | date-time | When the investigation last changed. | | attributes | verdict | enum | Verdict of the investigation. Only completed investigations have one. Allowed enum values: `benign`, `suspicious`, `malicious`. | | data | id [*required*] | string | The ID of the investigation. | | data | type [*required*] | enum | Type of the investigation resource. Allowed enum values: `investigations`. Default: `investigations`. | | | meta [*required*] | object | Metadata of a page of investigations. | | meta | reason | enum | Why `filter[signal_id]` returned no investigation. Set only on the first page of an empty result. The reason is based on the organization's current settings. Poll again only on `investigation_not_started`, after the number of seconds in the `Retry-After` header; treat the others as final for this signal. - `investigation_not_started`: no investigation has started yet, but one may still start. - `not_investigated`: no investigation started within an hour of the signal, so none is expected. The signal was skipped for a reason this API doesn't report, such as its severity or a rate limit. - `rule_not_enabled`: the signal's detection rule doesn't have Bits Security Analyst enabled, so no investigation starts automatically. - `signal_not_found`: the ID isn't a signal ID, or no signal with this ID exists in the organization. - `org_not_activated`: the organization hasn't activated Bits Security Analyst. Allowed enum values: `investigation_not_started`, `not_investigated`, `rule_not_enabled`, `signal_not_found`, `org_not_activated`. | | meta | total_count [*required*] | int64 | Without `filter[signal_id]`, the number of signals that match the filters. With `filter[signal_id]`, the number of investigations of that signal. Pages past the last page return 0. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "attributes": { "created_at": "2026-10-30T14:02:40Z", "is_latest": true, "rule_id": "abc-def-ghi", "signal": { "severity": "medium", "sources": [ "okta" ], "tactic": "TA0001-initial-access", "tags": [ "source:okta" ], "technique": "T1078-valid-accounts", "timestamp": "2026-10-30T14:02:11Z", "title": "Unusual login location for a user" }, "signal_id": "AQAAAaGNHjq4XzqcIQAAAABBWm8xY0wybUFBQmNYSjl1QUFBQUFBQUE", "state": "completed", "updated_at": "2026-10-30T14:15:02Z", "verdict": "benign" }, "id": "7f3c9a2e-5d14-4e8b-9c61-2a0b4f8d1e53", "type": "investigations" } ], "meta": { "reason": "investigation_not_started", "total_count": 1 } } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="400" %} Bad Request {% tabs %} {% tab label="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="403" %} Forbidden {% tabs %} {% tab label="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/security_monitoring/security_agent/investigations" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}