Get a run

GET/api/runs/{id}

Returns one run with all its steps and each step’s output.

Needs an API token with the Read permission for runs (run:read).

Parameters

Path

idRequired · UUID: The run’s ID: data.id from Run a workflow, or a row of List runs.

Query

stepOptional · string: Only this step: steps holds the one whose nodeId is this, read whole. For a run too big to take at once, or a value large=defer left out. trigger gives no steps and the whole triggerData.
largeOptional · string: include, the default, gives every value. defer leaves out each value over 64 KB, and names it with its size under deferred.

It takes no body.

Request

GORUNNER="https://api.gorunner.io"
# An API token with Read for runs
GORUNNER_TOKEN="grt_…"
RUN_ID="your-run-id"   # replace: data.id from Run a workflow

curl "$GORUNNER/api/runs/$RUN_ID" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"

const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const RUN_ID = process.env.RUN_ID; // data.id from Run a workflow

const res = await fetch(`${GORUNNER}/api/runs/${RUN_ID}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data: run } = await res.json();
const shout = run.steps.find((s) => s.nodeId === "shout");
console.log(run.status, shout?.outputData);

import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
RUN_ID = os.environ["RUN_ID"]  # data.id from Run a workflow

res = requests.get(
    f"{GORUNNER}/api/runs/{RUN_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
run = res.json()["data"]
shout = next(s for s in run["steps"] if s["nodeId"] == "shout")
print(run["status"], shout["outputData"])

Read a step’s output

Each step is in steps, named by nodeId: the step’s name in the definition, the one expressions use, such as {{steps.shout.result}}. It isn’t the name shown on the canvas.

A step’s result is in outputData, and what it ran with is in inputData. Large values come back as plain JSON, even when GoRunner kept them in storage.

Response · 200 OK, shortened

json

{
  "data": {
    "id": "727eb26b-41ce-45d0-be20-bdf9d5f7624c",
    "workflowId": "acc8ce50-355c-41f9-ba19-abf97bbdc684",
    "status": "completed",
    "triggerType": "api",
    "environment": "production",
    "startedAt": "2026-10-25T09:00:00.317Z",
    "finishedAt": "2026-10-25T09:00:00.338Z",
    "durationMs": 15,
    "steps": [
      {
        "nodeId": "shout",
        "displayName": "Text Helper",
        "pieceId": "text",
        "status": "completed",
        "outputData": { "result": "ADA LOVELACE" },
        "retryCount": 0
      }
    ]
  }
}

Wait for it to finish

Ask again until status is completed, failed or cancelled. waiting, pending, running and paused aren’t finished.

A paused run waits for an approval, a webhook or a set time, and can stay paused for days. To wait without asking again, follow it with Follow a run as it happens.

Ask once a second

bash

until STATUS=$(curl -s "$GORUNNER/api/runs/$RUN_ID" \
    -H "Authorization: Bearer $GORUNNER_TOKEN" | jq -r .data.status)
  case "$STATUS" in completed|failed|cancelled) true ;; *) false ;; esac
do sleep 1; done
echo "$STATUS"

Responses

200OK
The run, with its steps.
400VALIDATION_ERROR
id isn’t a UUID, or large is neither include nor defer.
403FORBIDDEN
The token lacks the Read permission for runs.
404NOT_FOUND
No run with this ID in the token’s workspace.
404STEP_NOT_FOUND
With step: the run has no step of that name. The message lists the ones it has.

Any call can also answer: 401 UNAUTHORIZED · 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 429 RATE_LIMITED · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.

Every field

It takes no body.

Response · 200 OK

dataobject

One execution of a workflow. The same schema serves the list and the detail read, but the two carry different subsets: the LIST adds workflowName, workflowTriggerType, stepTotal, stepFailed and the fields marked LIST only, and never includes steps; the DETAIL includes steps. Both carry the version fields and the retry and parent links. An IN-FLIGHT run read from the detail endpoint is served from a live cache and is completed from its run row (its start, environment, versions, retry and parent links, workspace and organization), so it reads as a settled run does, except that tags is null until the worker saves it.

idUUID

The run id.

workflowIdUUID

The workflow that ran.

workspaceIdUUID

Tenant workspace, denormalized onto the run.

orgIdUUID

Tenant organization.

statusstring

A run’s lifecycle status. TERMINAL values — stop polling when you see one — are completed, failed and cancelled. NON-TERMINAL values are waiting (accepted and waiting in line for a free slot: its workflow’s or its organization’s runs-at-once limit, or a free worker — waitingFor, waitingLimit and linePosition say which and where; it starts in order, and cancelling it takes it out of the line), pending (a worker has it or is about to: claimedAt says when a worker took it), running (a resumed run executing after its wait) and paused (suspended on a durable wait: an approval/webhook resume, or a scheduled resume time). A paused run can remain paused indefinitely; it resumes only when its wait is satisfied, or ends if you cancel it. waiting is new in v2026.10.4: before it, a run over a limit was refused instead.

One of waiting, pending, running, completed, failed, cancelled, paused.

triggerTypestring

How THIS run began — an open string, not the workflow’s trigger vocabulary. Known values: manual (editor test), webhook, cron, poll, event, error (an error-handler workflow), run_finished, api (started through POST /api/workflows/{id}/run), mcp (the same door, by an AI app’s tool), subflow (started by a parent flow’s Sub-flow step).

triggerDataobject or array or string or number or boolean or null

The payload the trigger delivered — for a webhook run an object with body, headers, query, method. This is what {{trigger...}} expressions resolved against.

startedAttime

When the run was accepted. It may then wait in line for a free slot before a worker starts it (firstStartedAt).

firstStartedAttime or null

When a worker first started the run. durationMs counts from here, so the time from startedAt to this is the time the run waited in line. Null until a worker starts the run, and for a run started on v2026.10.5 or earlier or one that ran inline (a Sub-flow’s, an error handler’s), whose durationMs counts from startedAt.

finishedAttime

When the run settled: the moment its result was decided (not when its record was saved, which can be a moment later). Present as soon as the run is finished, also while its record is still being saved. Absent while non-terminal.

durationMsinteger

How long the run took, in milliseconds: from the first time a worker started the run (firstStartedAt, else startedAt) to its finish. Waits inside the run (a Delay, an Approval) count; the time it waited in the line for a free slot does not. A run cancelled while it waited has none. Rounded to the millisecond. Present as soon as the run is finished, also while its record is still being saved. Absent while non-terminal.

errorMessagestring

Why the run failed (or the cancellation reason). Absent/empty otherwise.

tagsarray of strings or null

Tags attached during execution by the Tags app. Filterable via GET /api/runs?tag=. [] when it has none. null while the run is read from its live cache: in flight until the worker saves it, and for a moment after it is cancelled. A run still waiting in line, read from its record, says [].

environmentstring

Where the run came from. test for anything the editor started; production for real trigger traffic and for POST /api/workflows/{id}/run?environment=production. Deliberately independent of triggerType — a listen-captured run is both a webhook run and a test run. GET /api/runs hides test runs unless asked.

One of production, test.

stepsarray of objects

The executed steps, oldest first. Returned by GET /api/runs/{id} only — never in the list. Step output lives here, keyed by each element’s nodeId.

idUUID

Id of this step-run row. A step that suspended the run gets a new id when the run resumes: address a step by nodeId.

runIdUUID

The run this step belongs to.

nodeIdstring

The definition step NAME (stable identifier, e.g. parse_csv). Use this to find a step, not displayName.

pieceIdstring

The app that ran, e.g. http, code, csv.

actionIdstring

The action within that app, e.g. send_request, convert.

displayNamestring

The human label shown on the canvas. Not an identifier — it can be duplicated and renamed.

statusstring

A single step’s status inside a run. skipped means the step was not executed (a branch arm not taken, or a step after a failure). paused marks the wait step a suspended run is currently sitting on. A step executing when its run is cancelled ends failed ("Cancelled while it ran."), and so does the step a cancelled run was held on. A step can be failed while the run is completed — that happens when the step’s error handling routed to an error path or continued.

One of pending, running, completed, failed, skipped, paused.

inputDataobject or array or string or number or boolean or null

The resolved input the step ran with, after expressions were evaluated. Normally an object of the form {"config": { ...the step's resolved config... }}. Absent when the step never executed, and on a step that suspended the run (a top-level Approval, Delay or Wait for callback) once the run has resumed: its outputData is kept, its input is not.

outputDataobject or array or string or number or boolean or null

THE STEP’S OUTPUT — whatever the app returned, arbitrary JSON. Absent when the step failed before producing output or never executed. Large payloads are offloaded to object storage during the run and rehydrated here transparently, so this is always inline JSON when present; when it cannot be read back, it is absent and dataUnavailable is true.

errorMessagestring

Why the step failed. Absent/empty when it did not.

retryCountinteger

Which attempt this record reflects (0 = first attempt).

startedAttime

When the step began. Absent if it never started.

finishedAttime

When the step settled. Absent while running or if it never finished.

durationMsinteger

How long this record’s attempt took, in milliseconds, rounded (0 = under half a millisecond; the dashboard says "<1 ms"). For a retried step it is the last attempt; for a step that ran more than once (a loop body) its last pass. totalDurationMs has the step’s time in all.

attemptsinteger

How many attempts the step’s last pass took, when it was retried (absent: one attempt; every field of this group is absent on runs recorded before it existed). This record is the last of them.

firstAttemptStartedAttime

When the first of attempts began. Present with attempts.

passesinteger

How many times the step ran in the run, when more than once — a step inside a loop runs once per item. Absent: once. This record is the last pass.

totalDurationMsinteger

The step’s time in all, in milliseconds: each pass from its first attempt’s start to its finish (the waits between retries included), summed over its passes. Present with attempts or passes.

attemptErrorsarray of objects

The earlier attempts of the last pass and why each failed, oldest first: at most the last 20, each error at most 1,000 characters. Present with attempts.

attemptinteger

Which attempt (1 = the first).

errorstring

What it failed with.

attime

When it ended.

recoverystring

In a restarted run (restarts), what the run did with this step: replayed, an earlier attempt finished it, its recorded result was used and it did not run again; rerun, it had started when the worker stopped and ran again (it only reads or computes); unknown, it changes something outside the run and was in flight when the worker stopped, so it was NOT sent again: it failed with "Outcome unknown" and its error handling decided what followed. Absent: an ordinary step.

One of replayed, rerun, unknown.

runAttemptinteger

Which execution of a restarted run produced this record, when it was not the first (2 = the first restart). Absent: the first.

dataUnavailableboolean

Present (true) when the step’s payload was offloaded to object storage and could not be read back: the step did produce inputData/outputData, but it cannot be shown now (they are absent). Tells "produced nothing" apart from "cannot be read". Absent otherwise.

deferredobject

Only on a read with large=defer: the step’s inputData and/or outputData this read left out because each is over 64 KB of JSON (the step a paused run waits on is never left out), each with its size. The value exists; read it with GET /api/runs/{id}?step=<nodeId>. Absent otherwise.

inputobject

A value this read left out because it is large: its size in bytes of JSON, as stored, and for a step’s output its head.

bytesinteger

The value’s size in bytes of JSON.

headobject

A step OUTPUT’s facts, so a client can say what the step did without reading it (an HTTP status, an approval’s answer, a loop’s count): the output’s top-level keys — a scalar (up to 512 bytes) with its value, an object as its own scalar members, every other value null — at most 8 KB, scalars first. Absent for an input, the trigger data and an output that is not a JSON object. Never the output itself.

outputobject

A value this read left out because it is large: its size in bytes of JSON, as stored, and for a step’s output its head.

The same fields as data.steps.deferred.input above.

versionIdUUID

The workflow’s latest published version at the moment the run started. Absent for a workflow that has never been published.

versionNumberinteger

Display number of versionId.

executedVersionIdUUID

The version whose definition ACTUALLY executed. ABSENT means the DRAFT ran (an editor test), so rendering versionId's snapshot would show a graph that never ran. The list and the detail read carry it; GET /api/workflows/{id}/runs does not.

executedVersionNumberinteger

Display number of executedVersionId.

startedFromStepstring

For a partial ("run from here") run, the definition step NAME the run began at. Absent means the run started at its trigger, which is every ordinary run. Everything above that step was seeded, not executed — do not read its steps as having run. Detail read only: a row of GET /api/runs leaves it out.

retryOfRunIdUUID

The run this one is a retry of. Set at creation and immutable.

retriedByRunIdUUID

The most recent run that retried THIS one. The list and the detail read carry it.

parentRunIdUUID

For a run started by another run’s Sub-flow step (triggerType subflow), the run that called it. The list and the detail read carry it; absent for every other run and for sub-flow runs from before 2026-10.

restartsinteger

How many times the run was offered to another worker because the one running it stopped (killed, out of memory, its host lost, or it lost the run’s lease). A restarted run continues from what the stopped attempt finished: a step it finished does not run again (its step record says recovery replayed), and a step that changes something outside the run and was in flight is not sent again (recovery unknown, failed with "Outcome unknown"). Absent: never restarted, and every run from before 2026-11.

answerstring

How the run’s last wait on a person was settled: approved, rejected, or timed_out (nobody answered before the step’s timeout and the run continued without an answer). List read only; absent when the run waited on no one, or its answer was given before 2026-10.

One of approved, rejected, timed_out.

workflowNamestring

The workflow’s name. List read only.

workflowTriggerTypestring

The WORKFLOW’s configured trigger type (as opposed to this run’s triggerType). List read only.

workflowTriggerPiecestring

The PIECE the workflow starts with (form, schedule, gmailtrigger), as opposed to workflowTriggerType, which is how the platform DELIVERS it. Several apps share one type — a hosted form is delivered over a webhook — so the type alone cannot say what a person chose. Absent when the trigger has no app (manual). List read only.

stepTotalinteger

Number of step rows recorded for this run. List read only — use it to avoid fetching the detail just to count steps.

stepFailedinteger

Number of those steps with status failed. List read only.

waitStepstring

Only on a paused run: the definition step NAME that suspended the run.

resumeModestring

Only on a paused run: time = it resumes automatically at resumeAt; webhook = it waits for an external call (an approval) and will not resume on its own. An approval with a timeout is a time wait that is also answerable: read waitingOn for whether a person is waited on.

One of time, webhook.

resumeAttime

Only on a paused run with resumeMode: time: when it will resume.

waitingOnstring

Only on a paused run: person = a resume link is outstanding (an approval, a webhook resume), so someone has to answer it; time = it carries on by itself (a Delay, or a link already answered and resuming). The list’s waiting filter selects by this.

One of person, time.

claimedAttime

Only on an unfinished run a worker has taken: when it took it. A pending run with claimedAt is executing; one without it is about to be taken.

waitingForstring

Only on a waiting run held by a runs-at-once limit: workflow = its workflow is at its limit (settings.concurrencyLimit), organization = its organization is (the limit set on Platform › Organizations or by the embed API). Absent when it only waits for a free worker.

One of workflow, organization.

waitingLimitinteger

Only beside waitingFor: the limit it waits on.

linePositioninteger

Only on a waiting run: its place in its workflow’s line, 1 = next.

statestring

LIST only. The run’s state word: running covers a run in a Delay; a rejected approval is worked (see decision).

One of failed, held, running, queued, worked, cancelled.

retryOfStartedAttime

LIST only. When the run this one retried started. Absent when it is gone.

retryOutcomestring

LIST only. What retrying this run came to, over every retry descending from it: worked if any worked, else an open one’s state, else the newest one’s. Absent when never retried.

One of failed, held, running, queued, worked, cancelled.

retryAttime

LIST only. When the retry retryOutcome is about started.

decisionstring

LIST only. How the run’s last person-wait was settled (the same value as answer).

One of approved, rejected, timed_out.

decidedBystring

LIST only. Who answered from the product, never an address: a member of the workspace by their name (a member when they gave none), a former member for anyone the workspace no longer has, or token {name}. Absent for an answer through the link itself, a timeout, one from before 2026-10-19, and to an embedded person (who reads only decision).

decidedAttime

LIST only. When the last person-wait was settled.

heldSincetime

LIST only. A held run: when its current hold began. A run that held: when its last answered hold began.

heldMsinteger

LIST only. Time held on a person over every answered hold. durationMs includes it, so the run’s own time is durationMs - heldMs.

publishedVersionNumberinteger

LIST only. The workflow’s published version now. Absent for a draft.

publishedAttime

LIST only. When that version was published.

workflowStatusstring

LIST only. The workflow’s status now; absent when it was deleted.

One of active, paused, draft.

failureobject

LIST only, failed runs. The step the error names and the first clause of the reason.

stepKeystring

The step’s key; absent when the message names no step.

stepstring

Its display name in the version that ran (the draft for a test), else the key.

reasonstring

The first clause of the reason, without the step prefix, at most 160 characters.

parentWorkflowNamestring

LIST only. A sub-flow run’s caller: its workflow’s name.

parentStartedAttime

LIST only. When the calling run started.

deferredobject

Only on a read with large=defer: the run’s triggerData, when it was left out because it is over 64 KB of JSON, with its size. Read it with GET /api/runs/{id}?step=trigger. Absent otherwise.

triggerDataobject

A value this read left out because it is large: its size in bytes of JSON, as stored, and for a step’s output its head.

The same fields as data.steps.deferred.input above.

Why are some fields missing while the run is going?

While a run is going, finishedAt and durationMs are absent and tags can be null, also for a moment after a cancel. Both times are there as soon as it ends, even before its record is saved. Every other field is filled in, including workspaceId, environment and the version.

What else does a run hold?

errorMessage: Why the run failed, or why it was cancelled. Each step has its own.
A step’s status: pending, running, completed, failed, skipped, or paused on the step a run waits at. A step can be failed while the run is completed: its error path ran, or it was set to continue. A step that was running when the run was cancelled ends failed.
A step’s inputData: What it ran with. A step that paused the run (an approval, a Delay, a Wait for callback on the main line) has none once the run has gone on, only its outputData. It also gets a new id then, so find a step by nodeId.
dataUnavailable: On a step: its stored input or output couldn’t be read back. An empty outputData then isn’t an empty result.
A step’s durationMs: Its last try, rounded to the millisecond: 0 is under half a millisecond. A retried step adds attempts, firstAttemptStartedAt and attemptErrors (the earlier tries’ errors, the last 20). A step that ran more than once, as in a loop, adds passes. Both add totalDurationMs, the time in all. Runs from before v2026.10.28 don’t have them.
waiting: The run waits in line for a free slot. waitingFor is workflow or organization when a runs-at-once limit holds it, with that waitingLimit. linePosition is its place, 1 = next.
claimedAt: On a run that hasn’t finished: when a worker took it.
waitingOn: On a paused run: person when someone has to answer, time when it carries on by itself.
startedAt, firstStartedAt: When the run was accepted, and when a worker first started it. durationMs counts from firstStartedAt, so time in line isn’t in it.
executedVersionId: The version that actually ran. Missing: the draft ran. versionId is the version that was live when it started.
triggerType: How this run began: api (Run a workflow, in production), mcp (the same, by an AI app’s tool), manual (a test), webhook, cron, poll, event, error, run_finished or subflow.
environment: production or test.
startedFromStep: The step a partial run began at. Steps before it were filled in, not run.
retryOfRunId, retriedByRunId: The run this one retried, and the latest run that retried this one.
parentRunId: For a sub-flow run: the run whose Sub-flow step started it.
restarts: How many times the run’s worker stopped and another carried it on. Absent: never. See If a worker stops mid-run.
A step’s recovery: On a restarted run: replayed, it had finished and its result was used; rerun, it only reads or computes and ran again; unknown, it changes something outside and wasn’t sent again, so it failed with “Outcome unknown”. runAttempt is which try of the run made the step’s record, 2 for the first restart.

How do I see what a paused run waits for?

A paused run also has waitStep (the step it waits at), resumeMode (what wakes it) and, for a set time, resumeAt.

How do these match the states on the Runs page?

completed shows as Worked and cancelled as Cancelled. pending and running show as Running. paused shows as Held when it waits for a person, and Running when it waits for a time. A run waiting for a free slot shows as Queued. See Runs.

Get a run

Parameters

Path

Query

Read a step’s output

Wait for it to finish

Responses

Response · 200 OK

Panel