---
title: "List workflow runs"
method: GET
path: "/api/v3/workflows/runs"
tags: ["V3 Workflows"]
---

# List workflow runs

`GET /api/v3/workflows/runs`

Returns workflow run summaries for a workspace, newest first (`createdAt` descending). Use
`workflowId` to narrow the list to one workflow, or `responseId` to find the runs a specific
survey response produced.

List items are summaries without `triggerPayload`, `data`, or `logs`; fetch
`GET /api/v3/workflows/runs/{runId}` for the full debug-oriented payload. This keeps
response-level data out of list reads by default.

## Query parameters

- `workspaceId` string, cuid2, required
- `limit` integer
- `cursor` string
- `workflowId` string, cuid2
- `responseId` string, cuid2
- `filter[status][in]` WorkflowRunStatus[]
- `filter[isDryRun][eq]` boolean

## Response `200`

Workflow runs retrieved successfully

- object
  - `data` WorkflowRunListItem[], required
    - `id` string, cuid2, required
    - `workflowId` string, cuid2, required
    - `workspaceId` string, cuid2, required
    - `workflowVersionId` string, cuid2, nullable, required — Immutable workflow version snapshot the run executes against. `null` for dry runs of workflows that have never been enabled. Version contents are not readable through the v3 API in Scope 1.
    - `status` 'queued' | 'running' | 'completed' | 'failed' | 'canceled', required — Workflow run lifecycle state. `completed`, `failed`, and `canceled` are terminal. Valid transitions: `queued` → `running`, `running` → `queued` (retry/backoff), `queued` → `canceled`, and `running` → `completed`/`failed`/`canceled`. Retries do not introduce a separate status; retry state is exposed via `attempt` and `nextAttemptAt`.
    - `isDryRun` boolean, required — `true` for runs created by `POST /api/v3/workflows/{workflowId}/test`.
    - `triggerType` 'response.completed', required
    - `surveyId` string, cuid2, nullable, required
    - `responseId` string, cuid2, nullable, required — Survey response that triggered the run. `null` for synthesized dry-run data or when the response was deleted.
    - `error` string, nullable, required — Terminal or most recent failure reason. `null` while the run is healthy.
    - `attempt` integer, required — Retry attempt counter. `0` on the first execution; retries increment it without changing `status`.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `workflowName` string, required — Name of the workflow this run belongs to, joined for the runs-list display.
  - `meta` CursorPaginationMeta, required
    - `limit` integer, required
    - `nextCursor` string, nullable, required — Opaque cursor for the next page. `null` when there are no more results.

## Other responses

- `400` — Bad Request — malformed JSON, invalid query/body/params, duplicate name, or unsupported field.
- `401` — Not authenticated (no valid session or API key).
- `403` — Forbidden — no workspace access, or resource does not exist (404 not used; avoids existence leak).
- `429` — Rate limit exceeded.
- `500` — Internal Server Error.

---

[API](https://skmtc.dev/formbricks/apis/formbricks-api-v3.md) · [All operations](https://skmtc.dev/formbricks/apis/formbricks-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/formbricks/formbricks-api-v3/revisions/3c2c022e49d2/schema)