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

- threadId (string), required

  The unique thread identifier (UUID)

* limit (number), default: 100

  Maximum number of messages to return

- offset (number), default: 0

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

* order (string), default: desc

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

- depth (number), default: 0

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

* ids (string)

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

- includeWorkblocks (boolean), default: false

  Set `true` to include related workblock messages in `ids` mode.

* includeSilent (boolean), default: false

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

- messages (array), required

  Array of message objects

* total (number), required

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

- hasMore (boolean), required

  Whether more messages exist beyond the current page

### Message Object

- messages\[].id (string), required

  Unique message identifier

* messages\[].role (string), required

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

- messages\[].content (string | null), required

  Message content (null for tool calls without text)

* messages\[].silent (boolean), required

  Whether the message is hidden from default reads and streams.

- messages\[].reasoning_content (string | null)

  Persisted reasoning text returned by the provider.

* messages\[].reasoning_details (string | null)

  Serialized provider reasoning details.

- messages\[].tool_status (string | null)

  Tool result status: `success` or `error`.

* messages\[].name (string | null)

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

- messages\[].tool_calls (string | null)

  JSON string of tool calls made by assistant

* messages\[].tool_call_id (string | null)

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

- messages\[].created_at (number), required

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

* messages\[].status (string)

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

- messages\[].depth (number)

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

* messages\[].attachments (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
  - `size` (number): Stored size in bytes
  - `width` (number): Image width (images only)
  - `height` (number): Image height (images only)

- messages\[].subagent_id (string | null)

  Subagent reference UUID associated with this message (when present)

* messages\[].subagent_name (string | null)

  Projected child agent name from parent registry

- messages\[].subagent_title (string | null)

  Projected child agent title from parent registry

* messages\[].subagent_status (string | null)

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

- messages\[].metadata (Record\<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.

```bash cURL
curl "https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50" \
  -H "Authorization: Bearer $STANDARD_AGENTS_API_KEY"
```

```typescript JavaScript
const response = await fetch(
  'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50',
  { headers: { Authorization: `Bearer ${token}` } }
);
const result = await response.json();
```

```json 200
{
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Here's a photo of the damaged item",
      "created_at": 1699900000000000,
      "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": 1699900001000000,
      "status": "completed",
      "name": "Support Agent"
    }
  ],
  "total": 2,
  "hasMore": false
}
```