---
title: "Get Messages"
method: GET
path: "/api/chats/{chat_id}/messages"
tags: ["chats"]
---

# Get Messages

`GET /api/chats/{chat_id}/messages`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/chats/{chat_id}/messages`
- Auth: none declared

Keyset-paginated chat messages, newest window first (TOS-464).

Without ``before`` returns the most recent ``limit`` messages; pass the
previous response's ``next_cursor`` as ``before`` to load older history.
Returns 404 if the caller is not a participant, 400 on a malformed cursor.

## Path parameters

- `chat_id` string, uuid, required

## Query parameters

- `before` string, nullable
- `limit` integer
- `client_capabilities` string[], nullable

## Headers

- `x-impersonate-identity-id` string, nullable

## Response `200`

Successful Response

- MessageListResponse: A keyset-paginated page of messages (TOS-464). ``messages`` is ordered oldest→newest for display and windowed on the most recent messages. ``next_cursor`` is an opaque token for fetching the next (older) page; ``None`` means no older messages remain.
  - `messages` MessageResponse[]
    - `initial_response_terminal_status` 'failed' | 'canceled'
    - `initial_response_run_id` string, uuid, nullable
    - `metadata` object, nullable
    - `browser_timing` object, nullable
    - `server_duration_ms` integer, nullable
    - `response_charge` object, nullable
    - `id` string, uuid, required
    - `sender_id` string, uuid, nullable, required
    - `sender_display_name` string, nullable, required
    - `sender_kind` string, nullable, required
    - `provider_capture` union
      - CalendarCapture
        - `kind` 'calendar_event'
        - `calendar_id` string, required
        - `event_id` string, required
        - `title` string, required
        - `status` string
        - `start` CalendarWhen
          - `date` string, nullable
          - `dateTime` string, nullable
          - `timeZone` string, nullable
        - `end` CalendarWhen
          - `date` string, nullable
          - `dateTime` string, nullable
          - `timeZone` string, nullable
        - `location` string, nullable
        - `organizer` CalendarPerson
          - `email` string, nullable
          - `displayName` string, nullable
          - `responseStatus` string, nullable
        - `attendees` CalendarPerson[]
          - `email` string, nullable
          - `displayName` string, nullable
          - `responseStatus` string, nullable
        - `recurrence` string[]
        - `recurring_event_id` string, nullable
        - `original_start_time` CalendarWhen
          - `date` string, nullable
          - `dateTime` string, nullable
          - `timeZone` string, nullable
        - `updated` string, nullable
        - `sequence` integer, nullable
        - `source_url` string, nullable
      - GmailCapture
        - `kind` 'gmail_message'
        - `message_id` string, required
        - `thread_id` string, nullable
        - `subject` string, required
        - `from_address` string, nullable
        - `to` string, nullable
        - `cc` string, nullable
        - `bcc` string, nullable
        - `source_url` string, nullable
    - `capture_author_key` string, nullable
    - `capture_author_kind` string, nullable
    - `sender_avatar_url` string, nullable, required
    - `sent_via` string, nullable
    - `role` string, required
    - `content` string, required
    - `model` string, nullable, required
    - `provider` string, nullable, required
    - `revised_at` string, date-time, nullable, required
    - `created_at` string, date-time, nullable, required
    - `input_tokens` integer, nullable
    - `output_tokens` integer, nullable
    - `cache_read_tokens` integer, nullable
    - `cache_creation_tokens` integer, nullable
    - `cost_usd` number, nullable
    - `cost_status` string
    - `attachments` AttachmentResponse[]
      - `id` string, uuid, required
      - `file_name` string, required
      - `file_type` string, required
      - `mime_type` string, required
      - `file_size_bytes` integer, nullable, required
      - `created_at` string, date-time, nullable, required
      - `generation_type` 'document' | 'image' | 'code', nullable
      - `capture_source` 'glance_auto' | 'embed_page' | 'app_page' | 'shared_tab' | 'shared_window' | 'shared_screen' | 'camera', nullable
      - `code` CodeAttachmentInfo: The ``code`` metadata block for a generate_code_file attachment (TOS-7015).
        - `language` string, required
        - `line_count` integer, required
        - `run_command` string, nullable
        - `group_size` integer, required
        - `previous_attachment_id` string, uuid, nullable
    - `interaction_prompts` InteractionPrompt[]
      - `id` string, required
      - `kind` 'choice' | 'multi' | 'text' | 'scale', required
      - `heading` string, nullable
      - `options` InteractionOption[], required
        - `id` string, required
        - `label` string, required
        - `value` string, required
      - `min` integer, nullable
      - `max` integer, nullable
      - `interaction_source` string, nullable
    - `show_request` ShowRequestResponse
      - `kind` 'screen' | 'object', required
      - `capabilities` string[], required
    - `interaction_answers` InteractionAnswer[]
      - `interaction_id` string, required
      - `heading` string, nullable
      - `kind` 'choice' | 'multi' | 'text' | 'scale', required
      - `labels` string[], required
      - `value` union, required
        - string
        - string[]
    - `mcp_tool_call_traces` McpToolCallTrace[]
      - `trace_id` string, required
      - `tool_name` string, required
      - `tool_label` string
      - `source_label` string, nullable
      - `duration_ms` integer, nullable
      - `registration_id` string, nullable
      - `success` boolean
      - `error_kind` string, nullable
      - `response_status` integer, nullable
      - `response_is_error` boolean, nullable
      - `phase_timings_ms` object
      - `request_target` string, nullable
    - `mcp_auth_failures` McpAuthFailure[]
      - `registration_id` string, required
      - `registration_name` string, required
      - `registration_owner_identity_id` string, required
      - `invoking_identity_id` string, required
      - `credential_target_identity_id` string, nullable
      - `auth_kind` string, required
      - `upstream_status` integer, nullable
      - `error_message` string, nullable
      - `tool_name` string, nullable
      - `trace_id` string, nullable
      - `failure_kind` string
      - `connect_definition_id` string, nullable
      - `connect_name` string, nullable
      - `connect_instance_id` string, nullable
    - `concierge_guidance` ConciergeGuidanceAction[]
      - `kind` 'navigation' | 'highlight', required
      - `screen_id` string, required
      - `screen_name` string, required
      - `route` string, required
      - `target` string, required
      - `label` string, required
      - `reason` string
      - `requires_user_action` boolean
    - `training_receipts` TrainingReceiptCard[]
      - `tool_name` string, required
      - `operation_id` string, nullable
      - `source_message_id` string, nullable
      - `surface` string, nullable
      - `actor_identity_id` string, required
      - `actor_display_name` string, nullable
      - `teacher_identity_id` string, required
      - `teacher_display_name` string, nullable
      - `target_identity_id` string, required
      - `target_display_name` string, nullable
      - `destination` 'shared' | 'private' | 'none', required
      - `destination_library_id` string, nullable
      - `status` string, required
      - `write_status` string, nullable
      - `document_count` integer
      - `mind_status` string, required
      - `source_kind` 'text' | 'website', required
      - `source_url` string, nullable
      - `reason_codes` string[]
      - `detail` string, nullable
      - `imported_count` integer, nullable
      - `skipped_count` integer, nullable
      - `failed_count` integer, nullable
      - `remaining_count` integer, nullable
      - `generated_summary` boolean
    - `connection_checks` ConnectionCheckCard[]
      - `subject_identity_id` string, required
      - `subject_name` string, nullable
      - `viewer_identity_id` string, required
      - `checked_at` string, required
      - `counts` object, required
      - `groups` ConnectionCheckGroup[]
        - `connector` string, required
        - `name` string, required
        - `icon_url` string, nullable
        - `definition_id` string, nullable
        - `status` 'working' | 'limited' | 'broken', required
        - `connections` ConnectionCheckConnection[]
          - `instance_id` string, required
          - `account` string, required
          - `status` 'working' | 'limited' | 'broken', required
          - `label` string, required
          - `reason` string, nullable
          - `next_action` string, nullable
          - `can_repair` boolean
          - `tested_now` boolean
          - `last_tested_at` string, nullable
          - `affected_agents` string[]
    - `provenance` MessageProvenance
      - `origin` string, required
      - `delegated_source` MessageDelegatedSource
        - `kind` string, required
        - `label` string, nullable
        - `invocation_id` string, nullable
        - `api_key_id` string, nullable
        - `transport` string, nullable
      - `subconscious_source` MessageSubconsciousSource: TOS-424/TOS-581: the conversation (and message) an ambient ask came from.
        - `chat_id` string, required
        - `label` string, required
        - `message_id` string, nullable
    - `artifacts` union[]
      - union
        - LineChartArtifact
          - `chart_type` 'line', required
          - `payload` LineChartPayloadResponse, required
            - `title` string, required
            - `x_label` string, required
            - `y_label` string, required
            - `series` LineSeries[], required
              - …
            - `reference_lines` ReferenceLine[]
              - …
            - `y_scale` string
            - `value_format` ValueFormat: Mirrors ``services.artifacts.schema.ValueFormat`` (TOS-434). Kept in lockstep with the request schema; a field missing here is silently stripped from the API response and never reaches the renderer.
              - …
        - BarChartArtifact
          - `chart_type` 'bar', required
          - `payload` BarChartPayloadResponse, required
            - `title` string, required
            - `x_label` string, required
            - `y_label` string, required
            - `categories` string[], required
            - `series` BarSeries[], required
              - …
            - `stacked` boolean
            - `reference_lines` ReferenceLine[]
              - …
            - `y_scale` string
            - `value_format` ValueFormat: Mirrors ``services.artifacts.schema.ValueFormat`` (TOS-434). Kept in lockstep with the request schema; a field missing here is silently stripped from the API response and never reaches the renderer.
              - …
        - AreaChartArtifact
          - `chart_type` 'area', required
          - `payload` AreaChartPayloadResponse, required
            - `title` string, required
            - `x_label` string, required
            - `y_label` string, required
            - `series` LineSeries[], required
              - …
            - `stacked` boolean
            - `reference_lines` ReferenceLine[]
              - …
            - `y_scale` string
            - `value_format` ValueFormat: Mirrors ``services.artifacts.schema.ValueFormat`` (TOS-434). Kept in lockstep with the request schema; a field missing here is silently stripped from the API response and never reaches the renderer.
              - …
        - ScatterChartArtifact
          - `chart_type` 'scatter', required
          - `payload` ScatterChartPayloadResponse, required
            - `title` string, required
            - `x_label` string, required
            - `y_label` string, required
            - `points` ScatterPoint[], required
              - …
            - `y_scale` string
            - `value_format` ValueFormat: Mirrors ``services.artifacts.schema.ValueFormat`` (TOS-434). Kept in lockstep with the request schema; a field missing here is silently stripped from the API response and never reaches the renderer.
              - …
            - `x_format` ValueFormat: Mirrors ``services.artifacts.schema.ValueFormat`` (TOS-434). Kept in lockstep with the request schema; a field missing here is silently stripped from the API response and never reaches the renderer.
              - …
        - RadarChartArtifact
          - `chart_type` 'radar', required
          - `payload` RadarChartPayloadResponse, required
            - `title` string, required
            - `categories` string[], required
            - `series` BarSeries[], required
              - …
            - `y_scale` string
            - `value_format` ValueFormat: Mirrors ``services.artifacts.schema.ValueFormat`` (TOS-434). Kept in lockstep with the request schema; a field missing here is silently stripped from the API response and never reaches the renderer.
              - …
        - DonutChartArtifact
          - `chart_type` 'donut', required
          - `payload` DonutChartPayloadResponse, required
            - `title` string, required
            - `slices` DonutSlice[], required
              - …
            - `value_format` ValueFormat: Mirrors ``services.artifacts.schema.ValueFormat`` (TOS-434). Kept in lockstep with the request schema; a field missing here is silently stripped from the API response and never reaches the renderer.
              - …
        - TableArtifact
          - `chart_type` 'table', required
          - `payload` TableArtifactPayloadResponse, required
            - `title` string, required
            - `columns` union[], required
              - …
            - `rows` array[], required
              - …
            - `default_sorts` TableSort[]
              - …
            - `summary` TableSummaryStat[]
              - …
            - `notes` string[]
        - IframeEmbedArtifact: An externally-hosted embed (e.g. a completed integration job's playable output) rendered inline via an iframe, rather than a chart rendered from a data payload. TOS-3689 Task 6.
          - `chart_type` 'iframe-embed', required
          - `url` string, required
          - `title` string, nullable
          - `poster` string, nullable
          - `actions` EmbedAction[]
            - `label` string, required
            - `url` string, required
          - `refresh` EmbedRefresh
            - `name` string, required
            - `arguments` object
          - `registration_id` string, nullable
        - UiArtifact: A declarative UI panel an agent sent with emit_ui (TOS-2341). The payload reuses the tool's own strict model, so the API can never emit a block the tool would have rejected.
          - `chart_type` 'ui', required
          - `payload` UiPayload, required: The whole ``emit_ui`` argument object, persisted verbatim as the payload.
            - `title` string, nullable
            - `blocks` union[], required
              - …
        - UiActionArtifact: A press of a panel button, stored on the pressing message (TOS-2341 Phase 2). Built server-side from the stored panel, so ``label`` and ``action`` are exactly what the button said, whoever pressed it.
          - `chart_type` 'ui_action', required
          - `message_id` string, uuid, required
          - `action_id` string, required
          - `label` string, required
          - `action` union, required
            - UiReplyAction: Send ``text`` as the viewer's own chat message.
              - …
            - UiToolAction: Ask the panel's author agent to call ``name`` with ``arguments``. Pressing it executes nothing. It records the press on the pressing message, and the agent that authored the panel then makes the call itself, under its own tool permissions and approval gates (TOS-2341 Phase 2). A button can therefore never reach a tool its author could not already call, and a person clicking it grants no new authority.
              - …
        - McpAppArtifact: A connected server's MCP Apps widget, shown after its tool ran (TOS-2341 Phase 4).
          - `chart_type` 'mcp_app', required
          - `registration_id` string, required
          - `tool_name` string, required
          - `upstream_tool` string, required
          - `resource_uri` string, required
          - `title` string, required
          - `arguments` object
          - `result` object
    - `ui_state` object
    - `result_blocks` ResultBlockResponse[]
      - `kind` 'artifact' | 'create-document' | 'generate-image' | 'edit-document' | 'unknown', required
      - `title` string, required
      - `body` string, required
    - `my_feedback` string, nullable
    - `can_delete` boolean
    - `compression_summary` CompressionSummaryResponse
      - `messages_compressed` integer, required
      - `summary_model` string, required
    - `reply_to` MessageReplyToResponse: TOS-6892 quote card: the message a ``MessageResponse`` replies to. ``excerpt`` is a UI-only preview (mentions projected to plain ``@Name``, simple markdown stripped, capped at 200 chars) - never what an agent's prompt sees. ``deleted=True`` means the original was soft-deleted after this reply was sent; ``excerpt`` is then empty and the client renders "Message deleted" instead of a clickable card.
      - `message_id` string, uuid, required
      - `sender_id` string, uuid, nullable, required
      - `sender_display_name` string, nullable, required
      - `sender_kind` string, nullable, required
      - `capture_author_key` string, nullable
      - `capture_author_kind` string, nullable
      - `excerpt` string, required
      - `created_at` string, date-time, nullable, required
      - `deleted` boolean
    - `system_event` SystemEventResponse: Parsed view of a role='system' chat event. The raw ``metadata_`` dict is flat; participant events nest the actor/subject sides, while context compaction exposes the durable summary row it references.
      - `kind` 'participant_added' | 'participant_removed' | 'participant_left' | 'participants_added_batch' | 'direct_chat_converted' | 'context_compacted' | 'conversation_catchup' | 'autopilot_paused', required
      - `actor` SystemEventParticipant: One side (actor or subject) of a participant lifecycle event.
        - `id` string, uuid, required
        - `kind` 'person' | 'agent', required
        - `name_at_event` string, required
      - `subject` SystemEventParticipant: One side (actor or subject) of a participant lifecycle event.
        - `id` string, uuid, required
        - `kind` 'person' | 'agent', required
        - `name_at_event` string, required
      - `subjects` SystemEventParticipant[], nullable
        - `id` string, uuid, required
        - `kind` 'person' | 'agent', required
        - `name_at_event` string, required
      - `room_title` string, nullable
      - `room_description` string, nullable
      - `summary_message_id` string, uuid, nullable
      - `owner_identity_id` string, uuid, nullable
      - `source_message_count` integer, nullable
      - `covered_message_start_id` string, uuid, nullable
      - `covered_message_end_id` string, uuid, nullable
      - `summary_model` string, nullable
      - `summary_provider` string, nullable
      - `summary_model_run_id` string, uuid, nullable
      - `validation_status` string, nullable
      - `fallback_used` boolean, nullable
      - `summary_text` string, nullable
      - `catchup_text` string, nullable
      - `fact_ledger` FactLedgerEntryResponse[]
        - `key` string, required
        - `value` string, required
      - `pause_reason` 'identity_auto_send_limit' | 'conversation_loop_guard' | 'loop_guard_n_consecutive' | 'time_budget_exhausted' | 'agent_mode_expired', nullable
      - `identity_auto_sends` integer, nullable
      - `auto_send_limit` integer, nullable
      - `conversation_non_human` integer, nullable
      - `conversation_loop_limit` integer, nullable
      - `consecutive_non_human` integer, nullable
      - `auto_reply_limit` integer, nullable
      - `auto_reply_window_seconds` integer, nullable
    - `read_receipts` ReadReceiptResponse[]
      - `identity_id` string, uuid, required
      - `display_name` string, required
      - `read_at` string, date-time, required
    - `automation_trigger` MessageAutomationTrigger
      - `kind` string, required
      - `label` string, required
      - `detail` string, nullable
      - `trigger_id` string, uuid, nullable
      - `run_id` string, uuid, nullable
      - `trigger_kind` string, nullable
      - `trigger_reason` string, nullable
      - `user_message_id` string, uuid, nullable
      - `occurred_at` string, date-time, nullable
    - `activity` object, nullable
    - `turn_job` object, nullable
    - `approval_resume` object, nullable
    - `room_turn_status` RoomTurnStatus
      - `activity_runs` object[]
      - `activity_runs_truncated` boolean
      - `status` string, required
      - `response_status_visible` boolean, required
      - `floor_control_mode` string, required
      - `routing_source` string, nullable
      - `selected` RoomTurnResponderStatus[]
        - `identity_id` string, uuid, nullable
        - `display_name` string, nullable
        - `kind` string, nullable
        - `state` string, required
        - `role_label` string, nullable
        - `code` string, nullable
        - `source` string, nullable
      - `invoked` RoomTurnResponderStatus[]
        - `identity_id` string, uuid, nullable
        - `display_name` string, nullable
        - `kind` string, nullable
        - `state` string, required
        - `role_label` string, nullable
        - `code` string, nullable
        - `source` string, nullable
      - `skipped` RoomTurnResponderStatus[]
        - `identity_id` string, uuid, nullable
        - `display_name` string, nullable
        - `kind` string, nullable
        - `state` string, required
        - `role_label` string, nullable
        - `code` string, nullable
        - `source` string, nullable
      - `availability` RoomTurnResponderStatus[]
        - `identity_id` string, uuid, nullable
        - `display_name` string, nullable
        - `kind` string, nullable
        - `state` string, required
        - `role_label` string, nullable
        - `code` string, nullable
        - `source` string, nullable
      - `budget_before` integer, nullable
      - `budget_after_selection` integer, nullable
      - `max_responders` integer, required
      - `max_chain_depth` integer, required
      - `top_k_claimants` integer, required
    - `turn_error` object, nullable
    - `answer_trace` object, nullable
    - `loop_exit_limitation` OperationLimitationResponse: A factual operational limit and safe recovery choices.
      - `explanation` string, required
      - `options` string[]
      - `coverage` string, nullable
    - `interim_segments` string[]
    - `auto_continue` AutoContinueChainResponse: TOS-2134: where this message sits in an automatic-continuation chain.
      - `chain_id` string, required
      - `index` integer, required
      - `max_follow_ups` integer, required
      - `state` string, required
      - `end_reason` string, nullable
      - `next_index` integer, nullable
      - `follow_up_run_id` string, nullable
      - `root_user_message_id` string, nullable
    - `submitted_by_mode` string
    - `suggestion_outcome` string, nullable
  - `next_cursor` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/5387b4ded614?raw)