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

List Threads

GET/api/threads

Lists threads in descending activity order by default. A caller without the admin role receives only their own threads.

agent_idstring

Filter threads by current or original agent name

user_idstring

Filter threads by owner identifier. Only admins can select another owner.

limitnumberdefault: 50

Maximum number of threads to return

offsetnumberdefault: 0

Number of threads to skip for pagination

sortstringdefault: activity

activity sorts by recent activity. created sorts by newest creation time. oldest sorts by oldest creation time.

searchstring

Each word must match the thread ID, tags, or message preview.

startDatenumber

Earliest creation time in Unix seconds.

endDatenumber

Latest creation time in Unix seconds.

statusstring

Filters by run state: idle, running, or failed.

executingboolean

1 or true selects executing threads. 0 or false selects threads without an active execution.

terminatedboolean

1 or true selects terminated threads. 0 or false selects open threads.

include_childrenboolean

Set 1 to include descendants of threads that match agent_id.

include_totalbooleandefault: true

Set 0 or false to skip the count. total will be null. hasMore will still indicate another page.

Additional filters are root_only, has_failed_descendant, awaiting_human, model, min_cost, max_cost, min_run_seconds, max_run_seconds, started_by, and status_reason. The first three accept 1/true or 0/false. Cost and duration bounds accept non-negative numbers.

threadsarrayrequired

Array of thread objects

totalnumber | nullrequired

Total number of threads matching the filter

hasMorebooleanrequired

Whether more threads exist beyond the current page

Thread Object

Each thread also includes origin_agent_id, parent, terminated, last_activity_at, executing, status, status_reason, last_message_preview, and last_message_at. status is a run-state string. status_reason is non-null only for a failed run. terminated uses microseconds since the Unix epoch. The activity and message timestamps use seconds.

threads[].idstringrequired

Unique thread identifier

threads[].agent_idstringrequired

The agent name associated with this thread

threads[].user_idstring | null

User identifier if set

threads[].tagsarrayrequired

Array of string tags

threads[].created_atnumberrequired

Unix timestamp in seconds

threads[].agentobject

Agent details including title, side backings, description, and icon

threads[].agent.titlestring

Human-readable agent title

threads[].agent.side_a_backing'human' | 'prompt' | 'handler'

What backs side A of the agent

threads[].agent.side_b_backing'human' | 'prompt' | 'handler'

What backs side B of the agent

threads[].agent.descriptionstring

Agent description if set

threads[].agent.iconstring

Full URL to agent icon (absolute paths are resolved to full URLs)