Skip to main content
GET
Error

Authorizations

Authorization
string
header
required

The control surface credential. Send Authorization: Bearer <token>.

Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ or puk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.

Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.

Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.

Query Parameters

limit
integer

How many runs to return, 1 to 200. Defaults to 50. A value above 200 is refused, not clamped: page with the cursor instead.

Required range: 1 <= x <= 200
before
string

Opaque cursor from a previous page's nextBefore. Returns only runs older than it. Treat it as opaque: its form is not part of this contract. Send it only when you have one: an empty value is refused, not read as the first page.

Minimum string length: 1
state
enum<string>

Return only runs in this state. A run whose deadline has passed counts as failed here, because that is what it already is. A run state.

Available options:
queued,
running,
needs_user_control,
paused,
succeeded,
failed,
canceled

Response

A page of runs.

A page of runs, newest first.

runs
object[]
required
nextBefore
string

Send back as before for the next page. ABSENT on the last page, which is how paging ends.