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

GET /api/workflows/runs/:runId

Authentication

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

Authorization: Bearer <accessToken>

Path Parameters

runId · string · required

The unique run identifier returned by POST /api/workflows/:workflowId/run when the run was enqueued. Example: run_xyz789abc.

Request Body

This endpoint does not accept a request body.

Response

runId · string

The unique identifier for this run, matching the runId you provided in the path.

workflowId · string

The ID of the workflow this run belongs to.

status · 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.

nodes · 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.

Show Node result object

status · 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.

output · 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).

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).

{
  "runId": "run_xyz789abc",
  "workflowId": "wf_abc123",
  "status": "SUCCESS",
  "nodes": {
    "t":   { "status": "SUCCESS", "output": {} },
    "ds":  { "status": "SUCCESS", "output": { "rows": [{ "name": "Alice", "email": "[e-mail]", "rating": "5" }] } },
    "f":   { "status": "SUCCESS", "output": { "items": [{ "name": "Alice", "email": "[e-mail]", "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.

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.

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:

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 to extract the status field. Install it via your system package manager if needed (e.g., brew install jq on macOS).

curl Example

curl -s https://api.flowmatic.io/api/workflows/runs/run_xyz789abc \
  -H "Authorization: Bearer <accessToken>"

Related Endpoints

• POST /api/workflows/:workflowId/run — enqueue a new run and obtain a runId.
• GET /api/workflows/:workflowId/runs — list all runs for a workflow and monitor the queue.