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

# List workflows

`GET /api/v3/workflows`

Returns workflow list items for a workspace, sorted by `sortBy` (default `updatedAt`,
newest first). Workflows are workspace-scoped and exposed through the same v3
session-or-`x-api-key` authorization model as surveys.

List items are intentionally slim: they include the derived `triggerType` and `surveyId`
plus a `lastRun` summary, but not the full `definition`. Use
`GET /api/v3/workflows/{workflowId}` to read the definition.

`archived` workflows are excluded unless explicitly requested with
`filter[status][in]=archived`.

## Query parameters

- `workspaceId` string, cuid2, required
- `limit` integer
- `cursor` string
- `filter[name][contains]` string
- `filter[status][in]` WorkflowStatus[]
- `sortBy` 'createdAt' | 'updatedAt' | 'name'

## Response `200`

Workflows retrieved successfully

- object
  - `data` WorkflowListItem[], required
    - `id` string, cuid2, required
    - `workspaceId` string, cuid2, required
    - `name` string, required
    - `description` string, nullable, required
    - `status` 'draft' | 'enabled' | 'disabled' | 'archived', required — Workflow lifecycle state. `draft` workflows are editable and inert. `enabled` workflows respond to trigger events. `disabled` workflows keep their configuration but are inert. `archived` workflows are soft-deleted: read-only, excluded from default list reads, and restorable via unarchive. Status only changes through lifecycle endpoints. Valid transitions: `draft` → `enabled`, `enabled` ↔ `disabled`, `enabled`/`disabled` → `draft`, any non-archived state → `archived` (archive), and `archived` → `draft` (unarchive).
    - `triggerType` 'response.completed', required — Derived from `definition.trigger.triggerType`.
    - `surveyId` string, cuid2, required — Derived from `definition.trigger.config.surveyId`.
    - `createdBy` string, cuid2, nullable, required — User id that created the workflow. `null` when the creating user was deleted.
    - `creator` object, nullable, required — Creating user's name. `null` when the creating user was deleted.
      - `name` string, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `lastRun` WorkflowRunSummary, required — Slim run shape embedded as `lastRun` in workflow resources. The runs list (`GET /api/v3/workflows/runs`) returns `WorkflowRunListItem`, which extends this with `workflowName`. Excludes `triggerPayload`, `data`, and `logs`.
      - `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
    - `runCount` integer, required — Total number of runs (dry runs included) for this workflow.
  - `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)