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

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

> GET /api/workflows/:workflowId/runs — Retrieve all runs for a specific workflow, showing their status and progression through the execution queue.

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

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

## Authentication

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

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

## Path Parameters

<ParamField path="workflowId" type="string" required>
  The unique identifier of the workflow whose runs you want to list. Example: `wf_abc123`.
</ParamField>

## 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:

<ResponseField name="runId" type="string">
  The unique identifier for this run. Use this value with [GET /api/workflows/runs/:runId](/api-reference/runs/get) to retrieve full details and per-node output.
</ResponseField>

<ResponseField name="workflowId" type="string">
  The ID of the workflow this run belongs to. This will match the `workflowId` you provided in the path.
</ResponseField>

<ResponseField name="status" type="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.
</ResponseField>

<ResponseField name="createdAt" type="string">
  An ISO 8601 timestamp indicating when the run was enqueued. Example: `"2024-01-15T10:00:00Z"`.
</ResponseField>

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

```json theme={null}
[
  { "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" }
]
```

<Note>
  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.
</Note>

## 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:

```bash theme={null}
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`](https://jqlang.github.io/jq/) for JSON parsing. 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/wf_abc123/runs \
  -H "Authorization: Bearer <accessToken>"
```

## Related Endpoints

* [POST /api/workflows/:workflowId/run](/api-reference/runs/enqueue) — enqueue a new run for this workflow.
* [GET /api/workflows/runs/:runId](/api-reference/runs/get) — retrieve detailed status and per-node output for a specific run.