View as MarkdownPlain text for this page Open in ChatGPTQuestions about this page Open in ClaudeQuestions about this page

Get Thread

GET/api/threads/{threadId}

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

threadIdstringrequired

The unique thread identifier (UUID)

Response Structure

threadobjectrequired

Thread metadata object

thread.idstringrequired

Unique thread identifier

thread.agent_idstringrequired

The agent name associated with this thread

thread.user_idstring | null

User identifier if set

thread.tagsarrayrequired

Array of string tags for categorization

thread.parentstring | nullrequired

Parent thread ID, or null for a root thread.

thread.terminatednumber | nullrequired

Termination time in microseconds since the Unix epoch, or null for an open thread.

thread.created_atnumberrequired

Unix timestamp in seconds

agentobject | null

Agent definition details (null if agent no longer exists)

agent.idstring

Agent identifier (same as thread.agent_id)

agent.titlestring

Human-readable agent title

agent.side_a_backing'human' | 'prompt' | 'handler'

What backs side A of the agent

agent.side_b_backing'human' | 'prompt' | 'handler'

What backs side B of the agent

agent.descriptionstring

Agent description if set

agent.iconstring

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

statsobjectrequired

Thread statistics

stats.message_countnumber

Total number of messages in the thread

stats.log_countnumber

Total number of execution logs

statusobjectrequired

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

status.statestringrequired

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

status.sincenumberrequired

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

status.reasonstring | 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

curl https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $STANDARD_AGENTS_API_KEY"

JavaScript

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

200

{
  "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",
    "side_a_backing": "prompt",
    "side_b_backing": "human",
    "description": "Handles customer inquiries and resolves support issues",
    "icon": "https://your-worker.workers.dev/icons/support.svg",
    "side_a_label": "Agent",
    "side_b_label": "Customer"
  },
  "stats": {
    "message_count": 12,
    "log_count": 3
  },
  "status": {
    "state": "idle",
    "since": 1699900042000000,
    "reason": "stop_on_response"
  }
}

404

{
  "error": {
    "code": "not_found",
    "message": "Thread not found: 550e8400-e29b-41d4-a716-446655440000"
  },
  "requestId": "0b3c1f0e-7f0a-4a55-9c58-2f6f5a0f6f0e"
}