GET /api/workflows/:workflowId/runs — List Workflow Runs

This endpoint returns the full history of runs for a given workflow, ordered from earliest to most recent. Each entry in the response includes the run’s current status, making this endpoint ideal for monitoring your execution queue in bulk — particularly useful when you have enqueued multiple runs in a batch and want to watch them progress through PENDING → RUNNING → SUCCESS one at a time.

Endpoint

GET /api/workflows/:workflowId/runs

Authentication

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

Authorization: Bearer <accessToken>

Path Parameters

string

required

The unique identifier of the workflow whose runs you want to list. Example: wf_abc123.

Request Body

This endpoint does not accept a request body.

Response

The response is a JSON array of run summary objects, one per run associated with the specified workflow. The array is ordered chronologically by createdAt. Each object in the array has the following fields:

string

The unique identifier for this run. Use this value with GET /api/workflows/runs/:runId to retrieve full details and per-node output.

string

The ID of the workflow this run belongs to. This will match the workflowId you provided in the path.

string

The current status of the run. Possible values:

PENDING — queued but not yet executing.
RUNNING — actively executing right now.
SUCCESS — completed successfully.
FAILED — encountered an error during execution.

string

An ISO 8601 timestamp indicating when the run was enqueued. Example: "2024-01-15T10:00:00Z".

Example Response

The following response shows three runs in various stages of the execution queue: the first has already completed, the second is currently executing, and the third is still waiting.

[
  { "runId": "run_001", "workflowId": "wf_abc123", "status": "SUCCESS", "createdAt": "2024-01-15T10:00:00Z" },
  { "runId": "run_002", "workflowId": "wf_abc123", "status": "RUNNING",  "createdAt": "2024-01-15T10:01:00Z" },
  { "runId": "run_003", "workflowId": "wf_abc123", "status": "PENDING",  "createdAt": "2024-01-15T10:02:00Z" }
]

Flowmatic executes runs one at a time per workflow. At any given moment, at most one run will be in the RUNNING state — all others will be PENDING (waiting) or in a terminal state (SUCCESS or FAILED). If you call this endpoint repeatedly, you can watch the queue drain: run_003 will not start until run_002 finishes, and so on.

Monitoring a Batch of Queued Runs

If you enqueued several runs in rapid succession (for example, to process a batch of records), this endpoint gives you a single call to see the state of the entire queue. The following example polls the list every 3 seconds and prints a summary until no runs remain in a non-terminal state:

while true; do
  RESPONSE=$(curl -s https://api.flowmatic.io/api/workflows/wf_abc123/runs \
    -H "Authorization: Bearer <accessToken>")
  echo "$RESPONSE" | jq -r '.[] | "\(.runId): \(.status)"'

  ACTIVE=$(echo "$RESPONSE" | jq '[.[] | select(.status == "PENDING" or .status == "RUNNING")] | length')
  if [ "$ACTIVE" -eq 0 ]; then
    echo "All runs complete."
    break
  fi

  sleep 3
done

This script uses jq for JSON parsing. 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/wf_abc123/runs \
  -H "Authorization: Bearer <accessToken>"

POST /api/workflows/:workflowId/run — enqueue a new run for this workflow.
GET /api/workflows/runs/:runId — retrieve detailed status and per-node output for a specific run.

Authentication

Uploads

Workflows

Runs

Integrations

GET /api/workflows/:workflowId/runs — List Workflow Runs

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Response

Monitoring a Batch of Queued Runs

curl Example

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Example Response

​Monitoring a Batch of Queued Runs

​curl Example

​Related Endpoints

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Response

Monitoring a Batch of Queued Runs

curl Example

Related Endpoints