# List investigations (with optional filtering, sorting, and search)

Returns a paginated list of investigations. By default, only completed investigations (state='success') are returned. Use query parameters to filter by state, outcomes, priorities, date ranges, and more.

## Authorizations

- **ApiKeyAuth**

## Query parameters

- **alert_create_from** string Optional  
  Filter by alert creation time (from). ISO 8601 format  
- **alert_create_until** string Optional  
  Filter by alert creation time (until). ISO 8601 format  
- **alert_start_from** string Optional  
  Filter by alert start time (from). ISO 8601 format (e.g., 2024-01-01 or 2024-01-01T00:00:00Z)  
- **alert_start_until** string Optional  
  Filter by alert start time (until). ISO 8601 format  
- **alert_tenants** string[] Optional  
  Filter by alert tenant name (can be repeated)  
- **alert_types** string[] Optional  
  Filter by alert type/handler key (can be repeated)  
- **attack_surfaces** string · enum[] Optional  
  Filter by attack surface (can be repeated)

### Show properties

- **direct_source_labels** string[] Optional  
  Filter by alert source label (can be repeated)  
- **feedback_updated_from** string Optional  
  Filter by feedback last updated time (from). ISO 8601 format  
- **feedback_updated_until** string Optional  
  Filter by feedback last updated time (until). ISO 8601 format  
- **insight_tag_names** string[] Optional  
  Filter by insight tag name (can be repeated)  
- **interview_statuses** string · enum[] Optional  
  Filter by interview status (can be repeated)

### Show properties

- **inv_complete_from** string Optional  
  Filter by investigation completion time (from). ISO 8601 format  
- **inv_complete_until** string Optional  
  Filter by investigation completion time (until). ISO 8601 format  
- **investigation_state** string · enum Optional  
  Filter by investigation state. Valid values: not_asked (queued), loading (running), success (complete), error (stopped). Defaults to 'success'.  
  Possible values: `error` `loading` `not_asked` `success`  
- **limit** integer Optional  
  Number of results per page  
- **mitre_tactics** string · enum[] Optional  
  Filter by MITRE ATT&CK tactic (can be repeated)

### Show properties

- **offset** integer Optional  
  Number of results to skip  
- **outcomes** string · enum[] Optional  
  Filter by investigation outcome/conclusion (can be repeated)

### Show properties

- **priorities** string · enum[] Optional  
  Filter by investigation priority (can be repeated)

### Show properties

- **priority_statuses** string[] Optional  
  Filter by priority status (can be repeated)  
- **search** string Optional  
  Free-text search across investigation fields  
- **sort_dir** string · enum Optional  
  Sort direction. Defaults to 'desc'.  
  Possible values: `asc` `desc`  
- **sort_type** string · enum Optional  
  Sort field. Defaults to 'alert_create'.  
  Possible values: `activity` `alert_create` `alert_source` `alert_title` `alert_type` `feedback_status` `investigation_create` `outcome` `priority_status` `stopped_reason`  
- **stopped_reasons** string[] Optional  
  Filter by stopped reason for error/canceled investigations (can be repeated)  
- **tenant_id** string Optional  
  Filter by tenant ID  
- **tenant_integration_key** string Optional  
  Filter by tenant integration key  
- **user_statuses** string · enum[] Optional  
  Filter by user feedback status (can be repeated)

### Show properties

## Responses

### 200

Paginated list of investigations

Use next and previous URLs in the response for easy page navigation.

**Response body**

application/json

{
      "count": 1,
      "next": "https://example.com",
      "previous": "https://example.com",
      "results": [
        {
          "alert": {
            "alert_type": "text",
            "assets": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "coalesce_key": "text",
            "create_time": "2026-07-28T03:44:00.113Z",
            "created_at": "2026-07-28T03:44:00.113Z",
            "direct_source_label": "text",
            "entities": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "id": 1,
            "origin_integration": "text",
            "origin_ticket_id": "text",
            "origin_ticket_id_label": "text",
            "origin_ticket_url": "text",
            "original_title": "text",
            "proxy_source_label": "text",
            "raw_alert_content": "text",
            "schema_key": "text",
            "severity": "text",
            "start_time": "2026-07-28T03:44:00.113Z",
            "tenant_id": "text",
            "tenant_integration_key": "text",
            "tenant_label": "text",
            "tenant_union": {
              "created_at": "2026-07-28T03:44:00.113Z",
              "display_name": "text",
              "id": 1,
              "lookup_dict": {
                "ANY_ADDITIONAL_PROPERTY": "anything"
              },
              "updated_at": "2026-07-28T03:44:00.113Z"
            },
            "title": "text",
            "updated_at": "2026-07-28T03:44:00.113Z"
          },
          "alert_summary": "text",
          "attack_surface": "text",
          "canceled": "CANCEL_MANUAL",
          "conclusion": "text",
          "conclusion_summary": "text",
          "created_at": "2026-07-28T03:44:00.113Z",
          "custom_outcome": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "error_msg": "text",
          "exec_summary": "text",
          "feedback": {
            "conclusion": "text",
            "conclusion_summary": "text",
            "created_at": "2026-07-28T03:44:00.113Z",
            "findings": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "findings_ranking": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "id": 1,
            "insight_tags": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "key_findings": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "outcome": "COMPLETED_BREACHED_CONFIRMED",
            "outcome_note": "text",
            "priority": "informational",
            "remediations_done": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "status": "in_review",
            "updated_at": "2026-07-28T03:44:00.113Z"
          },
          "findings": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "findings_ranking": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "generated_time": "2026-07-28T03:44:00.113Z",
          "id": 1,
          "ignored_for_investigation_id": 1,
          "insight_tags": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "interview_proposals": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "inv_url": "text",
          "key_findings": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "mitre_tactic": "text",
          "outcome": "COMPLETED_BREACHED_CONFIRMED",
          "priority": "informational",
          "recommended_remediations": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "remediation_action_runs": [
            {
              "entity": "text",
              "remediation_action": {
                "name": "text"
              }
            }
          ],
          "start_time": "2026-07-28T03:44:00.113Z",
          "status": "not_asked",
          "updated_at": "2026-07-28T03:44:00.113Z"
        }
      ]
    }

