Skip to main content
GET
/
v1
/
threads
Threads
curl --request GET \
  --url https://api.example.com/v1/threads

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Threads are the canonical cloud conversation surface. Durable thread events are stored as JSONL in workspace storage and projected into agent_threads and thread_rollouts for fast listing. Transient deltas are live-only WebSocket frames. Use threads when you want conversation history, multi-client live updates, compaction, or local Mac runs that publish back into cloud history.

​
Thread Management

MethodPathScopeDescription
GET/v1/threadsagent:readList visible threads
GET/v1/threads/{threadId}agent:readGet a thread snapshot
GET/v1/threads/{threadId}/eventsagent:readRead durable event history
GET/v1/threads/{threadId}/rolloutsagent:readList compaction rollouts
PATCH/v1/threads/{threadId}agent:runRename or archive a thread
DELETE/v1/threads/{threadId}agent:runDelete a thread
POST/v1/threads/{threadId}/compactagent:runRequest compaction
​
limit
number
default:"50"
List endpoints cap limit at 100 for thread lists and 500 for event reads.
​
cursor
string
Cursor returned in meta.nextCursor.
​
archived
boolean
Include archived threads when listing.
​
include
string
Use include=all_rollouts on snapshot or event reads when you need non-active rollout history.
cURL
curl "https://api.runtools.ai/v1/threads?limit=25" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
cURL
curl "https://api.runtools.ai/v1/threads/thr_abc123/events?limit=200" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

​
Live WebSocket

Subscribe to live thread frames: 
wss://api.runtools.ai/v1/threads/{threadId}/events?api_key=<key>
wss://api.runtools.ai/v1/threads/{threadId}/events?token=<session-token>
Pass exactly one of api_key or token. The first frame is a snapshot for the owner, or a metadata-only snapshot for admin broader-view access. Common live frames:
FrameDurable?Description
snapshotNoInitial full snapshot with protocol_version: 1
run_started / run_completedYesRun lifecycle
user_message / assistant_messageYesFinal persisted messages
tool_call / tool_resultYesPersisted tool lifecycle and final output
assistant_message_deltaNoToken deltas
assistant_thinking_deltaNoReasoning deltas
assistant_message_sourceNoSource/citation deltas
tool_call_started / tool_output_delta / tool_call_completedNoLive tool execution output
compaction_started / compaction_completedYesRollout lifecycle
thread_archived / thread_deleted / thread_renamedNoMetadata updates

​
Publish Thread Events

Public clients that execute local runs, such as the Mac sidecar, publish through POST /v1/thread-events. This route requires user or API-key auth and rejects internal service headers. Durable frame types: 
run_started, run_completed, user_message, assistant_message, tool_call, tool_result
Transient frame types: 
assistant_message_delta, assistant_thinking_delta, assistant_message_source,
tool_call_started, tool_output_delta, tool_call_completed
Transient frames require threadId, runId, rolloutId, and a positive sequenceNumber. They fan out to WebSocket subscribers but do not write JSONL or bump durable thread timestamps.
cURL
curl -X POST https://api.runtools.ai/v1/thread-events \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "thr_abc123",
    "frame": {
      "type": "assistant_message_delta",
      "runId": "run_abc123",
      "rolloutId": "001",
      "messageId": "msg_abc123",
      "sequenceNumber": 1,
      "delta": "Hello"
    }
  }'

​
Thread Busy

Only one active run may write a thread at a time. Starting another run on a busy thread returns 409 THREAD_BUSY.