---
title: "Get Messages"
method: GET
path: "/v1/omni-ai/threads/{thread_id}/messages"
tags: ["Omni AI"]
---

# Get Messages

`GET /v1/omni-ai/threads/{thread_id}/messages`

## Request

- Base URL: `https://api.clearstreet.com`
- URL: `https://api.clearstreet.com/v1/omni-ai/threads/{thread_id}/messages`
- Auth: HTTP bearer

List finalized messages, including messages created before the account link.
Return the latest page by default, in chronological order within each page.
Use the returned page token to navigate history.

In-progress assistant output is not included. Poll
`GET /omni-ai/threads/{thread_id}/response` and refresh messages when a
response ends to read its finalized message here. Some answers start
without a request: a response with no `user_message_id` presents a
background result, such as a subagent's report, so keep polling the thread
response while the thread is open rather than only after sending a message.

Hide assistant messages with outcome `merged`. They have no content, and a
later answer covers their turn.

## Path parameters

- `thread_id` string, uuid, required

## Query parameters

- `account_id` integer
- `page_size` integer
- `page_token` string, byte: Base64URL-encoded pagination token

## Response `200`

Paginated list of finalized messages; latest page by default, chronological within each page

- object
  - `error` ApiError: A direct mapping of tonic::Status, for use in HTTP responses.
    - `code` integer, required: The error code is used to identify the nature of the error. It corresponds to an HTTP status code.
    - `details` object[]
    - `message` string, required: A human-readable message providing more details about the error.
  - `metadata` ResponseMetadata, required: Metadata for the response. This will always contain a request ID which can be used to identify the request to Clear Street for tracing, and optionally may include pagination data.
    - `next_page_token` string, byte, nullable: Base64URL-encoded pagination token
    - `page_number` integer, nullable: Pagination. Included if this was a GET (list) response
    - `previous_page_token` string, byte, nullable: Base64URL-encoded pagination token
    - `request_id` string, required: A unique ID for this request, generated upon ingestion of the request.
    - `total_items` integer, nullable: Total number of items available (not just in this page).
    - `total_pages` integer, nullable: Total number of pages available.
  - `data` Message[], required
    - `content` MessageContent, required: Finalized immutable message content container. Never includes thinking parts.
      - `parts` MessageContentPart[], required
        - union: Final immutable content part visible on persisted messages.
          - object: Text content part.
            - `text` string, required
            - `type` 'text', required
          - object: Structured action content part.
            - `action` union, required: Structured actions that Omni AI can return to clients. These actions provide machine-readable instructions for the client to execute, such as prefilling an order ticket, opening a chart, or navigating to a route.
              - …
            - `action_id` string, uuid, required
            - `clicked` boolean, required: Whether the current user clicked this action.
            - `clicked_item_ids` string[]: IDs of nested items clicked by the current user.
            - `item_id` string, uuid, nullable: Interaction-tracking identity. Absent on messages created before tracking. When a null/undefined value is observed, it indicates that there is no available data.
            - `type` 'structured_action', required
          - object: Chart payload content part.
            - `payload` ChartPayload, required: Typed chart payload rendered inline in assistant content.
              - …
            - `type` 'chart', required
          - object: Suggested actions payload content part.
            - `payload` SuggestedActionsPayload, required: Suggested follow-up buttons rendered at the end of an assistant message.
              - …
            - `type` 'suggested_actions', required
          - object: Escape-hatch custom payload content part.
            - `payload` object, required
            - `type` 'custom', required
    - `context` TurnContext: Client snapshots attached to one instant-chat user message. Context is separate from visible message text and does not grant account access. The compact JSON representation must not exceed 64 KiB.
      - `items` ContextItem[], required: One to four snapshots. Each snapshot's data may contain at most 32 levels of nesting.
        - `captured_at` string, date-time, nullable: Client-reported snapshot time. Omit when unknown.
        - `data` object, required: Relevant widget data, selections, and units. Use strings for exact decimals and large IDs.
        - `kind` string, required: Nonblank descriptive kind. New kinds do not require a backend release.
        - `label` string, required: Nonblank attachment label for conversation rendering.
    - `created_at` string, date-time, required
    - `error` ErrorStatus: Shared sanitized error payload.
      - `code` string, required: `FAILED`, or `execution_interrupted` when Omni lost the worker running the response; partial content is kept; send the message again.
      - `details` object, nullable: When a null/undefined value is observed, it indicates it does not apply.
      - `message` string, required
    - `id` string, uuid, required
    - `outcome` 'completed' | 'errored' | 'canceled' | 'steered' | 'merged', required: Immutable terminal outcome for a finalized assistant message. `steered`: the message is complete as written; the user sent a newer message before it finished. `merged`: the message has no content, and a later answer covers its turn. Hide `merged` messages.
    - `role` 'USER' | 'ASSISTANT', required: Finalized message role in the public contract.
    - `seq` integer, required
    - `thread_id` string, uuid, required

## Other responses

- `400`: Invalid request or supplied account ID
- `401`: Authentication required
- `403`: Caller lacks linked-account access
- `404`: Resource not found or not owned by caller
- `409`: Thread scope changed or conflicting retry; refresh before retrying
- `500`: Internal server error

## Changes

- **2026-11-04** `52e77ea7d731`: 2 warning
  - added the new `merged` enum value to the `allOf[subschema #2]/data/items/outcome` response property for the response status `200`
  - added the new `steered` enum value to the `allOf[subschema #2]/data/items/outcome` response property for the response status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/clear-street/apis/clear-street-trading-api/changes/v1/omni-ai/threads/:thread_id/messages/get.md)

---

[API](https://skmtc.dev/clear-street/apis/clear-street-trading-api.md) - [All operations](https://skmtc.dev/clear-street/apis/clear-street-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clear-street/apis/clear-street-trading-api/revisions/52e77ea7d731?raw)