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.
How the run’s flow version was chosen, recorded when the run was created: explicit (the start named it), pinned (the version pinned for the run’s project, its org or the tenant; flowPinnedScope names the pin) or latest (the newest version the run’s project reaches). Absent when the runtime didn’t record it, as on runs from before it did.
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. connections: the connects it waits for. tokens: its waits for another system’s answer. 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.
The one member who may decide it.
object
The person’s account the call would use.
object
The app’s entry id.
The account’s label at the app: an email address, a login.
The connects the run waits for. Left out when there are none.
A connect the run waits for: the person opens connectUrl, consents at the app, and the run goes on.
object
The tool’s name for the connection.
The app’s entry id.
What each permission asked for allows, in plain words.
The person connected this app before, and connects it again.
Its waits for another system’s answer (a pausing tool’s calls). Absent on a runtime that pauses no run, or when they can’t be read: those waits are then unattributed.
A wait for another system’s answer: a pack tool that declares pauses handed its wait token’s link on. Answer it through the link, or with POST /v1/runs/{runId}/resume and this tokenId. Never the link itself.
object
The waitpoint id (pause:…), for POST /v1/runs/{runId}/resume.
What the run waits for, as the tool named it.
The tool whose call waits.
object
The tool id.
The model’s id for the call, for an agent’s call.
The flow step that waits, for a flow’s tool step.
When the wait times out, and the call fails with wait-token-timed-out.
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. kind is the trigger’s kind: schedule, event, webhook (an inbound webhook) or mail (new mail in a mailbox).
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.
The trigger’s version the run started with (GET …/versions/{version}), which later edits don’t change. Absent on a run from before versions.
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: schedule, webhook, event or mail. 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.
Whom the run acts for, whose access it has, recorded when it was created and never changed: user:<id> (a person) or service_account:<id> (a service account), the same strings as an approval’s requestedBy, a conversation’s openedBy and whoami’s actor. A person who starts a run, signed in or with their own API key, is whom it acts for, and so is a service account whose key starts one. A run a schedule, a webhook or a mail trigger fired (startedBy schedule, webhook or mail) acts for the trigger’s owner when it fired; a child run for its parent’s; an agent acting for someone for that someone. An approval or a resume doesn’t change it. An id, never a name: show the caller’s own as you, and a name only where the caller may read that person or service account. Absent on a run that acts for no one (a system job, an agent on its own, an eval run’s replay run) and on runs from before runs recorded it. Never on a public run token’s progress view or its stream, nor on the run.finished webhook’s run.
The tools, by id, whose calls in this run don’t wait for a person’s yes though no person started it: the list of the webhook or schedule that fired it, as it was when the run started, and never changed after. A child run has its parent’s. Absent: none.
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": [ { "flowVersionVia": "explicit", "flowPinnedScope": { "kind": "tenant" }, "status": "pending", "agent": { "via": "explicit", "liveScope": { "kind": "tenant" } }, "waitingFor": { "approvals": [ { "approver": { "kind": "member" } } ], "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" }}The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.
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" }}