# List workflows

Lists the workflows of the key's community, newest first, with each workflow's trigger, steps and current revision.

- Endpoint: `GET https://api.returning.ai/v1/workflow-builder/data-workflows`
- Section: Workflow Builder / Workflows
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `workflowBuilder`
- Retries: Safe to retry at any time: it writes nothing.
- Guide: generated from the published specification
- Last updated: 28 Oct 2026
- Web page: https://docs.returning.ai/api-reference/workflow-builder/list-workflows

## When to use this

Use it to find a workflow id, to check deployment state before a change, or to confirm a delete or a copy.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `workflowBuilder`

The community comes from the key, so the list never spans communities and there is no community parameter to get wrong.

| Failure | Meaning | Recovery |
| --- | --- | --- |
| `401 AUTHENTICATION_REQUIRED` | No key, or an unknown key | Send a valid key. |
| `401 API_KEY_REQUIRED` | A valid admin session was used | Use a community API key. |
| `403 API_KEY_PERMISSION_DENIED` | The key authenticated without `workflowBuilder` | Grant the permission. |

## Behaviour

It returns workflows only. Runs, event ingests and credentials are separate calls, and every credential in the response is already replaced by the redaction marker.

## Request

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | No | Page number, from `1`. (Min 1; default `1`) |
| `limit` | `integer` | No | Page size, at most `100`. A larger value is refused with `400 VALIDATION_FAILED`, never silently reduced. (Default 20; max 100) |
| `status` | `string` | No | Keep only workflows in this state: `draft`, `deployed` or `undeployed`. (`draft`, `deployed`, `undeployed`) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key: `Bearer <API_KEY>`. |

### Watch for

- Every item is the full workflow detail, including every step's options. For a large community prefer a small `limit`, then `GET /{workflowId}` for the one workflow you need.
- `status` filters exactly one state. To see both drafts and deployed workflows, call twice or omit the filter.
- A workflow with no trigger reads `trigger: null`. That is not a broken row.
- `meta.total` is the number of workflows matching the filter, not the number in this page.
- Credentials are already redacted here. An `apiKey.value` of `["__REDACTED__"]` means a key is stored, not that the key is unset.

### Example request

```bash
curl --request GET \
  --url 'https://api.returning.ai/v1/workflow-builder/data-workflows?page=1&limit=20&status=deployed' \
  --header 'Authorization: Bearer <API_KEY>'
```

### More examples

A populated page, then the same call for a community with no workflows.

```bash
curl --request GET \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows?page=2&limit=10" \
  --header "Authorization: Bearer <API_KEY>"
```

```json
{
  "data": [
    {
      "_id": "65f1a2b3c4d5e6f708192a3b",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "name": "VIP bonus",
      "status": "deployed",
      "outgoingWebhookUrl": null,
      "createdAt": "2026-10-24T09:15:00.000Z",
      "updatedAt": "2026-10-24T09:20:11.000Z",
      "trigger": { "_id": "65f1a2b3c4d5e6f708192a41", "name": "Trade bonus trigger", "type": "webhook", "status": "idle", "options": { "tokenExchangeEnabled": false, "apiKey": { "enabled": true, "value": ["__REDACTED__"] } } },
      "nodes": [],
      "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
      "redactedPaths": ["trigger.options.apiKey.value"]
    }
  ],
  "meta": { "page": 2, "limit": 10, "total": 11, "totalPages": 2 }
}
```

An empty result is a normal success, not an error:

```json
{
  "data": [],
  "meta": { "page": 1, "limit": 20, "total": 0, "totalPages": 0 }
}
```

## Response

HTTP `200` with `data` (an array) and `meta` (`page`, `limit`, `total`, `totalPages`). Each item carries the same fields as `GET /{workflowId}`, including its `revision`, so a list read can be the read half of a later write. The list is the readback that proves a rename, a copy or a delete: re-read it after the mutation and match by `_id`.

