--- title: Get a Bits Security Analyst investigation description: Get a Bits Security Analyst investigation by its ID, with its verdict, conclusion, evidence, steps, and response suggestions. breadcrumbs: Docs > API > Get a Bits Security Analyst investigation --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Get a Bits Security Analyst investigation ## 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/{investigation_id} | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/security_monitoring/security_agent/investigations/{investigation_id} | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/security_monitoring/security_agent/investigations/{investigation_id} | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/security_monitoring/security_agent/investigations/{investigation_id} | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/security_monitoring/security_agent/investigations/{investigation_id} | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/security_monitoring/security_agent/investigations/{investigation_id} | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/security_monitoring/security_agent/investigations/{investigation_id} | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/security_monitoring/security_agent/investigations/{investigation_id} | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/security_monitoring/security_agent/investigations/{investigation_id} | ### Overview Get a Bits Security Analyst investigation by its ID, with its verdict, conclusion, evidence, steps, and response suggestions. While the investigation is running, the response has a `Retry-After` header. 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 #### Path Parameters | Field | Type | Description | | ----------------------------- | ------ | ----------------------------------------------------- | | investigation_id [*required*] | string | The ID of the investigation, as returned by the list. | #### Query Strings | Field | Type | Description | | ---------------------- | ----- | ------------------------------------------------------------------ | | fields[investigations] | array | Attributes to return, comma-separated. Defaults to all attributes. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} An investigation. | Parent field | Field | Type | Description | | ----------------------- | ----------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | An investigation and its content. `attributes` is absent when `fields[investigations]` is empty or lists only attributes the investigation doesn't have. | | data | attributes | object | Attributes of an investigation. When `fields[investigations]` is set, only listed attributes are returned. Attributes the investigation doesn't have yet are absent. | | attributes | conclusion | string | Summary of the investigation's findings. | | attributes | created_at | date-time | When the investigation started. | | attributes | key_entities | object | The entities the investigation found, by role. | | key_entities | actors [*required*] | [object] | Entities that performed the activity. | | actors | sub_type | string | More specific type of the entity. | | actors | type [*required*] | string | Type of the entity, such as a user, a host, or an IP address. | | actors | value [*required*] | string | Value that identifies the entity. | | key_entities | targets [*required*] | [object] | Entities the activity was aimed at. | | targets | sub_type | string | More specific type of the entity. | | targets | type [*required*] | string | Type of the entity, such as a user, a host, or an IP address. | | targets | value [*required*] | string | Value that identifies the entity. | | attributes | key_evidence | [object] | The evidence the verdict rests on. | | key_evidence | category [*required*] | string | Category of the evidence. | | key_evidence | finding [*required*] | string | What the investigation found. | | key_evidence | source_steps | [string] | Names of the steps the evidence comes from. | | attributes | response_suggestions | object | Suggested responses to the signal. | | response_suggestions | mitigation_suggestions | [object] | Suggested mitigations, in the order to apply them. | | mitigation_suggestions | actions | [object] | Actions that apply the mitigation. | | actions | applied [*required*] | boolean | Whether the action has run. | | actions | applied_at | date-time | When the action ran. | | actions | applied_by | string | Who ran the action. | | actions | fqn | string | ID of the action in the Action Catalog. | | actions | id [*required*] | string | ID of the action. | | actions | name | string | Name of the action in the Action Catalog. | | actions | resource | string | The resource the action changes. | | actions | source [*required*] | string | Integration that runs the action, such as `dd`, `aws`, or `okta`. | | actions | source_connected [*required*] | boolean | Whether the organization has a connection that can run the action. | | actions | target | string | What the action targets. | | mitigation_suggestions | id [*required*] | string | ID of the mitigation. | | mitigation_suggestions | rationale [*required*] | string | Why the mitigation is suggested. | | mitigation_suggestions | recommended [*required*] | boolean | Whether the mitigation is recommended. | | mitigation_suggestions | scope_note | string | What the mitigation applies to. | | mitigation_suggestions | step [*required*] | int64 | Order in which to apply the mitigation, starting at 1. | | mitigation_suggestions | title [*required*] | string | Title of the mitigation. | | response_suggestions | rule_tuning_suggestions | object | Suggestions to tune the detection rule that generated the signal. | | rule_tuning_suggestions | occurrence_window_days [*required*] | int64 | Length of the window, in days. | | rule_tuning_suggestions | reasoning [*required*] | string | Why tuning the rule is suggested. | | rule_tuning_suggestions | rule_id [*required*] | string | ID of the detection rule. | | rule_tuning_suggestions | rule_name [*required*] | string | Name of the detection rule. | | rule_tuning_suggestions | rule_signal_total [*required*] | int64 | Number of signals the rule generated in the window. | | rule_tuning_suggestions | suggestions [*required*] | [object] | The tuning suggestions. | | suggestions | action_type [*required*] | string | Kind of change the suggestion makes to the rule. | | suggestions | conditions [*required*] | [object] | The conditions the change applies to. | | conditions | field [*required*] | string | Attribute the condition checks. | | conditions | value [*required*] | string | Value the attribute is compared with. | | suggestions | description [*required*] | string | What the suggestion changes. | | suggestions | estimated_silenced_count | int64 | Estimated number of signals the change would have silenced in the window. | | suggestions | id [*required*] | string | ID of the suggestion. | | suggestions | match_logic [*required*] | string | How the conditions combine, such as AND or OR. | | suggestions | recommended [*required*] | boolean | Whether the suggestion is recommended. | | suggestions | rule_id [*required*] | string | ID of the detection rule. | | suggestions | title [*required*] | string | Title of the suggestion. | | suggestions | warning [*required*] | string | What the change could hide. It can be empty. | | suggestions | why [*required*] | string | Why the suggestion is made. | | rule_tuning_suggestions | summary [*required*] | string | Summary of the suggestions. | | attributes | rule_id | string | ID of the detection rule that generated the signal. | | 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 | string | ID of the signal, in its V1 form. | | attributes | state | 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 | steps | [object] | The steps of the investigation, in order. | | steps | name [*required*] | string | Name of the step, usually the question it answers. | | steps | summary [*required*] | string | Summary of what the step found. It can be empty. | | 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`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "conclusion": "The login came from a location the user travels to regularly, on a known device.", "created_at": "2026-10-30T14:02:40Z", "key_entities": { "actors": [ { "sub_type": "okta_user", "type": "user", "value": "jane.doe@example.com" } ], "targets": [ { "sub_type": "okta_user", "type": "user", "value": "jane.doe@example.com" } ] }, "key_evidence": [ { "category": "Authentication", "finding": "The user logged in from the same country three times in the last 30 days.", "source_steps": [ "Has the user logged in from this location before?" ] } ], "response_suggestions": { "mitigation_suggestions": [ { "actions": [ { "applied": false, "applied_at": "2026-10-30T14:20:00Z", "applied_by": "john.smith@example.com", "fqn": "com.datadoghq.okta.suspend_user", "id": "action-1", "name": "Suspend user", "resource": "jane.doe@example.com", "source": "okta", "source_connected": true, "target": "jane.doe@example.com" } ], "id": "mitigation-1", "rationale": "Only needed if the user doesn't confirm the login.", "recommended": false, "scope_note": "jane.doe@example.com", "step": 1, "title": "Suspend the user" } ], "rule_tuning_suggestions": { "occurrence_window_days": 30, "reasoning": "Most signals from this rule in the last 30 days were benign travel.", "rule_id": "abc-def-ghi", "rule_name": "Unusual login location for a user", "rule_signal_total": 120, "suggestions": [ { "action_type": "create_suppression", "conditions": [ { "field": "@usr.device.id", "value": "4b8f2c1e-9a7d-4e3b-8c5f-1d2e3f4a5b6c" } ], "description": "Don't generate signals for logins from devices the user has used before.", "estimated_silenced_count": 85, "id": "suggestion-1", "match_logic": "AND", "recommended": true, "rule_id": "abc-def-ghi", "title": "Suppress logins from known devices", "warning": "A stolen known device would no longer trigger this rule.", "why": "The user's known devices accounted for most benign signals." } ], "summary": "The rule fires often for users who travel to known locations." } }, "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", "steps": [ { "name": "Has the user logged in from this location before?", "summary": "Three earlier logins from the same country, on the same device." } ], "updated_at": "2026-10-30T14:15:02Z", "verdict": "benign" }, "id": "7f3c9a2e-5d14-4e8b-9c61-2a0b4f8d1e53", "type": "investigations" } } ``` {% /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="404" %} Not Found {% 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 # Path parameters export investigation_id="7f3c9a2e-5d14-4e8b-9c61-2a0b4f8d1e53" # 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/${investigation_id}" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}