# Fetch a run

GET

/v1/runs/{runId}

```sh
curl --request GET \
  --url https://example.com/v1/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'
```

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.1.9/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**runId**

required

string format: uuid

RunId — opaque branded string (a UUID).

## Responses

### 200

Run row.

application/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

- **object**

  The agent’s default for the whole tenant.

  object

  **kind**

  required

  string

  Allowed values: tenant

- **object**

  An org’s projects.

  object

  **kind**

  required

  string

  Allowed values: org

  **orgId**

  required

  string format: uuid

- **object**

  One project.

  object

  **kind**

  required

  string

  Allowed values: project

  **projectId**

  required

  string format: uuid

- **object**

  A segment path within a project: it covers every run whose path starts with it.

  object

  **kind**

  required

  string

  Allowed values: segment

  **projectId**

  required

  string format: uuid

  **path**

  required

  Array\<object>

  \>= 1 items <= 8 items

  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

**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

```json
{
  "status": "pending",
  "agent": {
    "via": "explicit",
    "liveScope": {
      "kind": "tenant"
    }
  },
  "waitingFor": {
    "other": [
      {
        "what": "child-run"
      }
    ]
  },
  "trigger": {
    "kind": "schedule"
  },
  "startedBy": "person"
}
```

### 400

`runId` is not a run id (a UUID).

application/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

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 401

Missing / malformed / expired / revoked bearer token.

application/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

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 404

No run with that id under this tenant.

application/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

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [`POST /v1/runs/{runId}/cancel`: Cancel a run](https://docs.kindgi.com/v0.1.9/reference/api/operations/runscancel.md)
- [`POST /v1/runs/{runId}/resume`: Resume a suspended run at a waitpoint (not available in this release)](https://docs.kindgi.com/v0.1.9/reference/api/operations/runsresume.md)
- [`GET /v1/runs/{runId}/journal`: Read the durable journal for a run](https://docs.kindgi.com/v0.1.9/reference/api/operations/runsjournal.md)
- [`GET /v1/runs/{runId}/stream`: Server-Sent Events stream of RunEvent frames](https://docs.kindgi.com/v0.1.9/reference/api/operations/runsstream.md)
- [See why runs failed](https://docs.kindgi.com/v0.1.9/guides/runs/see-why-runs-failed.md)
- [Show runs in your app](https://docs.kindgi.com/v0.1.9/guides/runs/show-runs-in-your-app.md)
- [Kindgi 0.1.8](https://docs.kindgi.com/v0.1.9/releases/0.1.8.md)
- [Every error code](https://docs.kindgi.com/v0.1.9/reference/errors.md)