Skip to main content
GET
/
api
/
threads
/
{threadId}
/
messages
curl "https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50"

{
  "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
}
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
​
before
string
Return messages before this message ID (for pagination)
​
after
string
Return messages after this message ID (for pagination)
​
includeSilent
boolean
default:"false"
Include silent messages (used for lifecycle/status/subagent communication)
​
messages
array
required
Array of message objects
​
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[].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 milliseconds
​
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
  • 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
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.
curl "https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50"

{
  "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
}