Skip to main content
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). 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 — 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 — 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 — whether a run is held for a person, and the Console handoff to give that person
  • GET /api/v3/runs/{runId}/artifacts — listRunArtifacts — 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 — 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):
  • GET /api/v3/runs/{runId}/provenance — getRunProvenance — production or test, the version or draft it ran, and its attempts
  • GET /api/v3/run-steps/{stepId} — getRunStep — one step with its outputs, stdout, error and delivery counts
  • GET /api/v3/runs/{runId}/timeline — getRunTimeline — every step with its runtime content, and the run’s newest audit events
  • GET /api/v3/runs/{runId}/validator-runs — listRunValidatorRuns — the schema and validator-agent passes over one step’s outputs
  • GET /api/v3/runs/{runId}/step-contexts — listRunStepContext — the knowledge, memories and facts one step recalled
  • GET /api/v3/runs/{runId}/citation-resolution — resolveRunCitation — the knowledge case a run’s citation names; also needs knowledge:read
  • GET /api/v3/runs/{runId}/artifact-producers/{fileId} — getRunArtifactProducer — the tool call that produced one of the run’s files
  • GET /api/v3/runs/{runId}/notification-obligations — listRunNotificationObligations — the notifications the run owes for one attempt
Conversations and exports (see Run conversations and exports):
  • GET /api/v3/runs/{runId}/debug-bundle — getRunDebugBundle — the run, its provenance, steps and validator passes in one bundle; needs runs:read
  • GET /api/v3/runs/{runId}/markdown — getRunMarkdown — the run rendered as one Markdown document; needs runs:read
  • GET /api/v3/runs/{runId}/step-messages — listRunStepMessages — one step’s agent conversation; needs runs:read
  • GET /api/v3/runs/{runId}/diagnostic-timeline — getRunDiagnosticTimeline — the run’s events, correlated platform changes and operator notes; needs runs:read
  • GET /api/v3/run-analyses — listRunAnalyses — the runs that have an AI analysis; needs workflows:read
  • GET /api/v3/runs/{runId}/analysis — getRunAnalysis — a run’s AI analysis and its first messages; needs workflows:read
  • GET /api/v3/runs/{runId}/analysis-messages — listRunAnalysisMessages — a run’s AI analysis conversation; needs workflows:read
Writes:
  • POST /api/v3/runs/{runId}/cancel — cancelRun — 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 — 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 — 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 — start the run’s AI analysis, once per run (model spend). Needs platform:manage.
  • POST /api/v3/runs/{runId}/set-kill-switch — setRunKillSwitch — 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.
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. 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:
Request a run’s cancellation, then poll GET /api/v3/runs/{runId} until it reports cancelled:
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. 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:
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.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):

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: