TRtracecat
cases

Search Cases

Search cases with cursor-based pagination, filtering, and sorting.

get/workspaces/{workspace_id}/cases/search

Request

  • Base URL
    https://platform.tracecat.com/api
  • Auth
    • API key in cookie fastapiusersauth
    • or HTTP bearer

Path parameters

workspace_idstring uuid required

Query parameters

limitinteger

Maximum items per page

cursorstring nullable

Cursor for pagination

reverseboolean

Reverse pagination direction

search_termstring nullable

Text to search for in case summary, description, short ID, or case UUID

search_mode'full_text' | 'literal'

Explicit lexical modes; omitted table mode remains a legacy policy.

Explicit full_text or literal; omitted mode preserves legacy search.

search_columnsstring[] nullable

Selected text fields; omitted searches both.

short_idstring nullable

Search by exact case short ID (e.g. 42 or CASE-0042)

case_idstring uuid nullable

Filter by exact case UUID

promote_exact_matchboolean

Place a complete case reference first, even outside view filters. Workspace authorization and explicit identity/relationship constraints remain strict. Filtered counts exclude cases outside the view.

match_noneboolean

The ordinary filter population is empty; exact promotion may still match.

statusCaseStatus[] nullable

Filter by case status

priorityCasePriority[] nullable

Filter by case priority

severityCaseSeverity[] nullable

Filter by case severity

tagsstring[] nullable

Filter by tag IDs or slugs (matches cases with any of the tags)

dropdownstring[] nullable

Filter by dropdown values. Format: definition_ref:option_ref (AND across definitions, OR within)

start_timestring date-time nullable

Return cases created at or after this timestamp

end_timestring date-time nullable

Return cases created at or before this timestamp

updated_afterstring date-time nullable

Return cases updated at or after this timestamp

updated_beforestring date-time nullable

Return cases updated at or before this timestamp

assignee_idstring[] nullable

Filter by assignee ID or 'unassigned'

order_by'relevance' | 'created_at' | 'updated_at' | 'priority' | 'severity' | 'status' | 'tasks' | 'id' | 'short_id' | 'assignee' | 'tags'

Full-text defaults to relevance; legacy/literal defaults to created_at. Explicit columns preserve their ordering.

sort'asc' | 'desc' nullable

Direction to sort (asc or desc)

include_rowsboolean

Include linked table rows

field_idsstring[] nullable

Include only the requested custom field IDs

include_durationsboolean

Include case duration values

include_payloadboolean

Include case payload

payload_fieldsstring[] 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_countboolean

Include the exact filtered total_estimate for compatibility. Set false on all pages 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.

parent_idstring uuid nullable

Return only the sub-cases of this parent case

payload_pathsstring 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

Successful Response

next_cursorstring nullable

Cursor for next page

prev_cursorstring nullable

Cursor for previous page

has_moreboolean

Whether more items exist

has_previousboolean

Whether previous items exist

total_estimateinteger nullable

Estimated total count from table statistics

Changes

No recorded changes to this operation across all 1 revision of this API.