List runs
const url = 'https://example.com/v1/runs?limit=25&scopeKind=tenant&replays=exclude&include=output';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/runs?limit=25&scopeKind=tenant&replays=exclude&include=output' \ --header 'Authorization: Bearer <token>'Cursor-paginated. Fixed sort order: createdAt desc, id desc.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”1..100. Default 25.
Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.
Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.
Optional scope discriminator. If absent, no scope filter is applied.
Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.
Only the child runs of this run.
When true, only runs that are not a child of another run.
Only this agent’s turns, at any version. Turns that ran before Kindgi 0.1.3 don’t name their agent and aren’t matched.
Replay runs (an eval run re-running a past run). exclude (default) leaves them out; include lists them with the other runs; only lists just them.
Only the replay runs of this eval run. Implies replays are included; cannot be combined with replays=exclude.
Only the runs this trigger started (Run.trigger.triggerId).
Comma-separated extras per run. output adds each run’s output.
Only runs in these statuses: one, or several, repeated (status=failed&status=cancelled) or comma-separated (status=failed,cancelled).
Only runs created strictly after this time.
Only runs created strictly before this time.
With agentId: only the turns that ran this version. Turns from before versions were recorded never match.
Only runs of this flow. An agent’s turns run agent.turn; use agentId for an agent’s.
With flowId: only runs of this version.
Responses
Section titled “Responses”Page of runs.
object
object
RunId.
Semver.
The failure as the runtime recorded it. Read failure instead: an agent turn records its typed error here in an internal form.
Why a failed run failed; present only on a failed run. An agent turn’s failure carries its own code (budget-exceeded, capability-routing-failed, model-invocation-failed, …; rate-limit-exceeded when a budget kept per tenant refused work the turn needed, with details naming the budget); any other failure is run-failed, with the run’s failure message.
object
What the error came from, when it says: e.g. for capability-routing-failed, the router’s capability-unsatisfiable with its reasons, by provider.
The error’s own reason, when it gives one: for a turn that ended at its approval (hitl-cancelled), timeout when nobody decided in time. Absent from an older runtime and from errors without one; read code then.
The error’s own facts, for a code that has them: for rate-limit-exceeded, limit (the budget that refused: schema-compile-time or template-render-time) and budgetMs, the names the API’s 429 uses. Never the wait: read back later, it’s stale. Absent for any other code, and from an older runtime.
object
The run’s output once it completed. Present on single-run responses; on lists only with ?include=output.
When an erasure cleared the run’s content (its input, output, failure message and journal payloads): a person’s words were erased. Structure (status, times, ids) stays.
Set on a child run (a sub-flow run, or the agent turn an agent step started): the run that started it.
Set on a child run: the node in the parent run that started it.
Set on an agent’s turn (an agent run, or the turn a flow’s agent step started): the agent, the version that ran and the conversation. Absent on other runs, and on turns that ran before Kindgi 0.1.3.
object
The agent id.
The agent version that ran (semver).
Why this version ran: named by the caller (explicit); held by the flow version a flow’s agent step runs in (flow-pin: the node’s config.version, else the version the flow version pinned when it was published); the conversation’s own (conversation); the version live for the run’s scope (live); or the latest, nothing being live (latest). Absent on runs from before Kindgi 0.1.4.
The agent’s default for the whole tenant.
object
An org’s projects.
object
One project.
object
A segment path within a project: it covers every run whose path starts with it.
object
object
Lowercase, like an identifier: company, contact-role.
Set on a suspended run by GET /v1/runs/{runId} (not the list): what it waits for, its journal’s open waits. approvals: those still to be decided, linked to the waits. other: the rest. Absent from a runtime before Kindgi 0.1.6, or when the journal can’t be read; kindgi runs resume then works it out itself.
object
An approval the run waits for, as a run reader sees it: its identity and state. Its subject’s details, description, context and decision stay on GET /v1/approvals/{approvalId}, behind the reviewer gate.
object
Still to be decided: pending, assigned, in_review or escalated.
The reviewer role that may decide it, or above.
What waits: e.g. tool-call:pending (a tool call held for review).
For a tool call held for review: which tool and which call. Never the call’s arguments.
object
The tool id.
The model’s id for the call.
child-run (childRunId, childStatus, timesOutAt): a child run must finish. decided-approval (approvalId, approvalStatus): decided, the runtime continues. unattributed (tokenId, timesOutAt): a wait no approval is linked to. no-open-wait: the journal shows none; the runtime picks the run up again.
object
Set on a run a trigger started: the trigger and the fire that started it. Absent on other runs. The runtime fires schedules only; event and webhook are kept for event triggers and inbound webhooks, which aren’t served yet.
object
The fire that started the run: one entry of the trigger’s fire history.
A schedule’s fire: the occurrence the run is for.
How the run started, recorded when it was created and never changed: person (a person, signed in or with their own API key), key (a service account’s key), or the kind of trigger that fired it. A child run has its parent’s. Only person counts as attended: in any other run, or one without this field (runs from before runs recorded it), a tool that declares needsApprovalWhenUnattended waits for a person’s yes.
Set on a replay run (an eval run re-running a past run): the run it replays.
Set on a replay run: the eval run that started it.
Agents and tools a flow runs at other exact versions than the flow version’s pins (“this flow, with acme.scorer at 0.4.0”), without publishing a new flow version: a comparison’s flow candidate (versions on the start body and the run’s comparison), and the flow runs that replay it (a run’s versions). Each id must be an agent or tool the flow uses.
object
Tool id → exact version.
object
Agent id → exact version, for agent nodes with or without a version of their own.
object
The segment path the run was started with (coarse to fine), which picks live agent versions. A child run has its parent’s. Absent when there was none.
object
Lowercase, like an identifier: company, contact-role.
The W3C trace id of the request that started the run: the caller’s (from its traceparent) or one the API minted. The runtime’s records about the run carry it; GET responses answer traceresponse with each request’s own. Absent for a run no request started, and on runs from before runs recorded it.
Only in the response to POST /v1/runs, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for GET /v1/runs/{runId}/progress and its stream.
When publicAccessToken stops working.
Opaque cursor for the next page. Absent when hasMore: false. See docs/API-ROUTE-CONVENTIONS.md §5.
Example
{ "data": [ { "status": "pending", "agent": { "via": "explicit", "liveScope": { "kind": "tenant" } }, "waitingFor": { "other": [ { "what": "child-run" } ] }, "trigger": { "kind": "schedule" }, "startedBy": "person" } ]}Malformed cursor, filter or scope.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}