---
title: "List Items"
method: GET
path: "/workspaces/{workspace_id}/inbox/items"
tags: ["inbox"]
---

# List Items

`GET /workspaces/{workspace_id}/inbox/items`

## Request

- Base URL: `https://platform.tracecat.com/api`
- URL: `https://platform.tracecat.com/api/workspaces/{workspace_id}/inbox/items`
- Auth: API key in cookie `fastapiusersauth`

List inbox items with cursor-based pagination.

Supports sorting by created_at or updated_at.
Default sort is by created_at descending.
Filtering by case requires the case add-ons entitlement.

## Path parameters

- `workspace_id` string, uuid, required

## Query parameters

- `limit` integer
- `cursor` string, nullable
- `reverse` boolean
- `order_by` 'created_at' | 'updated_at', nullable: Column name to order by (created_at, updated_at)
- `sort` 'asc' | 'desc', nullable: Sort direction (asc or desc)
- `search` string, nullable: Case-insensitive search on item title
- `case_id` string, uuid, nullable: Filter items to root sessions associated with this case
- `group` 'review_required' | 'running' | 'error' | 'completed': Display groups for inbox items. Groups are derived from approval state and live workflow execution status, so membership cannot be expressed as a pure SQL filter.
- `entity_type` 'case' | 'agent_preset' | 'agent_preset_builder' | 'copilot' | 'workflow' | 'approval' | 'external_channel': The type of entity associated with an agent session. Determines the context and behavior of the session: - CASE: Chat attached to a Case entity for investigation - AGENT_PRESET: Live chat testing a preset configuration - AGENT_PRESET_BUILDER: Builder chat for editing/configuring a preset - WORKSPACE_CHAT: Workspace-level chat assistant (wire value: copilot) - WORKFLOW: Workflow-initiated agent run (from action) - APPROVAL: Inbox approval continuation (hidden from main chat list) - EXTERNAL_CHANNEL: External channel session (e.g. Slack thread)
- `created_after` string, date-time, nullable: Only items created at or after this time (ISO 8601)
- `updated_after` string, date-time, nullable: Only items updated at or after this time (ISO 8601)

## Response `200`

Successful Response

- CursorPaginatedResponseInboxItemRead
  - `items` InboxItemRead[], required
    - `id` string, uuid, required: Unique inbox item ID
    - `type` 'approval' | 'agent_run', required: Types of inbox items.
    - `title` string, required: Display title
    - `preview` string, required: Preview text
    - `status` 'pending' | 'completed' | 'failed', required: Status of inbox items.
    - `unread` boolean, required: Whether the item is unread
    - `created_at` string, date-time, required: Creation timestamp
    - `updated_at` string, date-time, required: Last update timestamp
    - `workflow` WorkflowSummary: Summary of a workflow for inbox item context.
      - `id` string, uuid, required: Workflow ID
      - `title` string, required: Workflow title
      - `alias` string, nullable: Workflow alias
    - `created_by` UserSummary: Summary of a user for inbox item context.
      - `id` string, uuid, required: User ID
      - `email` string, required: User email
      - `first_name` string, nullable: User first name
      - `last_name` string, nullable: User last name
    - `source_id` string, uuid, required: ID of the source entity
    - `source_type` string, required: Type of source entity (e.g., agent_session)
    - `metadata` object, nullable: Type-specific metadata
  - `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)