---
title: "List Cases"
method: GET
path: "/workspaces/{workspace_id}/cases"
tags: ["cases"]
---

# List Cases

`GET /workspaces/{workspace_id}/cases`

## Request

- Base URL: `https://platform.tracecat.com/api`
- URL: `https://platform.tracecat.com/api/workspaces/{workspace_id}/cases`
- Auth: one of:
  - API key in cookie `fastapiusersauth`
  - HTTP bearer

List cases with default filtering and sorting options.

## Path parameters

- `workspace_id` string, uuid, required

## Query parameters

- `limit` integer: Maximum items per page
- `cursor` string, nullable: Cursor for pagination
- `reverse` boolean: Reverse pagination direction
- `order_by` 'created_at' | 'updated_at' | 'priority' | 'severity' | 'status' | 'tasks' | 'assignee' | 'tags', nullable: Column name to order by (e.g. created_at, updated_at, priority, severity, status, tasks, assignee, tags). Default: created_at
- `sort` 'asc' | 'desc', nullable: Direction to sort (asc or desc)
- `include_rows` boolean: Include linked table rows
- `field_ids` string[], nullable: Include only the requested custom field IDs
- `include_durations` boolean: Include case duration values
- `include_payload` boolean: Include case payload
- `payload_fields` string[], nullable: Return only these literal top-level payload keys, automatically including the subset regardless of include_payload. Dots are literal; nested values are returned whole. Missing keys are omitted and null values preserved. An empty list acts as omitted; an empty string selects the literal empty key.
- `include_count` boolean: Include the exact filtered total_estimate for compatibility. Set false when fetching aggregate counts separately; total_estimate will be null.
- `hierarchy` 'all' | 'top_level': Return every case, or only top-level cases without a parent.
- `payload_paths` string, nullable: JSON-encoded array of up to 100 object paths, e.g. [["alert","source","ip"]]. Each path contains 1 to 32 literal keys. Preserves nesting, combines with payload_fields, and includes the subset automatically. Selected parents include their whole value. Missing paths are omitted; nulls are preserved. Arrays can be selected whole, without index traversal. An empty list acts as omitted.

## Response `200`

Successful Response

- CursorPaginatedResponseCaseReadMinimal
  - `items` CaseReadMinimal[], required
    - `is_exact_match` boolean: This row is the promoted exact case reference.
    - `is_outside_filters` boolean: The promoted reference falls outside the filtered results.
    - `id` string, uuid, required
    - `short_id` string, required
    - `search_match` CaseSearchMatchRead: Bounded lexical metadata beside case fields; excerpts are untrusted text.
      - `score` number, nullable
      - `matched_columns` string[]
      - `excerpts` string[]
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `summary` string, required
    - `status` 'unknown' | 'new' | 'in_progress' | 'on_hold' | 'resolved' | 'closed' | 'other', required: Case status values aligned with OCSF Incident Finding status.
    - `priority` 'unknown' | 'low' | 'medium' | 'high' | 'critical' | 'other', required: Case priority values aligned with urgency levels. Values: UNKNOWN (0): No priority is assigned LOW (1): Application or personal procedure is unusable, where a workaround is available or a repair is possible MEDIUM (2): Non-critical function or procedure is unusable or hard to use causing operational disruptions with no direct impact on a service's availability. A workaround is available HIGH (3): Critical functionality or network access is interrupted, degraded or unusable, having a severe impact on services availability. No acceptable alternative is possible CRITICAL (4): Interruption making a critical functionality inaccessible or a complete network interruption causing a severe impact on services availability. There is no possible alternative OTHER (99): The priority is not normalized
    - `severity` 'unknown' | 'informational' | 'low' | 'medium' | 'high' | 'critical' | 'fatal' | 'other', required: Case severity values aligned with OCSF severity values. Values: UNKNOWN (0): The event/finding severity is unknown INFORMATIONAL (1): Informational message. No action required LOW (2): The user decides if action is needed MEDIUM (3): Action is required but the situation is not serious at this time HIGH (4): Action is required immediately CRITICAL (5): Action is required immediately and the scope is broad FATAL (6): An error occurred but it is too late to take remedial action OTHER (99): The event/finding severity is not mapped
    - `assignee` UserRead
      - `id` string, uuid, required
      - `email` string, email, required
      - `is_active` boolean
      - `is_superuser` boolean
      - `is_verified` boolean
      - `role` 'basic' | 'admin', required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `settings` object, required
    - `tags` CaseTagRead[]
      - `id` string, uuid, required
      - `name` string, required
      - `ref` string, required
      - `color` string, nullable, required
    - `dropdown_values` CaseDropdownValueRead[], required
      - `id` string, uuid, required
      - `definition_id` string, uuid, required
      - `definition_ref` string, required
      - `definition_name` string, required
      - `option_id` string, uuid, nullable
      - `option_label` string, nullable
      - `option_ref` string, nullable
      - `option_icon_name` string, nullable
      - `option_color` string, nullable
    - `rows` CaseTableRowRead[]
      - `id` string, uuid, required
      - `case_id` string, uuid, required
      - `table_id` string, uuid, required
      - `table_name` string, nullable
      - `row_id` string, uuid, required
      - `row_data` object, nullable
      - `is_row_available` boolean
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `durations` CaseDurationRead[], nullable
      - `definition_id` string, uuid, required: Identifier of the case duration definition generating this duration.
      - `start_event_id` string, uuid, nullable: Case event that started the duration, if available.
      - `end_event_id` string, uuid, nullable: Case event that ended the duration, if available.
      - `started_at` string, date-time, nullable: Timestamp when the duration began.
      - `ended_at` string, date-time, nullable: Timestamp when the duration ended.
      - `duration` string, duration, nullable: Total elapsed time between start and end timestamps.
      - `id` string, uuid, required
      - `case_id` string, uuid, required
    - `field_values` object, nullable
    - `payload` object, nullable
    - `num_tasks_completed` integer
    - `num_tasks_total` integer
    - `parent` CaseParentRead: Summary of a sub-case's parent case.
      - `id` string, uuid, required
      - `short_id` string, required
      - `summary` string, required
    - `num_sub_cases` integer, required
  - `next_cursor` string, nullable: Cursor for next page
  - `prev_cursor` string, nullable: Cursor for previous page
  - `has_more` boolean: Whether more items exist
  - `has_previous` boolean: Whether previous items exist
  - `total_estimate` integer, nullable: Estimated total count from table statistics

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tracecat/apis/tracecat-api.md) - [All operations](https://skmtc.dev/tracecat/apis/tracecat-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tracecat/apis/tracecat-api/revisions/2efdda25045f?raw)