Skip to main content
GET
Get run detail (with steps, human-step status and outputs)
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Visibility

You read a run when your role grants hold runs:read at the run’s home (its own org unit, else its workflow’s owning org unit) and at every company it carries. Any other run, and a run with neither home, answers 404 exactly like a missing one.

Outputs

outputs is null until the run is completed. Then it is the run’s declared workflow outputs. A file-typed output is a file id: list the run’s files with listArtifacts and fetch bytes with GET /api/v2/files/content under files:read. The completedBy, completedVia and response keys a terminal human step records are removed, so a person’s identity, channel and free-text answer are never readable under runs:read.

Holds and human steps

Each step carries hold: its governance hold’s state, heldAt, resolvedAt and opaque approvalId, with a person handoff while it is waiting. humanSteps lists each human step’s status, attempt and timestamps, oldest first, with a handoff while it is waiting or escalated. Give handoff.url (or handoff.path) to an eligible person, who decides in the Forge Console or with their own Personal key through completeHumanTask; a platform key or an External App cannot decide it. At most the newest 100 human steps are returned; humanStepsPartial: true says older ones were omitted.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Path Parameters

runId
string
required

Response

Run detail with its executed steps, human steps and outputs

data
object
required

A workflow run with its steps, human-step status and declared outputs.

meta
object
required