Get Thread

GET

api

threads

{threadId}

curl https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000

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

{
  "thread": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "support_agent",
    "user_id": "user_abc123",
    "tags": ["support", "priority"],
    "created_at": 1699900000
  },
  "agent": {
    "id": "support_agent",
    "title": "Support Agent",
    "type": "ai_human",
    "description": "Handles customer inquiries and resolves support issues",
    "icon": "https://your-worker.workers.dev/icons/support.svg",
    "side_a_label": "Customer",
    "side_b_label": "Agent"
  },
  "stats": {
    "message_count": 12,
    "log_count": 3
  },
  "status": {
    "state": "idle",
    "since": 1699900042000000,
    "reason": "stop_on_response"
  }
}

{
  "error": "Thread not found: 550e8400-e29b-41d4-a716-446655440000"
}

Retrieves thread details including metadata, agent info, and statistics.

string

required

The unique thread identifier (UUID)

Response Structure

object

required

Thread metadata object

string

required

Unique thread identifier

string

required

The agent name associated with this thread

string | null

User identifier if set

array

required

Array of string tags for categorization

number

required

Unix timestamp in seconds

object | null

Agent definition details (null if agent no longer exists)

string

Agent identifier (same as thread.agent_id)

string

Human-readable agent title

string

Agent type: ai_human or dual_ai

string

Agent description if set

string

Full URL to agent icon (absolute paths are resolved to full URLs using the request origin)

object

required

Thread statistics

number

Total number of messages in the thread

number

Total number of execution logs

object

required

Authoritative run status (ThreadStatus). The same value streams live as thread_status frames on the WebSocket stream.

string

required

idle, running, or failed. A run that handed the turn to a human side is idle.

number

required

When the thread entered this state, microseconds since epoch (0 if it has never run).

string | null

Raw stop reason code of the last transition out of running (for example stop_on_response, stop_tool, awaiting_human, hook_blocked, aborted_by_user, step_error, execution_lost). Opaque; null while running.

curl https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000

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

{
  "thread": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "support_agent",
    "user_id": "user_abc123",
    "tags": ["support", "priority"],
    "created_at": 1699900000
  },
  "agent": {
    "id": "support_agent",
    "title": "Support Agent",
    "type": "ai_human",
    "description": "Handles customer inquiries and resolves support issues",
    "icon": "https://your-worker.workers.dev/icons/support.svg",
    "side_a_label": "Customer",
    "side_b_label": "Agent"
  },
  "stats": {
    "message_count": 12,
    "log_count": 3
  },
  "status": {
    "state": "idle",
    "since": 1699900042000000,
    "reason": "stop_on_response"
  }
}

{
  "error": "Thread not found: 550e8400-e29b-41d4-a716-446655440000"
}

curl https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000

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

{
  "thread": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "support_agent",
    "user_id": "user_abc123",
    "tags": ["support", "priority"],
    "created_at": 1699900000
  },
  "agent": {
    "id": "support_agent",
    "title": "Support Agent",
    "type": "ai_human",
    "description": "Handles customer inquiries and resolves support issues",
    "icon": "https://your-worker.workers.dev/icons/support.svg",
    "side_a_label": "Customer",
    "side_b_label": "Agent"
  },
  "stats": {
    "message_count": 12,
    "log_count": 3
  },
  "status": {
    "state": "idle",
    "since": 1699900042000000,
    "reason": "stop_on_response"
  }
}

{
  "error": "Thread not found: 550e8400-e29b-41d4-a716-446655440000"
}

Threads

Messages

File System

Define Utilities

WebSocket

Response Structure

​Response Structure

Response Structure