Run states
A run isrunning 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 optionalstatus,workflowId,kind,versionId,runTypeandinterfaceIdfiltersGET /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 outputsGET /api/v3/runs/{runId}/trust-status— getRunTrustStatus — whether a run is held for a person, and the Console handoff to give that personGET /api/v3/runs/{runId}/artifacts— listRunArtifacts — references to the files a run produced; fetch bytes separately withGET /api/v3/files/{fileId}/contentunderfiles:readGET /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
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 attemptsGET /api/v3/run-steps/{stepId}— getRunStep — one step with its outputs, stdout, error and delivery countsGET /api/v3/runs/{runId}/timeline— getRunTimeline — every step with its runtime content, and the run’s newest audit eventsGET /api/v3/runs/{runId}/validator-runs— listRunValidatorRuns — the schema and validator-agent passes over one step’s outputsGET /api/v3/runs/{runId}/step-contexts— listRunStepContext — the knowledge, memories and facts one step recalledGET /api/v3/runs/{runId}/citation-resolution— resolveRunCitation — the knowledge case a run’s citation names; also needsknowledge:readGET /api/v3/runs/{runId}/artifact-producers/{fileId}— getRunArtifactProducer — the tool call that produced one of the run’s filesGET /api/v3/runs/{runId}/notification-obligations— listRunNotificationObligations — the notifications the run owes for one attempt
GET /api/v3/runs/{runId}/debug-bundle— getRunDebugBundle — the run, its provenance, steps and validator passes in one bundle; needsruns:readGET /api/v3/runs/{runId}/markdown— getRunMarkdown — the run rendered as one Markdown document; needsruns:readGET /api/v3/runs/{runId}/step-messages— listRunStepMessages — one step’s agent conversation; needsruns:readGET /api/v3/runs/{runId}/diagnostic-timeline— getRunDiagnosticTimeline — the run’s events, correlated platform changes and operator notes; needsruns:readGET /api/v3/run-analyses— listRunAnalyses — the runs that have an AI analysis; needsworkflows:readGET /api/v3/runs/{runId}/analysis— getRunAnalysis — a run’s AI analysis and its first messages; needsworkflows:readGET /api/v3/runs/{runId}/analysis-messages— listRunAnalysisMessages — a run’s AI analysis conversation; needsworkflows:read
POST /api/v3/runs/{runId}/cancel— cancelRun — request a run’s cancellation; effects already performed are not rolled back. Needsruns:manageat 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). Needsruns:manageat 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. Needsruns:manageat the run’s home.POST /api/v3/runs/{runId}/start-analysis— startRunAnalysis — start the run’s AI analysis, once per run (model spend). Needsplatform:manage.POST /api/v3/runs/{runId}/set-kill-switch— setRunKillSwitch — halt or resume the run’s sandbox commands; it does not cancel the run. Needsswitches:useat 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:
failureRateandrunCountcount outcomes. A step that failed is a failure, whatever it spent getting there.avgCostandavgDurationMsmeasure 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.
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 includeexecutionOutcome, 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:GET /api/v3/runs/{runId} until it reports cancelled:
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 with403, and a hold that sends outside Forge is approved only in the Console. So a machine caller hands the decision to a person:
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 holdsworkflows: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,errorandoutputsinGET /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, soaccess_tokenandapiKeycount) reads[REDACTED]whatever it looks like. A key that only describes a credential, ending in a word such astype,count,usage,enabled,idorsource(token_type,tokenUsage,otpEnabled,sessionId), is kept, as are plurals such asmax_tokens; a secret-shaped value under such a key is still masked. - Credential-shaped strings (JWTs,
Bearertokens,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.
- A value under a credential-named key (
GET /api/v3/runsrows 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,completedViaorresponse. - 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.
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,tieristoo_largeandmeta.partialistrue. A large Markdown export comes back in pages that continue bycursor(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-analysiswrites. Reading them (the list, a run’s analysis and its messages) needsworkflows:readat the platform scope, with scopes reachingruns:read, and you see only analyses of runs you can read.
Related
- Trace observability — conceptual background on run tracing and step results
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token - Webhook events —
run.started,run.completed,run.failed,run.paused

