# Run a workflow

**POST** `/api/workflows/{id}/run`

Starts a run of a workflow. The JSON you send becomes the trigger’s data.

Needs [an API token](https://docs.gorunner.io/api/authentication#scopes) with the **Run** permission for workflows (`workflow:run`), from **Settings › Workspace › API tokens**.

## Parameters

### Path

- `id` · Required · UUID: The workflow’s ID.

### Query

- `environment` · Optional · string: `production` runs the published version, `test` the draft. Left out: `production` when the workflow is live with no unpublished changes, else `test`. A production run records `triggerType: "api"`, a test run `manual`. List runs leaves test runs out unless you send `environment=test` or `all`.
- `wait` · Optional · integer: Seconds to wait for the run to finish, a whole number from 0 to 30. The default, 0, answers at once. Anything else is a `400`, and no run is made.

### Headers

- `Idempotency-Key` · Optional · string: Up to 255 characters. Send the same request with the same key within 24 hours of a successful answer, and you get that answer again, not a second run. See [Idempotency](https://docs.gorunner.io/api/idempotency).

### Body

Any JSON object, or nothing. A webhook workflow reads `{"orderId": …}` as `{{trigger.body.orderId}}`.

Request

**curl**

```bash
GORUNNER="https://api.gorunner.io"
# An API token, from Settings › Workspace › API tokens
GORUNNER_TOKEN="grt_…"
WORKFLOW_ID="your-workflow-id"   # replace: from the workflow's address
URL="$GORUNNER/api/workflows/$WORKFLOW_ID/run"

curl -X POST "$URL?environment=production" \
  -H "Authorization: Bearer $GORUNNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "A-1001"}'
```

**JavaScript**

```js
const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const ID = process.env.WORKFLOW_ID; // the workflow's ID
const headers = {
  Authorization: `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};
const body = JSON.stringify({ orderId: "A-1001" });

const res = await fetch(
  `${GORUNNER}/api/workflows/${ID}/run` +
    "?environment=production",
  { method: "POST", headers, body },
);
const { data: run } = await res.json(); // 202
```

**Python**

```python
import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
ID = os.environ["WORKFLOW_ID"]  # the workflow's ID
headers = {"Authorization": f"Bearer {TOKEN}"}
body = {"orderId": "A-1001"}

res = requests.post(
    f"{GORUNNER}/api/workflows/{ID}/run",
    params={"environment": "production"},
    headers=headers, json=body,
)
run = res.json()["data"]  # 202
```

Response · 202 Accepted

```json
{
  "data": {
    "id": "8f0c41d2-6b7e-4c1a-9d3f-2a5b7c9e1f04",
    "workflowId": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
    "workspaceId": "c41a7e02-9b3d-4f6a-8e15-7d2c0b9a4f68",
    "orgId": "e9d2b6f1-3a7c-4d05-b8e4-1c6f2a9d7b30",
    "status": "pending",
    "triggerType": "api",
    "triggerData": {
      "body": { "orderId": "A-1001" },
      "headers": {
        "content-type": "application/json"
      },
      "method": "POST",
      "query": {}
    },
    "environment": "production",
    "versionId": "f20f671a-2c8e-4b9d-a7f1-6e3b0d5c9a12",
    "startedAt": "2026-10-25T09:00:00.317Z",
    "firstStartedAt": null,
    "tags": null
  }
}
```

## Get the result

A `202` means the run has started, not finished. `data.id` is the run’s ID.

**Wait in the same call.** Add `wait=30`. A run that finishes in time answers `200`, with each step’s output. Otherwise you get `202`, also for a run that pauses on a Delay or an approval. When the server already holds as many waiting callers as it can, the `202` comes at once, with `X-Run-Wait: overloaded` and `Location: /api/runs/<id>`. The run is never cut short by `wait`.

**Ask later.** Call [Get a run](https://docs.gorunner.io/api/runs/get-run) with the run’s ID.

Request

**curl**

```bash
curl -X POST "$URL?wait=30" \
  -H "Authorization: Bearer $GORUNNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "A-1001"}'
```

**JavaScript**

```js
// GORUNNER, ID, headers and body as in the first sample
const res = await fetch(
  `${GORUNNER}/api/workflows/${ID}/run?wait=30`,
  { method: "POST", headers, body },
);
// 200: finished · 202: still going, ask later
```

**Python**

```python
# GORUNNER, ID, headers and body as in the first sample
res = requests.post(
    f"{GORUNNER}/api/workflows/{ID}/run",
    params={"wait": 30},
    headers=headers, json=body,
)
# 200: finished · 202: still going, ask later
```

Response · 200 OK, shortened

```json
{
  "data": {
    "id": "8f0c41d2-6b7e-4c1a-9d3f-2a5b7c9e1f04",
    "status": "completed",
    "finishedAt": "2026-10-25T09:00:00.338Z",
    "durationMs": 15,
    "steps": [
      {
        "nodeId": "check_stock",
        "status": "completed",
        "outputData": { "inStock": true }
      }
    ]
  }
}
```

## Responses

- 200 Finished

  The run finished within `wait`. The body is the finished run.

- 202 Accepted

  The run is queued or still going.

- 400 `VALIDATION_ERROR`

  A parameter is not valid, such as `environment=live` or `wait=31`. No run is made.

- 400 `VALIDATION_ERROR`

  An `Idempotency-Key` longer than 255 characters.

- 403 `FORBIDDEN`

  The token lacks the **Run** permission.

- 403 `ACCOUNT_SUSPENDED`

  The workspace’s account is suspended. Nothing starts until it is resumed.

- 404 `NOT_FOUND`

  No workflow with this ID in the token’s workspace, or an unknown `versionId` or `retryOf`.

- 409 `CONFLICT`

  You asked for `production`, but the workflow isn’t live (a draft or paused), or its live version can’t be read. Also: a request with this `Idempotency-Key` is still in flight.

- 409 `ACCOUNT_DELETED`

  The workspace’s account was deleted.

- 422 `VALIDATION_ERROR`

  The workflow can’t run here, such as a step on an app this installation doesn’t have. No run is made.

- 422 `VALIDATION_ERROR`

  This `Idempotency-Key` was already used with a different request.

- 422 `VALIDATION_ERROR`

  `fromNode` isn’t a step on the main line.

- 422 `PIECE_NOT_ALLOWED`

  A step uses an app this workspace may not use. The message names the step.

- 429 `CONCURRENCY_LIMIT`

  The workflow is at its concurrency limit and is set to **Refuse**.

- 429 `RUNS_WAITING_LIMIT`

  Too many runs are already waiting. Try again later.

- 503 `PIECES_UNAVAILABLE`

  GoRunner couldn’t check which apps may run. Nothing started. Try again.

- 503 `STATE_UNAVAILABLE`

  The account’s state couldn’t be read. Nothing started. Try again.

- 503 `STORAGE_UNAVAILABLE`

  With `wait`: the run finished, but couldn’t be read back in time. It is intact: read it with Get a run.

Any call can also answer: [`401 UNAUTHORIZED`](https://docs.gorunner.io/errors#UNAUTHORIZED) · [`401 TOKEN_ENDED`](https://docs.gorunner.io/errors#TOKEN_ENDED) · [`403 TOKEN_SURFACE_OFF`](https://docs.gorunner.io/errors#TOKEN_SURFACE_OFF) · [`413 PAYLOAD_TOO_LARGE`](https://docs.gorunner.io/errors#PAYLOAD_TOO_LARGE) · [`415 INVALID_CONTENT_TYPE`](https://docs.gorunner.io/errors#INVALID_CONTENT_TYPE) · [`429 RATE_LIMITED`](https://docs.gorunner.io/errors#RATE_LIMITED) · [`503 PAUSED`](https://docs.gorunner.io/errors#PAUSED) · [`503 SERVICE_UNAVAILABLE`](https://docs.gorunner.io/errors#SERVICE_UNAVAILABLE). See [Errors](https://docs.gorunner.io/api/errors#by-status).

Response · 429 Too Many Requests

```json
{
  "error": {
    "code": "CONCURRENCY_LIMIT",
    "message": "This workflow is already running its limit of 2 at once. Try again when a run finishes."
  }
}
```

**Every field**

The trigger payload. Any JSON object; it is reshaped into the delivery shape of this workflow’s trigger kind unless `__shaped` is true.

### Body

- `__shaped` · Optional · boolean: Set true when the object is ALREADY in delivery shape (a replayed run’s `triggerData`, or a saved test payload): the key is stripped and the rest passes through verbatim, so `method`/`headers`/`query` survive instead of being re-wrapped under `body`.

### Response · 200 OK

- `data` · object: 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.
  - `id` · UUID: The run id.
  - `workflowId` · UUID: The workflow that ran.
  - `workspaceId` · UUID: Tenant workspace, denormalized onto the run.
  - `orgId` · UUID: Tenant organization.
  - `status` · string: 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`.
  - `triggerType` · string: 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).
  - `triggerData` · object 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.
  - `startedAt` · time: When the run was accepted. It may then wait in line for a free slot before a worker starts it (`firstStartedAt`).
  - `firstStartedAt` · time 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`.
  - `finishedAt` · time: 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.
  - `durationMs` · integer: 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.
  - `errorMessage` · string: Why the run failed (or the cancellation reason). Absent/empty otherwise.
  - `tags` · array 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 `[]`.
  - `environment` · string: 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`.
  - `steps` · array 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`.
    - `id` · UUID: 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`.
    - `runId` · UUID: The run this step belongs to.
    - `nodeId` · string: The definition step NAME (stable identifier, e.g. `parse_csv`). Use this to find a step, not `displayName`.
    - `pieceId` · string: The app that ran, e.g. `http`, `code`, `csv`.
    - `actionId` · string: The action within that app, e.g. `send_request`, `convert`.
    - `displayName` · string: The human label shown on the canvas. Not an identifier — it can be duplicated and renamed.
    - `status` · string: 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`.
    - `inputData` · object 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.
    - `outputData` · object 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.
    - `errorMessage` · string: Why the step failed. Absent/empty when it did not.
    - `retryCount` · integer: Which attempt this record reflects (0 = first attempt).
    - `startedAt` · time: When the step began. Absent if it never started.
    - `finishedAt` · time: When the step settled. Absent while running or if it never finished.
    - `durationMs` · integer: 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.
    - `attempts` · integer: 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.
    - `firstAttemptStartedAt` · time: When the first of `attempts` began. Present with `attempts`.
    - `passes` · integer: 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.
    - `totalDurationMs` · integer: 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`.
    - `attemptErrors` · array 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`.
      - `attempt` · integer: Which attempt (1 = the first).
      - `error` · string: What it failed with.
      - `at` · time: When it ended.
    - `recovery` · string: 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`.
    - `runAttempt` · integer: Which execution of a restarted run produced this record, when it was not the first (2 = the first restart). Absent: the first.
    - `dataUnavailable` · boolean: 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.
    - `deferred` · object: 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.
      - `input` · object: 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`.
        - `bytes` · integer: The value’s size in bytes of JSON.
        - `head` · object: 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.
      - `output` · object: 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.
  - `versionId` · UUID: The workflow’s latest published version at the moment the run started. Absent for a workflow that has never been published.
  - `versionNumber` · integer: Display number of `versionId`.
  - `executedVersionId` · UUID: 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.
  - `executedVersionNumber` · integer: Display number of `executedVersionId`.
  - `startedFromStep` · string: 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.
  - `retryOfRunId` · UUID: The run this one is a retry of. Set at creation and immutable.
  - `retriedByRunId` · UUID: The most recent run that retried THIS one. The list and the detail read carry it.
  - `parentRunId` · UUID: 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.
  - `restarts` · integer: 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.
  - `answer` · string: 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`.
  - `workflowName` · string: The workflow’s name. List read only.
  - `workflowTriggerType` · string: The WORKFLOW’s configured trigger type (as opposed to this run’s `triggerType`). List read only.
  - `workflowTriggerPiece` · string: 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.
  - `stepTotal` · integer: Number of step rows recorded for this run. List read only — use it to avoid fetching the detail just to count steps.
  - `stepFailed` · integer: Number of those steps with status `failed`. List read only.
  - `waitStep` · string: Only on a `paused` run: the definition step NAME that suspended the run.
  - `resumeMode` · string: 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`.
  - `resumeAt` · time: Only on a `paused` run with `resumeMode: time`: when it will resume.
  - `waitingOn` · string: 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`.
  - `claimedAt` · time: 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.
  - `waitingFor` · string: 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`.
  - `waitingLimit` · integer: Only beside `waitingFor`: the limit it waits on.
  - `linePosition` · integer: Only on a `waiting` run: its place in its workflow’s line, 1 = next.
  - `state` · string: 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`.
  - `retryOfStartedAt` · time: LIST only. When the run this one retried started. Absent when it is gone.
  - `retryOutcome` · string: 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`.
  - `retryAt` · time: LIST only. When the retry `retryOutcome` is about started.
  - `decision` · string: LIST only. How the run’s last person-wait was settled (the same value as `answer`). One of `approved`, `rejected`, `timed_out`.
  - `decidedBy` · string: 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`).
  - `decidedAt` · time: LIST only. When the last person-wait was settled.
  - `heldSince` · time: LIST only. A held run: when its current hold began. A run that held: when its last answered hold began.
  - `heldMs` · integer: LIST only. Time held on a person over every answered hold. `durationMs` includes it, so the run’s own time is `durationMs - heldMs`.
  - `publishedVersionNumber` · integer: LIST only. The workflow’s published version now. Absent for a draft.
  - `publishedAt` · time: LIST only. When that version was published.
  - `workflowStatus` · string: LIST only. The workflow’s status now; absent when it was deleted. One of `active`, `paused`, `draft`.
  - `failure` · object: LIST only, failed runs. The step the error names and the first clause of the reason.
    - `stepKey` · string: The step’s key; absent when the message names no step.
    - `step` · string: Its display name in the version that ran (the draft for a test), else the key.
    - `reason` · string: The first clause of the reason, without the step prefix, at most 160 characters.
  - `parentWorkflowName` · string: LIST only. A sub-flow run’s caller: its workflow’s name.
  - `parentStartedAt` · time: LIST only. When the calling run started.
  - `deferred` · object: 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.
    - `triggerData` · object: 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.

