View as MarkdownPlain text for this page Open in ChatGPTQuestions about this page Open in ClaudeQuestions about this page

Get Messages

GET/api/threads/{threadId}/messages

Retrieves all messages in a thread. Messages queued by sendMessage() or queueMessage() that have not yet been injected into stored history are included as pending messages with metadata.queued: true.

threadIdstringrequired

The unique thread identifier (UUID)

limitnumberdefault: 100

Maximum number of messages to return

offsetnumberdefault: 0

Number of messages to skip from the start of the selection.

orderstringdefault: desc

desc selects the newest messages first. asc selects the oldest messages first. The response array is chronological in both cases.

depthnumberdefault: 0

Maximum message depth to include. 0 includes top-level messages.

idsstring

Comma-separated message IDs to fetch directly. This mode replaces pagination.

includeWorkblocksbooleandefault: false

Set true to include related workblock messages in ids mode.

includeSilentbooleandefault: false

Include silent messages (used for lifecycle/status/subagent communication)

messagesarrayrequired

Array of message objects

totalnumberrequired

Number of messages that match the silent and depth filters before pagination. In ids mode, this is the number of returned messages.

hasMorebooleanrequired

Whether more messages exist beyond the current page

Message Object

messages[].idstringrequired

Unique message identifier

messages[].rolestringrequired

Message role: "system", "user", "assistant", or "tool"

messages[].contentstring | nullrequired

Message content (null for tool calls without text)

messages[].silentbooleanrequired

Whether the message is hidden from default reads and streams.

messages[].reasoning_contentstring | null

Persisted reasoning text returned by the provider.

messages[].reasoning_detailsstring | null

Serialized provider reasoning details.

messages[].tool_statusstring | null

Tool result status: success or error.

messages[].namestring | null

Display name (e.g., agent label for assistant messages)

messages[].tool_callsstring | null

JSON string of tool calls made by assistant

messages[].tool_call_idstring | null

ID linking tool result to its call (for tool role messages)

messages[].created_atnumberrequired

Unix timestamp in microseconds. For a JavaScript date, use new Date(message.created_at / 1000).

messages[].statusstring

Message status: "pending", "completed", or "failed". Queued messages are returned as "pending".

messages[].depthnumber

Nesting depth for sub-prompt messages (0 for top-level)

messages[].attachmentsarray | null

Array of file attachments. Each attachment object:

id (string): Unique attachment identifier
type (string): Always "file"
path (string): File path in thread storage (e.g., /attachments/123-abc.jpg)
name (string): Original filename
mimeType (string): MIME type
size (number): Stored size in bytes
width (number): Image width (images only)
height (number): Image height (images only)

messages[].subagent_idstring | null

Subagent reference UUID associated with this message (when present)

messages[].subagent_namestring | null

Projected child agent name from parent registry

messages[].subagent_titlestring | null

Projected child agent title from parent registry

messages[].subagent_statusstring | null

Projected child runtime status (e.g. running, idle, terminated, or custom)

messages[].metadataRecord<string, unknown>

Message metadata. The field is absent when the message has no metadata. Runtime lifecycle markers may appear here (for example status_kind). Queued messages include queued: true, queue_status: "queued", and queue_source until they are injected into stored history.