Browse documentation
List workspace runs
Lists the account's retained runs, most recently active first, one
bounded page at a time. Requires run:read. Continue with
next_cursor as after.
Filters combine: agent_id selects one agent, version selects the runs
with at least one turn on that deployment version of it (the
agent_version each turn reports), state selects idle or busy runs,
and created_after and created_before bound when the run was created.
Repeat tag, up to 5 times, to select the runs that have every one of
those tags. A tag matches exactly, with its case.
A filter of tags that are all common in the workspace searches at most 50,000 of its runs to fill a page. If that does not fill one, the request is refused with 400, code invalid_request and param tag, never answered with a short page: add a more specific tag, since a run must have every tag and a tag that few runs have narrows the search.
A listed run is a summary of durable run data. Retrieve a run to read its turns. Listing never loads events.
/runsAuthorization
AuthorizationBearer <token>Query parameters
agent_idstring- pattern
"^agt_[A-Za-z0-9]+$"
versionintegerOnly runs with at least one turn on this deployment version of the agent, matching the agent_version each turn reports. A run that moved to a newer version still lists under the versions its earlier turns ran on, so it can appear under more than one version, and the agent_version it shows is the version its workspace is on.
- minimum
1- maximum
2147483647
statestring- enum
["idle","busy"]
tagarrayOnly runs that have this tag. Repeat the parameter, up to 5 times, to require several tags. A run must have all of them. A tag matches exactly, with its case.
- minItems
1- maxItems
5- style
form- explode
true
Show nested schema
A free-form label of 1 to 64 characters, stored exactly as sent. It is case-sensitive and nothing is trimmed. It may not be only whitespace or contain a control character.
- minLength
1- maxLength
64- pattern
"^(?![ \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]+$)[^\\u0000-\\u001f\\u007f-\\u009f]+$"
created_afterinteger- minimum
0
created_beforeinteger- minimum
0
limitinteger- minimum
1- maximum
100- default
20
afterstringResponse
Run list
objectstringrequired- const
"list"
dataarrayrequiredShow nested schema
Additional properties are allowed.
idstringrequired- pattern
"^run_[A-Za-z0-9]+$"
objectstringrequired- const
"run"
agent_idstringrequired- pattern
"^agt_[A-Za-z0-9]+$"
agent_versionintegerrequiredThe deployment version the run's workspace is on. It moves to a newer version only when a turn on that version upgrades the workspace, so a queued turn can already be on a newer version. The version filter matches the version of any of the run's turns, so a run can be listed under a version other than this one. Retrieve the run to see the version of each turn.
- minimum
1
statestringrequired- enum
["idle","busy"]
tagsarrayrequiredThe run's tags, sorted, without repeats. A run has at most 20.
- maxItems
20- uniqueItems
true
Show nested schema
A free-form label of 1 to 64 characters, stored exactly as sent. It is case-sensitive and nothing is trimmed. It may not be only whitespace or contain a control character.
- minLength
1- maxLength
64- pattern
"^(?![ \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]+$)[^\\u0000-\\u001f\\u007f-\\u009f]+$"
created_atintegerrequired- minimum
0
last_activity_atintegerrequired- minimum
0
has_morebooleanrequirednext_cursorstring | nullrequired