### Response · 202 Accepted, A run

- `data` · object: A run. From `POST /api/workflows/{id}/run` it arrives `pending` with nothing executed — poll `GET /api/runs/{id}` for the outcome and per-step detail.
  - `id` · UUID: The run id. This is what a 202 gives you to poll or stream.
  - `workflowId` · UUID
  - `workspaceId` · UUID
  - `orgId` · UUID
  - `status` · string: `pending` = queued, nothing has executed. `waiting` (with `?wait=`) = accepted and still waiting in line for a free slot after the wait: a runs-at-once limit holds it, and it starts in order. `paused` = suspended on a durable wait (delay/approval) and will continue — it is in flight, not finished. One of `pending`, `running`, `completed`, `failed`, `cancelled`, `paused`, `waiting`.
  - `triggerType` · string: How the run started. `api` = a production run through `POST /api/workflows/{id}/run`; `mcp` = the same door, by an AI app’s tool. `manual` = a TEST run through that same endpoint (kept as `manual` deliberately — the builder’s step-data picker matches it literally). Also `webhook` (a hosted form’s submission too), `cron`, `poll`, `error`, `run_finished`, `subflow`.
  - `triggerData`: The trigger payload this run received, in delivery shape (for a webhook: `method`/`headers`/`query`/`body`). This is exactly what `{{trigger.…}}` resolves against, and what you would replay as a `__shaped` body.
  - `startedAt` · time: When the run was accepted. It may then wait in line for a free slot before a worker starts it (`firstStartedAt`).
  - `firstStartedAt` · time 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`.
  - `finishedAt` · time or null: Absent while the run is in flight.
  - `durationMs` · integer or null: How long the run took, in milliseconds: from the first time a worker started the run (`firstStartedAt`, else `startedAt`) to its finish. Absent while the run is in flight.
  - `errorMessage` · string
  - `tags` · array of strings or null: `null` on the 202 of a run just accepted, `[]` when a finished run has none.
  - `environment` · string: Deliberately independent of `triggerType` — a listen-captured delivery is honestly a webhook run AND honestly a test. `GET /api/runs` defaults to production only; this workflow-scoped list returns both. One of `test`, `production`.
  - `versionId` · UUID or null: The latest published version at the moment the run started — NOT necessarily what executed.
  - `versionNumber` · integer or null
  - `executedVersionId` · UUID or null: What ACTUALLY executed. Neither answer of this shape carries it, whatever ran (the 202 without `?wait=`, `GET /api/workflows/{id}/runs`): read `GET /api/runs/{id}`, where absent means the DRAFT ran, so rendering `versionId`'s snapshot would show a graph that never ran.
  - `executedVersionNumber` · integer or null: Display number of `executedVersionId`; carried only where it is.
  - `startedFromStep` · string or null: The step a PARTIAL (`fromNode`) run began at. Empty/absent means the run started at its trigger, which is every ordinary run — without it the trigger would be marked complete on a run that never executed it.
  - `retryOfRunId` · UUID or null: Lineage only, set from `?retryOf=`.
  - `steps` · array of objects: Per-step results. NOT populated by the run list or by the 202 from the run endpoint — fetch `GET /api/runs/{id}`. Each entry’s `outputData` is that step’s output, keyed to the step by `nodeId`.

### Response · 202 Accepted, One execution of a workflow

- `data` · object: 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.
  - `id` · UUID: The run id.
  - `workflowId` · UUID: The workflow that ran.
  - `workspaceId` · UUID: Tenant workspace, denormalized onto the run.
  - `orgId` · UUID: Tenant organization.
  - `status` · string: 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`.
  - `triggerType` · string: 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).
  - `triggerData` · object 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.
  - `startedAt` · time: When the run was accepted. It may then wait in line for a free slot before a worker starts it (`firstStartedAt`).
  - `firstStartedAt` · time 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`.
  - `finishedAt` · time: 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.
  - `durationMs` · integer: 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.
  - `errorMessage` · string: Why the run failed (or the cancellation reason). Absent/empty otherwise.
  - `tags` · array 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 `[]`.
  - `environment` · string: 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`.
  - `steps` · array 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`.
    - `id` · UUID: 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`.
    - `runId` · UUID: The run this step belongs to.
    - `nodeId` · string: The definition step NAME (stable identifier, e.g. `parse_csv`). Use this to find a step, not `displayName`.
    - `pieceId` · string: The app that ran, e.g. `http`, `code`, `csv`.
    - `actionId` · string: The action within that app, e.g. `send_request`, `convert`.
    - `displayName` · string: The human label shown on the canvas. Not an identifier — it can be duplicated and renamed.
    - `status` · string: 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`.
    - `inputData` · object 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.
    - `outputData` · object 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.
    - `errorMessage` · string: Why the step failed. Absent/empty when it did not.
    - `retryCount` · integer: Which attempt this record reflects (0 = first attempt).
    - `startedAt` · time: When the step began. Absent if it never started.
    - `finishedAt` · time: When the step settled. Absent while running or if it never finished.
    - `durationMs` · integer: 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.
    - `attempts` · integer: 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.
    - `firstAttemptStartedAt` · time: When the first of `attempts` began. Present with `attempts`.
    - `passes` · integer: 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.
    - `totalDurationMs` · integer: 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`.
    - `attemptErrors` · array 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`.
      - `attempt` · integer: Which attempt (1 = the first).
      - `error` · string: What it failed with.
      - `at` · time: When it ended.
    - `recovery` · string: 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`.
    - `runAttempt` · integer: Which execution of a restarted run produced this record, when it was not the first (2 = the first restart). Absent: the first.
    - `dataUnavailable` · boolean: 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.
    - `deferred` · object: 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.
      - `input` · object: 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`.
        - `bytes` · integer: The value’s size in bytes of JSON.
        - `head` · object: 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.
      - `output` · object: 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.
  - `versionId` · UUID: The workflow’s latest published version at the moment the run started. Absent for a workflow that has never been published.
  - `versionNumber` · integer: Display number of `versionId`.
  - `executedVersionId` · UUID: 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.
  - `executedVersionNumber` · integer: Display number of `executedVersionId`.
  - `startedFromStep` · string: 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.
  - `retryOfRunId` · UUID: The run this one is a retry of. Set at creation and immutable.
  - `retriedByRunId` · UUID: The most recent run that retried THIS one. The list and the detail read carry it.
  - `parentRunId` · UUID: 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.
  - `restarts` · integer: 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.
  - `answer` · string: 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`.
  - `workflowName` · string: The workflow’s name. List read only.
  - `workflowTriggerType` · string: The WORKFLOW’s configured trigger type (as opposed to this run’s `triggerType`). List read only.
  - `workflowTriggerPiece` · string: 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.
  - `stepTotal` · integer: Number of step rows recorded for this run. List read only — use it to avoid fetching the detail just to count steps.
  - `stepFailed` · integer: Number of those steps with status `failed`. List read only.
  - `waitStep` · string: Only on a `paused` run: the definition step NAME that suspended the run.
  - `resumeMode` · string: 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`.
  - `resumeAt` · time: Only on a `paused` run with `resumeMode: time`: when it will resume.
  - `waitingOn` · string: 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`.
  - `claimedAt` · time: 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.
  - `waitingFor` · string: 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`.
  - `waitingLimit` · integer: Only beside `waitingFor`: the limit it waits on.
  - `linePosition` · integer: Only on a `waiting` run: its place in its workflow’s line, 1 = next.
  - `state` · string: 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`.
  - `retryOfStartedAt` · time: LIST only. When the run this one retried started. Absent when it is gone.
  - `retryOutcome` · string: 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`.
  - `retryAt` · time: LIST only. When the retry `retryOutcome` is about started.
  - `decision` · string: LIST only. How the run’s last person-wait was settled (the same value as `answer`). One of `approved`, `rejected`, `timed_out`.
  - `decidedBy` · string: 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`).
  - `decidedAt` · time: LIST only. When the last person-wait was settled.
  - `heldSince` · time: LIST only. A held run: when its current hold began. A run that held: when its last answered hold began.
  - `heldMs` · integer: LIST only. Time held on a person over every answered hold. `durationMs` includes it, so the run’s own time is `durationMs - heldMs`.
  - `publishedVersionNumber` · integer: LIST only. The workflow’s published version now. Absent for a draft.
  - `publishedAt` · time: LIST only. When that version was published.
  - `workflowStatus` · string: LIST only. The workflow’s status now; absent when it was deleted. One of `active`, `paused`, `draft`.
  - `failure` · object: LIST only, failed runs. The step the error names and the first clause of the reason.
    - `stepKey` · string: The step’s key; absent when the message names no step.
    - `step` · string: Its display name in the version that ran (the draft for a test), else the key.
    - `reason` · string: The first clause of the reason, without the step prefix, at most 160 characters.
  - `parentWorkflowName` · string: LIST only. A sub-flow run’s caller: its workflow’s name.
  - `parentStartedAt` · time: LIST only. When the calling run started.
  - `deferred` · object: 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.
    - `triggerData` · object: 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.

