> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standardagentbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get 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`.

<ParamField path="threadId" type="string" required>
  The unique thread identifier (UUID)
</ParamField>

<ParamField query="limit" type="number" default="100">
  Maximum number of messages to return
</ParamField>

<ParamField query="before" type="string">
  Return messages before this message ID (for pagination)
</ParamField>

<ParamField query="after" type="string">
  Return messages after this message ID (for pagination)
</ParamField>

<ParamField query="includeSilent" type="boolean" default="false">
  Include silent messages (used for lifecycle/status/subagent communication)
</ParamField>

<ResponseField name="messages" type="array" required>
  Array of message objects
</ResponseField>

<ResponseField name="hasMore" type="boolean" required>
  Whether more messages exist beyond the current page
</ResponseField>

### Message Object

<ResponseField name="messages[].id" type="string" required>
  Unique message identifier
</ResponseField>

<ResponseField name="messages[].role" type="string" required>
  Message role: `"system"`, `"user"`, `"assistant"`, or `"tool"`
</ResponseField>

<ResponseField name="messages[].content" type="string | null" required>
  Message content (null for tool calls without text)
</ResponseField>

<ResponseField name="messages[].name" type="string | null">
  Display name (e.g., agent label for assistant messages)
</ResponseField>

<ResponseField name="messages[].tool_calls" type="string | null">
  JSON string of tool calls made by assistant
</ResponseField>

<ResponseField name="messages[].tool_call_id" type="string | null">
  ID linking tool result to its call (for tool role messages)
</ResponseField>

<ResponseField name="messages[].created_at" type="number" required>
  Unix timestamp in milliseconds
</ResponseField>

<ResponseField name="messages[].status" type="string">
  Message status: `"pending"`, `"completed"`, or `"failed"`. Queued messages are returned as `"pending"`.
</ResponseField>

<ResponseField name="messages[].depth" type="number">
  Nesting depth for sub-prompt messages (0 for top-level)
</ResponseField>

<ResponseField name="messages[].attachments" type="array | 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
  * `width` (number): Image width (images only)
  * `height` (number): Image height (images only)
</ResponseField>

<ResponseField name="messages[].subagent_id" type="string | null">
  Subagent reference UUID associated with this message (when present)
</ResponseField>

<ResponseField name="messages[].subagent_name" type="string | null">
  Projected child agent name from parent registry
</ResponseField>

<ResponseField name="messages[].subagent_title" type="string | null">
  Projected child agent title from parent registry
</ResponseField>

<ResponseField name="messages[].subagent_status" type="string | null">
  Projected child runtime status (e.g. `running`, `idle`, `terminated`, or custom)
</ResponseField>

<ResponseField name="messages[].metadata" type="object | null">
  Message 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.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50"
  ```

  ```typescript JavaScript theme={null}
  const response = await fetch(
    'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50'
  );
  const result = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "content": "Here's a photo of the damaged item",
        "created_at": 1699900000000,
        "status": "completed",
        "attachments": [
          {
            "id": "att_abc123",
            "type": "file",
            "path": "/attachments/1699900000-abc123.jpg",
            "name": "damaged-item.jpg",
            "mimeType": "image/jpeg",
            "width": 2048,
            "height": 1536
          }
        ]
      },
      {
        "id": "msg_002",
        "role": "assistant",
        "content": "I can see the damage in your photo. I'll process a replacement for you.",
        "created_at": 1699900001000,
        "status": "completed",
        "name": "Support Agent"
      }
    ],
    "hasMore": false
  }
  ```
</ResponseExample>