Paging is by page number, not a cursor. `totalPages` is `0` when nothing matches. Rows are ordered newest first by creation time, with the identifier as a tie-break, so a page can only repeat or skip a row if a workflow is created between two calls.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `data` | `object[]` | - | Workflows of this page. |
| `data._id` | `string` | - | Workflow identifier. |
| `data.communityId` | `string` | - | Community the workflow belongs to. |
| `data.name` | `string` | - | Workflow name. |
| `data.status` | `string` | - | `draft`, `deployed` or `undeployed`. |
| `data.outgoingWebhookUrl` | `string` | - | Failure webhook URL, when one is set. (Nullable) |
| `data.createdAt` | `string` | - | Creation time. |
| `data.updatedAt` | `string` | - | Last authored change. |
| `data.trigger` | `object` | - | The trigger, or `null` when the workflow has none. (Nullable) |
| `data.trigger._id` | `string` | - | Trigger identifier. Use it as the source of a reference. |
| `data.trigger.name` | `string` | - | Display name. |
| `data.trigger.type` | `string` | - | Trigger type. |
| `data.trigger.status` | `string` | - | Trigger lifecycle state, for example `idle`. |
| `data.trigger.options` | `object` | - | Trigger options. A webhook key is shown only in the response that created it. (Nullable) |
| `data.nodes` | `object[]` | - | Main-line steps in canvas order, routers carrying their branches. |
| `data.nodes._id` | `string` | - | Step identifier. |
| `data.nodes.name` | `string` | - | Step name. |
| `data.nodes.type` | `string` | - | Step type. |
| `data.nodes.order` | `integer` | - | Position on the main line, from 1. |
| `data.nodes.continueOnFailure` | `boolean` | - | Whether a failure stops the run. |
| `data.nodes.retryOnFailure` | `boolean` | - | Whether the step is retried on failure. |
| `data.nodes.options` | `object` | - | Stored step options, with every credential replaced by `["__REDACTED__"]`. (Nullable) |
| `data.nodes.status` | `string` | - | Last run state of the step, when one exists. |
| `data.nodes.nestedNodes` | `object[]` | - | Present on a router: each branch carries its own `workflowNodeIds` and `nestedNodes`. |
| `data.revision` | `string` | - | 64 hexadecimal characters. Send it back as `If-Match`; it also arrives as the `ETag` header. |
| `data.redactedPaths` | `string[]` | - | Every location where a credential was replaced by `["__REDACTED__"]`. |
| `meta` | `object` | - | Paging metadata. |
| `meta.page` | `integer` | - | - |
| `meta.limit` | `integer` | - | - |
| `meta.total` | `integer` | - | - |
| `meta.totalPages` | `integer` | - | - |

### Example response (200)

```json
{
  "data": [
    {
      "_id": "65f1a2b3c4d5e6f708192a3b",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "name": "VIP bonus",
      "status": "draft",
      "outgoingWebhookUrl": null,
      "createdAt": "2026-10-24T09:15:00.000Z",
      "updatedAt": "2026-10-24T09:20:11.000Z",
      "trigger": {
        "_id": "65f1a2b3c4d5e6f708192a41",
        "name": "Trade bonus trigger",
        "type": "webhook",
        "status": "idle",
        "options": {
          "tokenExchangeEnabled": false,
          "apiKey": {
            "enabled": false
          },
          "aesKey": {
            "enabled": false
          }
        }
      },
      "nodes": [
        {
          "_id": "65f1a2b3c4d5e6f708192a3c",
          "name": "Read member XP",
          "type": "platform-action",
          "order": 1,
          "continueOnFailure": false,
          "retryOnFailure": false,
          "options": {
            "action": "get-user-fields",
            "selectUser": {
              "type": "email",
              "value": ["{{65f1a2b3c4d5e6f708192a41.email}}"]
            },
            "fields": [
              {
                "label": "Total XP",
                "field": "total_xp"
              }
            ]
          }
        }
      ],
      "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
      "redactedPaths": []
    },
    {
      "_id": "65f1a2b3c4d5e6f708192a42",
      "communityId": "65f1a2b3c4d5e6f708192a50",
      "name": "Trade bonus",
      "status": "deployed",
      "outgoingWebhookUrl": null,
      "createdAt": "2026-10-24T09:15:00.000Z",
      "updatedAt": "2026-10-24T09:20:11.000Z",
      "trigger": null,
      "nodes": [],
      "revision": "162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c",
      "redactedPaths": []
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}
```

## Errors

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | `limit` above `100`, a non-numeric `page`, or an unknown `status` value. `errors[].path` names the query field. Fix the query value. |
| 401 | `AUTHENTICATION_REQUIRED` | No key, or an unknown key. Send a valid key. |
| 401 | `API_KEY_REQUIRED` | A valid admin session was used, because this API accepts community API keys only. Use a community API key. |
| 403 | `API_KEY_PERMISSION_DENIED` | No `workflowBuilder`. Grant the permission. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 429 | `RATE_LIMITED` | The community's API rate limit was reached. Wait for the window to reset, then retry. |
| 500 | `INTERNAL_ERROR` | Unexpected failure. Retry with bounded backoff. |

**Retries:** Safe to retry at any time: it writes nothing. A retry can return a different page if workflows were created or deleted in between, so treat a page as a snapshot rather than a fixed set. To enumerate a large community, page by `page` from `1` and stop when `page > meta.totalPages`; a page beyond the last one returns `data: []`.

## Next step

- [Create a workflow](https://docs.returning.ai/api-reference/workflow-builder/create-a-workflow.md): `POST /v1/workflow-builder/data-workflows`.