**How does the body look to each kind of trigger?**

GoRunner reshapes the body to look like a real delivery from the workflow’s trigger. A webhook workflow gets it as `trigger.body`, with `trigger.headers`, `trigger.query` and `trigger.method` beside it. A schedule workflow gets a schedule-shaped payload.

To send trigger data that is already in that shape, such as a past run’s `triggerData`, add `"__shaped": true` at the top level. GoRunner removes that key and passes the rest through as it is.

**Can I start from a step, run an older version, or mark a retry?**

- `fromNode` · Optional · string: Starts at this step, with earlier steps’ values taken from test data. It must be a step on the main line: one inside a branch or loop, or an unknown one, answers 422. The run records it as `startedFromStep`. Test runs only.
- `versionId` · Optional · UUID: Runs this published version. It must belong to this workflow. With `production`, it must be the live version.
- `retryOf` · Optional · UUID: Records this run as a retry of that run. It changes nothing about what runs: pass the original’s data, `versionId` and `fromNode` yourself.

Passing `fromNode` or `versionId` makes `test` the default environment.

**What happens when the workflow is already busy?**

A production run counts toward the workflow’s concurrency limit. By default, a run over the limit waits in line and starts in order.

If the workflow is set to **Refuse**, the call fails with `429 CONCURRENCY_LIMIT`. Try again when a run finishes.

Waiting runs are capped at 10,000 per organization and 1,000 per workflow. A self-hosted installation can change both (`RUNS_WAITING_PER_ORG`, `RUNS_WAITING_PER_WORKFLOW`). Test runs count toward the caps, but ignore the concurrency limit.

Related: [Get a run](https://docs.gorunner.io/api/runs/get-run) · [Follow a run as it happens](https://docs.gorunner.io/api/streaming) · [Publish a workflow](https://docs.gorunner.io/api/publish/publish-workflow) · [Authentication](https://docs.gorunner.io/api/authentication) · [Idempotency](https://docs.gorunner.io/api/idempotency)

Source: https://docs.gorunner.io/api/runs/run-workflow