> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs

> Inspect workflow runs and their steps, hand held runs to a person, and cancel, restart or otherwise control a run.

A run is one execution of a workflow graph. The Runs domain exposes run state, step results, the status of runs held for a person, and cancellation. External integrations use it to drive dashboards, monitor production runs, and stop runs they no longer need.

## Run states

A run is `running` until it ends `completed` or `failed`. An Agent node assigned to a person, or a governance hold, waits inside a running run for an eligible person; the run continues on its own once that person decides (see [When a run is held for a person](#when-a-run-is-held-for-a-person)). A cancelled run passes through `cancellation_requested` while in-flight work drains, then ends `cancelled` (or `failed` if the drain could not finish). A delegated run paused from the Console reports `paused`.

## Operations

Reads:

* `GET /api/v3/runs` — [listRuns](https://docs.gloo.com/forge/reference/http-api/runs/list.md) — list every run you may read, wherever it was launched, with optional `status`, `workflowId`, `kind`, `versionId`, `runType` and `interfaceId` filters
* `GET /api/v3/runs/{runId}` — [getRun](https://docs.gloo.com/forge/reference/http-api/runs/get.md) — fetch a single run by ID, including steps, each step's governance hold, human-step status and, once completed, its declared outputs
* `GET /api/v3/runs/{runId}/trust-status` — [getRunTrustStatus](https://docs.gloo.com/forge/reference/http-api/runs/getTrustStatus.md) — whether a run is held for a person, and the Console handoff to give that person
* `GET /api/v3/runs/{runId}/artifacts` — [listRunArtifacts](https://docs.gloo.com/forge/reference/http-api/runs/listArtifacts.md) — references to the files a run produced; fetch bytes separately with `GET /api/v3/files/{fileId}/content` under `files:read`
* `GET /api/v3/runs/{runId}/events` — [listRunEvents](https://docs.gloo.com/forge/reference/http-api/runs/listEvents.md) — the run's structural timeline: checkpoints, handoffs, guardrail trips, interventions, cost milestones, errors and completion; never tool I/O, messages, error payloads or cost amounts

A run you cannot read (you need `runs:read` at the run's home, its own org unit else its workflow's owning org unit, and at every company it carries) answers `404` like a missing one, and the list never includes it.

Inspection reads (each needs `runs:read` on the run; see [Inspecting a run](#inspecting-a-run)):

* `GET /api/v3/runs/{runId}/provenance` — [getRunProvenance](https://docs.gloo.com/forge/reference/http-api/runs/getProvenance.md) — production or test, the version or draft it ran, and its attempts
* `GET /api/v3/run-steps/{stepId}` — [getRunStep](https://docs.gloo.com/forge/reference/http-api/runs/getStep.md) — one step with its outputs, stdout, error and delivery counts
* `GET /api/v3/runs/{runId}/timeline` — [getRunTimeline](https://docs.gloo.com/forge/reference/http-api/runs/getTimeline.md) — every step with its runtime content, and the run's newest audit events
* `GET /api/v3/runs/{runId}/validator-runs` — [listRunValidatorRuns](https://docs.gloo.com/forge/reference/http-api/runs/listValidatorRuns.md) — the schema and validator-agent passes over one step's outputs
* `GET /api/v3/runs/{runId}/step-contexts` — [listRunStepContext](https://docs.gloo.com/forge/reference/http-api/runs/listStepContext.md) — the knowledge, memories and facts one step recalled
* `GET /api/v3/runs/{runId}/citation-resolution` — [resolveRunCitation](https://docs.gloo.com/forge/reference/http-api/runs/resolveCitation.md) — the knowledge case a run's citation names; also needs `knowledge:read`
* `GET /api/v3/runs/{runId}/artifact-producers/{fileId}` — [getRunArtifactProducer](https://docs.gloo.com/forge/reference/http-api/runs/getArtifactProducer.md) — the tool call that produced one of the run's files
* `GET /api/v3/runs/{runId}/notification-obligations` — [listRunNotificationObligations](https://docs.gloo.com/forge/reference/http-api/runs/listNotificationObligations.md) — the notifications the run owes for one attempt

Conversations and exports (see [Run conversations and exports](#run-conversations-and-exports)):

* `GET /api/v3/runs/{runId}/debug-bundle` — [getRunDebugBundle](https://docs.gloo.com/forge/reference/http-api/runs/getDebugBundle.md) — the run, its provenance, steps and validator passes in one bundle; needs `runs:read`
* `GET /api/v3/runs/{runId}/markdown` — [getRunMarkdown](https://docs.gloo.com/forge/reference/http-api/runs/getMarkdown.md) — the run rendered as one Markdown document; needs `runs:read`
* `GET /api/v3/runs/{runId}/step-messages` — [listRunStepMessages](https://docs.gloo.com/forge/reference/http-api/runs/listStepMessages.md) — one step's agent conversation; needs `runs:read`
* `GET /api/v3/runs/{runId}/diagnostic-timeline` — [getRunDiagnosticTimeline](https://docs.gloo.com/forge/reference/http-api/runs/getDiagnosticTimeline.md) — the run's events, correlated platform changes and operator notes; needs `runs:read`
* `GET /api/v3/run-analyses` — [listRunAnalyses](https://docs.gloo.com/forge/reference/http-api/runs/listAnalyses.md) — the runs that have an AI analysis; needs `workflows:read`
* `GET /api/v3/runs/{runId}/analysis` — [getRunAnalysis](https://docs.gloo.com/forge/reference/http-api/runs/getAnalysis.md) — a run's AI analysis and its first messages; needs `workflows:read`
* `GET /api/v3/runs/{runId}/analysis-messages` — [listRunAnalysisMessages](https://docs.gloo.com/forge/reference/http-api/runs/listAnalysisMessages.md) — a run's AI analysis conversation; needs `workflows:read`

Writes:

* `POST /api/v3/runs/{runId}/cancel` — [cancelRun](https://docs.gloo.com/forge/reference/http-api/runs/cancel.md) — request a run's cancellation; effects already performed are not rolled back. Needs `runs:manage` at the run's home.
* `POST /api/v3/runs/{runId}/restart` — [restartRun](https://docs.gloo.com/forge/reference/http-api/runs/restart.md) — restart a failed run from one of its steps as a new attempt (model spend). Needs `runs:manage` at the run's home.
* `POST /api/v3/run-notification-obligations/{obligationId}/retry` — [retryRunNotification](https://docs.gloo.com/forge/reference/http-api/runs/retryNotification.md) — retry a run's failed notification, optionally to someone else, as a Personal key's owner. Needs `runs:manage` at the run's home.
* `POST /api/v3/runs/{runId}/start-analysis` — [startRunAnalysis](https://docs.gloo.com/forge/reference/http-api/runs/startAnalysis.md) — start the run's AI analysis, once per run (model spend). Needs `platform:manage`.
* `POST /api/v3/runs/{runId}/set-kill-switch` — [setRunKillSwitch](https://docs.gloo.com/forge/reference/http-api/runs/setKillSwitch.md) — halt or resume the run's sandbox commands; it does not cancel the run. Needs `switches:use` at the run's home.

`POST /api/v2/runs/resume` was retired: it could never succeed, and a held run continues on its own after approval.

## Step analytics and what counts as a sample

Per-step aggregates (`avgDurationMs`, `avgCost`, `failureRate`, `runCount`) sample completed and failed step rows separately, and the two are **not** interchangeable:

* **`failureRate` and `runCount` count outcomes.** A step that failed is a failure, whatever it spent getting there.
* **`avgCost` and `avgDurationMs` measure work that actually happened.** A step can fail *after* running to completion — most commonly when its output is rejected by a validation gate — and that attempt really did burn tokens and wall clock. Those attempts are included in the cost and duration averages, because excluding them would under-report real spend and make the averages describe a subset of the work the platform actually performed.

The two averages carry independent divisors. Cost is sampled whenever a step accrued spend; duration is sampled only when the row carries both a start and an end timestamp, which a legacy row may not. A step can therefore contribute to `avgCost` and not to `avgDurationMs`.

> [!NOTE]
>
> If you previously reconciled `avgCost × runCount` against a run's total, expect the figures to move for runs containing validation-rejected steps: the spend was always real and booked to the run, but the average used to omit it.

## Execution outcome metadata

Run detail, list and debug-bundle records may include `executionOutcome`, separately from `status`.
It carries `schemaVersion: 1`, `classifierRevision: 1`, `source` (`native`, `platform` or `backfill`),
`attempt`, `workflowInstanceId`, `statusAtCapture`, `coverage` (`complete`, `partial` or `unavailable`),
finite `reasonCodes`, optional `summary`, optional `graphDigest`, `selectedPaths`, `omittedPathCount`
and `capturedAt`. See the exact [OpenAPI contract](https://docs.gloo.com/forge/reference/openapi.json).

`summary.disposition` is `normal`, `expected_exceptions`, `failure_handled`, `failure_unresolved` or
`cancelled`. It also retains expected exception, handled failure and unresolved failure node IDs.
`selectedPaths` contains bounded node identities/names and selected labels. A label does not itself
mean exception. Native `handlingSummary` remains authoritative when present.

New graph launches collect this automatically without changing legacy execution semantics or
requiring workflow author setup. Missing metadata does not mean normal or successful business work.
Nonterminal records have no terminal execution outcome. `executionOutcomeReadReason` can explain a
bounded list read (for example `evidence_read_limit`); open the run detail to load its evidence.
Historical backfill preserves original status and never sends old communications again.

Strict MCP result mirrors carry the same optional metadata. Because released strict consumers reject
additive fields, the next MCP package publication requires a new major release; source deployment and
MCP package publication are separate operations.

## Common workflows

Poll for a run's outcome:

```bash theme={null}
curl "$FORGE_BASE/api/v3/runs/run_abc" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

Request a run's cancellation, then poll `GET /api/v3/runs/{runId}` until it reports `cancelled`:

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/runs/run_abc/cancel" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel-run_abc" \
  -d '{"reason": "Duplicate of run_xyz"}'
```

Cancellation stops new work; it never undoes work already done.

For real-time updates without polling, subscribe to webhooks for `run.*` events.

## When a run is held for a person

A governance hold or an Agent node assigned to a person pauses a run until an eligible person decides. Only a person decides it: in the Console, or with their own Personal key through [completeHumanTask](https://docs.gloo.com/forge/reference/http-api/governance/completeHumanTask.md). A platform API key or an External App is refused with `403`, and a hold that sends outside Forge is approved only in the Console. So a machine caller hands the decision to a person:

```bash theme={null}
curl "$FORGE_BASE/api/v3/runs/run_abc/trust-status"   -H "Authorization: Bearer $FORGE_TOKEN"
```

While `state` is `waiting`, `handoff` names the Console item to decide. Give `handoff.url` to an eligible person (or `handoff.path` when the deployment has no Console base URL); opening it requires a Console sign-in. Poll until `state` changes. `message` is a fixed sentence per state, never the recorded approval text or who decided; callers that also hold `grants:read`, `policies:read` and `audit:read` read the recorded trail with `GET /api/v3/runs/{runId}/approvals`. `coverage.status: "partial"` means the 50-item inspection cap was reached, so treat the status as incomplete.

### After the approval

Once an eligible person approves a hold on an agent node, the run continues on its own; there is no resume call. The approval is spent exactly once, on that node's next dispatch, and only while the External App that launched the run still holds `workflows:use` for the workflow's home. `continuation` reports what happened:

| `continuation.state` | Meaning |
| - | - |
| `awaiting_decision` | No decision yet. |
| `released` | Approved; no agent has started for the node (it is waiting to dispatch, or it failed before an agent started). |
| `dispatched` | The approved node was dispatched once. A failure is reported as `dispatched` unless the run shows no agent started. |
| `refused` | Nothing was dispatched: `refusal` is `approval_rejected`, `approval_spent` (a rerun needs a new approval), `release_unavailable` (the approval no longer matches the node's release policy), or `original_actor_unauthorized` (the launching External App lost `workflows:use` for the workflow, or is inactive). |

`continuation.effect` is the current attempt's recorded effect evidence: `not_started`, `not_applied`, `applied`, `unknown` or `not_recorded`. `unknown` and `not_recorded` are never success, and nothing retries the node automatically. `continuation` is `null` for an Agent node assigned to a person and for a run with no agent-node hold. Never dispatch the workflow again with a new idempotency key to "retry" a held node: that starts a second run.

## Inspecting a run

The inspection reads return the runtime content the Console shows a person who reads the run: step outputs, stdout and errors, validator verdicts and the outputs they checked, the context a step recalled, and the tool call that produced a file. `GET /api/v3/runs/{runId}/events` stays milestones only.

* Run content is masked the same way in every run read, including a run's launch inputs (`args`), `goal`, `error` and `outputs` in `GET /api/v3/runs/{runId}`, the debug bundle and the Markdown export:
  * A value under a credential-named key (`password`, `secret`, `token`, `api_key`, `access_key`, `private_key`, `client_secret`, `passcode`, `otp`, `totp`, `pin`, `mfa`, `backup_code`, `recovery_code`, `credential`, `authorization`, `cookie`, `session`, as a whole part of the key in any case or joiner, so `access_token` and `apiKey` count) reads `[REDACTED]` whatever it looks like. A key that only describes a credential, ending in a word such as `type`, `count`, `usage`, `enabled`, `id` or `source` (`token_type`, `tokenUsage`, `otpEnabled`, `sessionId`), is kept, as are plurals such as `max_tokens`; a secret-shaped value under such a key is still masked.
  * Credential-shaped strings (JWTs, `Bearer` tokens, `x-access-token:` URLs and GitHub tokens) are replaced by a `[REDACTED]` marker anywhere in the text.
  * In free text, the value assigned to a credential-named key (`backup code: 48213907`, `OPENAI_API_KEY=…`, `"access_token": "…"`) reads `[REDACTED]`: a quoted value up to its closing quote (or the end of the line when it never closes), an unquoted one up to the next space, and the rest of the line is kept. A benign value assigned to such a key (`pin: 3`) is masked too.
  * A secret with no credential name, shape or assignment is not recognised.
* `GET /api/v3/runs` rows name a run's launch input keys (`argKeys`), never their values.
* A human step's outputs, and the outputs its validator passes received, never carry `completedBy`, `completedVia` or `response`.
* No field names who acted, answered, was notified or repaired, and no answer carries a credential or where it is stored, an agent thread, a storage handle or the run's company list; runtime content is returned as recorded, so it may mention anything the run itself wrote.

Find a step with `GET /api/v3/runs/{runId}/timeline`, then read it in full with `GET /api/v3/run-steps/{stepId}`, its validator passes with `GET /api/v3/runs/{runId}/validator-runs` and its context with `GET /api/v3/runs/{runId}/step-contexts` (both keyed by the step's `nodeId`):

```bash theme={null}
curl "$FORGE_BASE/api/v3/run-steps/node_123?runId=run_abc" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Run conversations and exports

The conversation reads are keyed by the run (and step), never by an agent thread: a step's agent conversation and a run's AI analysis come back as messages with their text, reasoning and tool calls, credential-shaped strings replaced by `[REDACTED]`, and no field naming the thread or who wrote a message.

* The debug bundle and the Markdown export are built from the inspection reads, so they carry the same content those reads carry. Neither ever returns a storage URL; above 8 MiB the body is `null`, `tier` is `too_large` and `meta.partial` is `true`. A large Markdown export comes back in pages that continue by `cursor` (`meta.nextCursor`), each turn exactly once.
* The diagnostic timeline places the run's events beside the deployments and agent changes around it and the operator notes on it, by name, never by who acted or a resource id.
* AI analyses are the operator surface `POST /api/v3/runs/{runId}/start-analysis` writes. Reading them (the list, a run's analysis and its messages) needs `workflows:read` at the platform scope, with scopes reaching `runs:read`, and you see only analyses of runs you can read.

Read a failed step's conversation:

```bash theme={null}
curl "$FORGE_BASE/api/v3/runs/run_abc/step-messages?stepId=node_123&limit=20" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Related

* [Trace observability](https://docs.gloo.com/forge/run/observability.md) — conceptual background on run tracing and step results
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token
* [Webhook events](https://docs.gloo.com/forge/run/webhooks.md) — `run.started`, `run.completed`, `run.failed`, `run.paused`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.