> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowmaticai.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a Workflow Run — GET /api/workflows/runs/:runId

> GET /api/workflows/runs/:runId — Retrieve the status and per-node output of a workflow run. Poll this endpoint to track progress to SUCCESS or FAILED.

After enqueuing a workflow run, you can use this endpoint to inspect its current state at any point in time. The response includes both a top-level run status and a granular breakdown of every node in the workflow graph — showing whether each node has executed, what it produced, or whether it was skipped due to a conditional branch not being taken. This makes the endpoint useful for both real-time monitoring and post-run debugging.

## Endpoint

```bash theme={null}
GET /api/workflows/runs/:runId
```

## Authentication

All requests must include a valid Bearer token in the `Authorization` header.

```bash theme={null}
Authorization: Bearer <accessToken>
```

## Path Parameters

<ParamField path="runId" type="string" required>
  The unique run identifier returned by [POST /api/workflows/:workflowId/run](/api-reference/runs/enqueue) when the run was enqueued. Example: `run_xyz789abc`.
</ParamField>

## Request Body

This endpoint does not accept a request body.

## Response

<ResponseField name="runId" type="string">
  The unique identifier for this run, matching the `runId` you provided in the path.
</ResponseField>

<ResponseField name="workflowId" type="string">
  The ID of the workflow this run belongs to.
</ResponseField>

<ResponseField name="status" type="string">
  The overall status of the run. Possible values:

  * `PENDING` — the run is queued and has not started executing yet.
  * `RUNNING` — the run is actively executing; some nodes may already be complete.
  * `SUCCESS` — all required nodes executed successfully and the run is complete.
  * `FAILED` — one or more nodes encountered an error and the run halted.
</ResponseField>

<ResponseField name="nodes" type="object">
  A map of node IDs to their individual execution results. Each key is a node ID (as defined in your workflow graph), and the value is an object describing that node's outcome.

  <Expandable title="Node result object">
    <ResponseField name="status" type="string">
      The execution status of this individual node. Possible values:

      * `PENDING` — the node is waiting for upstream nodes to complete.
      * `RUNNING` — the node is currently executing.
      * `SUCCESS` — the node finished without errors.
      * `FAILED` — the node encountered an error during execution.
      * `SKIPPED` — the node was not executed because a conditional branch upstream resolved to a path that does not include this node.
    </ResponseField>

    <ResponseField name="output" type="object">
      The data produced by this node upon successful execution. The shape of this object varies by node type — for example, a data-source node might return `{ "rows": [...] }`, while an output node might return `{ "emailsSent": 1 }`. This field is present for `SUCCESS` nodes and may be an empty object `{}` for nodes that produce no meaningful output (such as a trigger node).
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

The following response shows a fully completed run for a four-node workflow: a trigger (`t`), a data-source (`ds`), a filter (`f`), and an output action (`out`).

```json theme={null}
{
  "runId": "run_xyz789abc",
  "workflowId": "wf_abc123",
  "status": "SUCCESS",
  "nodes": {
    "t":   { "status": "SUCCESS", "output": {} },
    "ds":  { "status": "SUCCESS", "output": { "rows": [{ "name": "Alice", "email": "alice@example.com", "rating": "5" }] } },
    "f":   { "status": "SUCCESS", "output": { "items": [{ "name": "Alice", "email": "alice@example.com", "rating": "5" }] } },
    "out": { "status": "SUCCESS", "output": { "emailsSent": 1 } }
  }
}
```

## Understanding the `SKIPPED` Status

Flowmatic workflows support conditional branching — nodes can be connected along different paths that are only activated when certain conditions are met. If the execution engine evaluates a condition and follows one branch, all nodes on the other branch receive a `SKIPPED` status.

A `SKIPPED` node is **not** a failure. The overall run can still reach `SUCCESS` even when some nodes are skipped. You should expect `SKIPPED` nodes whenever your workflow includes conditional logic, and use the node-level statuses to understand exactly which execution path was taken.

<Note>
  When a node is `SKIPPED`, its `output` field will typically be absent or empty. Do not treat a missing `output` as an error — check the node's `status` field first to determine whether it ran at all.
</Note>

## Polling for Completion

Because workflow runs are asynchronous, you will often need to poll this endpoint repeatedly until the top-level `status` reaches a terminal state (`SUCCESS` or `FAILED`). The example script below does this in a shell loop, checking every 2 seconds:

```bash theme={null}
while true; do
  STATUS=$(curl -s https://api.flowmatic.io/api/workflows/runs/run_xyz789abc \
    -H "Authorization: Bearer <accessToken>" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "SUCCESS" ] || [ "$STATUS" = "FAILED" ]; then
    break
  fi
  sleep 2
done
```

This script uses [`jq`](https://jqlang.github.io/jq/) to extract the `status` field. Install it via your system package manager if needed (e.g., `brew install jq` on macOS).

## curl Example

```bash theme={null}
curl -s https://api.flowmatic.io/api/workflows/runs/run_xyz789abc \
  -H "Authorization: Bearer <accessToken>"
```

## Related Endpoints

* [POST /api/workflows/:workflowId/run](/api-reference/runs/enqueue) — enqueue a new run and obtain a `runId`.
* [GET /api/workflows/:workflowId/runs](/api-reference/runs/list) — list all runs for a workflow and monitor the queue.