Get Messages

GET

api

threads

{threadId}

messages

curl "https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50"

const response = await fetch(
  'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50'
);
const result = await response.json();

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

string

required

The unique thread identifier (UUID)

number

default:"100"

Maximum number of messages to return

string

Return messages before this message ID (for pagination)

string

Return messages after this message ID (for pagination)

boolean

default:"false"

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

array

required

Array of message objects

boolean

required

Whether more messages exist beyond the current page

Message Object

string

required

Unique message identifier

string

required

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

string | null

required

Message content (null for tool calls without text)

string | null

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

string | null

JSON string of tool calls made by assistant

string | null

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

number

required

Unix timestamp in milliseconds

string

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

number

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

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)

string | null

Subagent reference UUID associated with this message (when present)

string | null

Projected child agent name from parent registry

string | null

Projected child agent title from parent registry

string | null

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

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"

const response = await fetch(
  'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50'
);
const result = await response.json();

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

curl "https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50"

const response = await fetch(
  'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages?limit=50'
);
const result = await response.json();

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

Threads

Messages

File System

Define Utilities

WebSocket

Message Object

​Message Object

Message Object