---
title: "List Bits Security Analyst investigations"
method: GET
path: "/api/v2/security_monitoring/security_agent/investigations"
tags: ["Bits Security Analyst"]
---

# List Bits Security Analyst investigations

`GET /api/v2/security_monitoring/security_agent/investigations`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/security_monitoring/security_agent/investigations`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `security_monitoring_signals_read`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/security_monitoring/security_agent/investigations/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Query parameters

- `filter[signal_id]` string
- `filter[title]` string
- `filter[from]` string
- `filter[to]` string
- `filter[verdict]` string
- `filter[state]` string
- `filter[rule_id]` string
- `filter[rule_type]` string
- `filter[signal_severity]` string
- `filter[signal_source]` string
- `filter[tags]` string
- `filter[entity]` string
- `sort` string
- `page[number]` integer
- `page[size]` integer

## Response `200`

OK

- SecurityAgentInvestigationsListResponse: A page of investigations.
  - `data` SecurityAgentInvestigationListItem[], required: The investigations on this page.
    - `attributes` SecurityAgentInvestigationListItemAttributes, required: Attributes of an investigation in a list. To get an investigation's full content, use the get investigation endpoint.
      - `created_at` string, date-time: When the investigation started.
      - `is_latest` boolean, required: Whether this is the latest investigation of the signal. Always true when `filter[signal_id]` isn't set.
      - `rule_id` string, required: ID of the detection rule that generated the signal. It can be empty while the investigation runs.
      - `signal` SecurityAgentInvestigationSignal: Summary of the signal the investigation is about.
        - `severity` string: Severity of the signal: `info`, `low`, `medium`, `high`, or `critical`.
        - `sources` string[]: Sources of the signal.
        - `tactic` string: MITRE ATT&CK tactic, from the signal's `tactic` tag.
        - `tags` string[]: Tags of the signal, written `key:value`.
        - `technique` string: MITRE ATT&CK technique, from the signal's `technique` tag.
        - `timestamp` string: Time the signal was generated.
        - `title` string: Title of the signal.
      - `signal_id` string, required: ID of the signal, in its V1 form.
      - `state` 'investigating' | 'completed' | 'failed', required: State of the investigation: `investigating` while it runs, `completed` after it has a result, or `failed` when it produced no result before its timeout.
      - `updated_at` string, date-time: When the investigation last changed.
      - `verdict` 'benign' | 'suspicious' | 'malicious': Verdict of the investigation. Only completed investigations have one.
    - `id` string, required: The ID of the investigation.
    - `type` 'investigations', required: Type of the investigation resource.
  - `meta` SecurityAgentInvestigationsListMeta, required: Metadata of a page of investigations.
    - `reason` 'investigation_not_started' | 'not_investigated' | 'rule_not_enabled' | 'signal_not_found' | 'org_not_activated': 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.
    - `total_count` integer, required: 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.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)