Skip to content
Kindgi

Fetch a run

View as Markdown
GET
/v1/runs/{runId}
curl --request GET \
  --url https://example.com/v1/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
runId
required
string format: uuid

RunId — opaque branded string (a UUID).

Responses

Section titled “Responses”

200

Section titled “200”

Run row.

Media typeapplication/json
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
startedBy

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.

string
Allowed values: person key schedule webhook event
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
Example
{
  "status": "pending",
  "agent": {
    "via": "explicit",
    "liveScope": {
      "kind": "tenant"
    }
  },
  "waitingFor": {
    "other": [
      {
        "what": "child-run"
      }
    ]
  },
  "trigger": {
    "kind": "schedule"
  },
  "startedBy": "person"
}

400

Section titled “400”

runId is not a run id (a UUID).

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"
  }
}

404

Section titled “404”

No run with that id under this tenant.

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