List threads
cURL
GET /management/v1/threads
Lists your organization’s threads, newest first, as a paginated
list. Filters OR within a field and
AND across fields — repeat a parameter to OR values:
string
Filter by project.
string
Filter by agent — repeatable.
string
Filter by end-user id.
string
RFC 3339 timestamp — repeat it twice for a
[start, end] range.string
Threads where this tool was activated — repeatable.
string
Threads where a rule was evaluated:
code, or code:outcome with outcome
one of fired, blocked, passed. Repeatable.string
Threads by computed parameter:
key:value, key:* (any value), or a
comparison like amount>100. Repeatable.string
Which runtime to list threads from. Pass the runtime version your agent runs
on (e.g.
0.8.0; any value outside the 1.x family selects runtime v2) to
list its threads. Runtime v2 listings are always scoped — include an
agent_id or user_id filter — and only agent_id, user_id, and
created (with agent_id) apply there; the runtime v1–only filters return
a clear 400 on the runtime v2 path. Omit it to list threads of
runtime v1 agents (the default), where every
filter above applies.id, title, created_at, and version_tag
— the agent version the conversation ran on, so you can tell at a glance which
release of your agent handled it.
Get a thread
GET /management/v1/threads/{threadId}
Returns one thread — its title, the user_id it belongs to, its
welcome_message, and current followup_suggestions.
string
The runtime the thread lives on — pass the runtime version the agent runs on
(e.g.
0.8.0; any value outside the 1.x family selects runtime v2).
Required for runtime v2 threads (UUID ids); omit for threads of
runtime v1 agents (24-character hex ids), whose
runtime is the default. A thread lives on the runtime that created it —
asking the wrong one returns 404. Applies to the rename and transcript
endpoints below as well.Rename a thread
PATCH /management/v1/threads/{threadId}
cURL
string
The new title. Fields you omit are left unchanged; the full updated thread
is returned.
Read a thread’s transcript
GET /management/v1/threads/{threadId}/messages
The thread’s full transcript, in chronological order — the same message shape
as the messaging surface.
Inspect reasoning
GET /management/v1/threads/{threadId}/trace
GET /management/v1/interactions/{interactionId}/trace
The reasoning traces for a whole thread or one
interaction — the management twins of the messaging trace endpoints, with the
same shapes and pagination. Every trace carries runtime ("v1" or "v2")
naming the shape that follows.
string
On the interaction endpoint: the thread the interaction belongs to.
Required for runtime v2 interactions (dashed-UUID ids) — without it the
API answers
400 bad_request and says so; ignored for runtime v1
interactions. See Errors.cURL