Skip to content
Kindgi

List runs

View as Markdown
GET
/v1/runs
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”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

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.

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string
Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId
string
>= 1 characters

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.

parentRunId
string format: uuid

Only the child runs of this run.

topLevel
boolean

When true, only runs that are not a child of another run.

agentId
string
>= 1 characters

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.

replays
string
default: exclude
Allowed values: exclude include only

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.

evalRunId
string
>= 1 characters

Only the replay runs of this eval run. Implies replays are included; cannot be combined with replays=exclude.

triggerId
string format: uuid

Only the runs this trigger started (Run.trigger.triggerId).

include
string
Allowed values: output

Comma-separated extras per run. output adds each run’s output.

status
Array<string>
Allowed values: pending running suspended completed failed cancelled

Only runs in these statuses: one, or several, repeated (status=failed&status=cancelled) or comma-separated (status=failed,cancelled).

createdAfter
string format: date-time

Only runs created strictly after this time.

createdBefore
string format: date-time

Only runs created strictly before this time.

agentVersion
string
>= 1 characters

With agentId: only the turns that ran this version. Turns from before versions were recorded never match.

flowId
string
>= 1 characters

Only runs of this flow. An agent’s turns run agent.turn; use agentId for an agent’s.

flowVersion
string
>= 1 characters

With flowId: only runs of this version.

Responses

Section titled “Responses”

200

Section titled “200”

Page of runs.

Media typeapplication/json
object
data
required
Array<object>
object
id
required

RunId.

string format: uuid
tenantId
required
string format: uuid
projectId
string format: uuid
flowId
required
string
flowVersion
required

Semver.

string
status
required
string
Allowed values: pending running suspended completed failed cancelled
dryRun
required
boolean
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
completedAt
string format: date-time
failureMessage

The failure as the runtime recorded it. Read failure instead: an agent turn records its typed error here in an internal form.

string
failure

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
code
required
string
message
required
string
cause

What the error came from, when it says: e.g. for capability-routing-failed, the router’s capability-unsatisfiable with its reasons, by provider.

reason

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.

string
details

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
key
additional properties
any
output

The run’s output once it completed. Present on single-run responses; on lists only with ?include=output.

contentErasedAt

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.

string format: date-time
parentRunId

Set on a child run (a sub-flow run, or the agent turn an agent step started): the run that started it.

string format: uuid
parentNodeId

Set on a child run: the node in the parent run that started it.

string
agent

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
id
required

The agent id.

string
version
required

The agent version that ran (semver).

string
conversationId
required
string format: uuid
via

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.

string
Allowed values: explicit flow-pin conversation live latest
liveScope
One of: discriminator: kind

The agent’s default for the whole tenant.

object
kind
required
string
Allowed values: tenant
waitingFor

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
approvals
required
Array<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
approvalId
required
string format: uuid
status
required

Still to be decided: pending, assigned, in_review or escalated.

string
requiredRole
required

The reviewer role that may decide it, or above.

string
title
string
createdAt
required
string format: date-time
expiresAt
string format: date-time
subjectKind
required

What waits: e.g. tool-call:pending (a tool call held for review).

string
tool

For a tool call held for review: which tool and which call. Never the call’s arguments.

object
id
required

The tool id.

string
version
required
string
callId
required

The model’s id for the call.

string
other
required
Array<object>

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
what
required
string
Allowed values: child-run decided-approval unattributed no-open-wait
childRunId
string format: uuid
childStatus
string
approvalId
string format: uuid
approvalStatus
string
tokenId
string
timesOutAt
string format: date-time
trigger

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
triggerId
required
string format: uuid
kind
required
string
Allowed values: schedule event webhook
fireId
required

The fire that started the run: one entry of the trigger’s fire history.

string
scheduledFor

A schedule’s fire: the occurrence the run is for.

string format: date-time
replayOf

Set on a replay run (an eval run re-running a past run): the run it replays.

string format: uuid
evalRunId

Set on a replay run: the eval run that started it.

string
versions

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
tools

Tool id → exact version.

object
key
additional properties
string
agents

Agent id → exact version, for agent nodes with or without a version of their own.

object
key
additional properties
string
segments

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.

Array<object>
object
key
required

Lowercase, like an identifier: company, contact-role.

string
/^[a-z][a-z0-9_-]{0,63}$/
value
required
string
>= 1 characters <= 256 characters
traceId

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.

string
/^[0-9a-f]{32}$/
publicAccessToken

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.

string
publicAccessTokenExpiresAt

When publicAccessToken stops working.

string format: date-time
nextCursor

Opaque cursor for the next page. Absent when hasMore: false. See docs/API-ROUTE-CONVENTIONS.md §5.

string
hasMore
required
boolean
Example
{
  "data": [
    {
      "status": "pending",
      "agent": {
        "via": "explicit",
        "liveScope": {
          "kind": "tenant"
        }
      },
      "waitingFor": {
        "other": [
          {
            "what": "child-run"
          }
        ]
      },
      "trigger": {
        "kind": "schedule"
      }
    }
  ]
}

400

Section titled “400”

Malformed cursor, filter or scope.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also