### Errors

### 400

Bad request - invalid input

### 401

Unauthorized

### 403

Access denied

### 500

System error

### 503

System not ready for requests

## Create a new alert investigation

Creates a new alert investigation, returning `investigation_id`. Returns existing id if alert already exists (unless `force_reinvestigation=True`). Then use `GET /app/api/v1/investigation/{investigation_id}` for updates.

## Authorizations

- **ApiKeyAuth**

## Body

- **force_reinvestigation** boolean Optional  
  Default: `false`  
- **raw_alert_content** object Optional  
- **schema_key** string Optional  
- **tenant_union_id** number · nullable Optional  
  Default: `null`

## Responses

### 200

Existing investigation found

**Response body**

application/json

{
      "investigation_id": 1
    }

### 201

New investigation created

### Errors

### 400

Bad request - invalid input

### 401

Unauthorized

### 403

Access denied

### 422

Alert skipped due to missing data (e.g., propagation delay)

### 500

System error

### 503

System not ready for requests
  
## Get an alert investigation

Returns an alert investigation.

## Authorizations

- **ApiKeyAuth**

## Path parameters

- **investigation_id** string Required

## Responses

### 200

Investigation data object. For progress: investigation.status=

**Response body**

application/json

{
      "alert": {
        "alert_type": "text",
        "assets": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "coalesce_key": "text",
        "create_time": "2026-07-28T03:44:00.113Z",
        "created_at": "2026-07-28T03:44:00.113Z",
        "direct_source_label": "text",
        "enrich_result": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "entities": [
          {
            "type": "text",
            "value": "text"
          }
        ],
        "handler_version": "v1",
        "id": 1,
        "origin_integration": "text",
        "origin_integration_display_name": "text",
        "origin_ticket_id": "text",
        "origin_ticket_id_label": "text",
        "origin_ticket_url": "text",
        "original_title": "text",
        "proxy_source_label": "text",
        "raw_alert_content": "text",
        "schema_key": "text",
        "severity": "text",
        "start_time": "2026-07-28T03:44:00.113Z",
        "tenant_id": "text",
        "tenant_integration_key": "text",
        "tenant_label": "text",
        "tenant_union": {
          "created_at": "2026-07-28T03:44:00.113Z",
          "display_name": "text",
          "id": 1,
          "last_modified_by": {
            "email": "name@gmail.com",
            "first_name": "text",
            "id": 1,
            "last_name": "text",
            "oidc_user_id": "text",
            "role": "admin"
          },
          "lookup_dict": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "updated_at": "2026-07-28T03:44:00.113Z"
        },
        "title": "text",
        "updated_at": "2026-07-28T03:44:00.113Z"
      },
      "alert_summary": "text",
      "attack_surface": "text",
      "backfill": 1,
      "canceled": "CANCEL_MANUAL",
      "conclusion": "text",
      "conclusion_summary": "text",
      "created_at": "2026-07-28T03:44:00.113Z",
      "email_screenshot": "text",
      "error_msg": "text",
      "exec_summary": "text",
      "findings": [
        {
          "artifacts": [
            "text"
          ],
          "evidences": [
            {
              "data": "text",
              "evidence_type": "text",
              "tag": "text"
            }
          ],
          "finding": "text",
          "headline": "text",
          "outcome": "COMPLETED_BREACHED_CONFIRMED"
        }
      ],
      "findings_ranking": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "generated_time": "2026-07-28T03:44:00.113Z",
      "id": 1,
      "ignored_for": 1,
      "insight_tags": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "interview_proposals": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "inv_url": "text",
      "is_retried": true,
      "key_findings": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "mitre_tactic": "text",
      "outcome": "COMPLETED_BREACHED_CONFIRMED",
      "priority": "informational",
      "ready": true,
      "recommended_remediations": [
        "text"
      ],
      "related_alert_hypothesis": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "start_time": "2026-07-28T03:44:00.113Z",
      "status": "not_asked",
      "updated_at": "2026-07-28T03:44:00.113Z"
    }

### Errors

### 401

Unauthorized

### 403

Access denied

### 404

Resource not found

### 500

System error

### 503

System not ready for requests

Last updated 8 months ago