## List flows

`GET /v1/tasks/flows`

Returns one page of task flows in the Bitrix24 account, with filtering, sorting, and field selection passed as JSON in the query parameters.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|----------|
| `select` (query) | string | no | all fields | JSON array of field names in uppercase: `ID`, `OWNER_ID`, `CREATOR_ID`, `GROUP_ID`, `TEMPLATE_ID`, `EFFICIENCY`, `ACTIVE`, `PLANNED_COMPLETION_TIME`, `ACTIVITY`, `NAME`, `DESCRIPTION`, `DISTRIBUTION_TYPE`, `DEMO`. Example: `["ID","NAME","ACTIVE"]` |
| `filter` (query) | string | no | — | JSON object of filter conditions: the key is a field name in uppercase, as in `select`, and the value is the value to match. A comparison operator can precede the name: `{">ID":10}`. The `ACTIVE` and `DEMO` flags accept `true` and `false` or `1` and `0`. The strings `"Y"` and `"N"` cause no error and are read as `false`. Example: `{"ACTIVE":true}` |
| `order` (query) | string | no | ascending `id` | JSON sort object: the key is a field name in uppercase, and the value is `ASC` or `DESC`, case-insensitive. A field name in lowercase, such as `{"id":"desc"}`, causes no error and is ignored. Example: `{"ID":"DESC"}` |
| `group` (query) | string | no | — | JSON array of field names in uppercase. It does not change the output: with `["ACTIVE"]` you get the same list as without the parameter |
| `start` (query) | number | no | `0` | Page offset in steps of 50. See the **Pagination** paragraph below |

The method accepts no other query parameters. URL-encode the values of `select`, `filter`, `order`, and `group`.

**Pagination.** The response is one page of up to 50 flows and has no `meta.total` or `meta.next` fields. `start` selects the page in steps of 50: values from `0` to `49` return the first page, and `50` returns the second. Request the next page with `start` increased by exactly 50. Do not add the number of received flows to `start`: after an incomplete page, such a request returns the same page, and a loop that waits for an empty response never ends. A page with fewer than 50 flows is the last one. Pages are not loaded automatically.

## Examples

### curl — personal key

```bash
curl -G "https://vibecode.bitrix24.com/v1/tasks/flows" \
  --data-urlencode 'select=["ID","NAME","ACTIVE"]' \
  --data-urlencode 'filter={">ID":10}' \
  --data-urlencode 'order={"ID":"DESC"}' \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -G "https://vibecode.bitrix24.com/v1/tasks/flows" \
  --data-urlencode 'select=["ID","NAME","ACTIVE"]' \
  --data-urlencode 'filter={">ID":10}' \
  --data-urlencode 'order={"ID":"DESC"}' \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const query = new URLSearchParams({
  select: JSON.stringify(['ID', 'NAME', 'ACTIVE']),
  filter: JSON.stringify({ '>ID': 10 }),
  order: JSON.stringify({ ID: 'DESC' }),
})

const res = await fetch(`https://vibecode.bitrix24.com/v1/tasks/flows?${query}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Flows:', data.map((flow) => `${flow.id}: ${flow.name}`))
```

### JavaScript — OAuth application

```javascript
const query = new URLSearchParams({
  select: JSON.stringify(['ID', 'NAME', 'ACTIVE']),
  filter: JSON.stringify({ '>ID': 10 }),
  order: JSON.stringify({ ID: 'DESC' }),
})

const res = await fetch(`https://vibecode.bitrix24.com/v1/tasks/flows?${query}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data` | array | Flows on the page. Past the last page, an empty array |
| `data[].id` | number | Flow ID |
| `data[].ownerId` | number | ID of the flow administrator. List: [`GET /v1/users`](/docs/entities/users/list) |
| `data[].creatorId` | number | ID of the employee who created the flow. List: [`GET /v1/users`](/docs/entities/users/list) |
| `data[].groupId` | number | ID of the flow's workgroup. List: [`GET /v1/workgroups`](/docs/entities/workgroups/list) |
| `data[].templateId` | number | ID of the template used to create tasks in the flow. `0` means no template. List: [`GET /v1/task-templates`](/docs/entities/tasks/templates-list) |
| `data[].efficiency` | number | Flow efficiency as a percentage |
| `data[].active` | boolean | `true` means the flow is enabled |
| `data[].plannedCompletionTime` | number | Time to complete a task, in seconds |
| `data[].activity` | string | Date and time of the flow's last activity, ISO 8601 with a time zone offset |
| `data[].name` | string | Flow name |
| `data[].description` | string | Flow description. An empty string when there is no description |
| `data[].distributionType` | string | How tasks reach assignees: `manually` — a moderator distributes them, `queue` — in turn among employees, `himself` — employees take tasks themselves |
| `data[].demo` | boolean | `true` means a Bitrix24 demo flow |

With `select`, an item contains only the listed fields and `id`: `id` is returned even when it is not in `select`. The list does not return responsible users, team members, or deadline and notification settings — they are returned by [`GET /v1/tasks/flows/:flowId`](/docs/entities/tasks/flows-get).

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": 15,
      "active": true,
      "name": "Request handling"
    },
    {
      "id": 13,
      "active": false,
      "name": "Legal department"
    },
    {
      "id": 11,
      "active": false,
      "name": "Certificate requests to accounting"
    }
  ]
}
```

## Error response example

422 — the field names in `select` are in lowercase:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Invalid select data",
    "b24Code": "0"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | A query parameter other than `select`, `filter`, `order`, `group`, and `start` was passed: `query contains unsupported fields` |
| 400 | `INVALID_PARAMS` | `select` or `group` is not a JSON array: `select must be a JSON array`, `group must be a JSON array` |
| 400 | `INVALID_PARAMS` | `filter` or `order` is not a JSON object: `filter must be a JSON object`, `order must be a JSON object` |
| 400 | `INVALID_PARAMS` | `select`, `filter`, `order`, or `group` was passed in bracket notation `filter[…]=…` instead of a JSON string: `filter must be JSON`, and likewise for the others |
| 400 | `INVALID_PARAMS` | `start` is not a non-negative integer: `start must be a non-negative safe integer` |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not found |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |
| 403 | `SCOPE_DENIED` | The key does not have the `task` or `tasks` scope |
| 422 | `BITRIX_ERROR` | `select` contains an unknown field name or a name not in uppercase: `Invalid select data` |
| 422 | `BITRIX_ERROR` | `filter` contains an unknown field name or a name not in uppercase: `Invalid filter data` |
| 422 | `BITRIX_ERROR` | `group` contains an unknown field name or a name not in uppercase: `Invalid group data` |
| 422 | `BITRIX_ERROR` | `order` contains an unknown field name: `Incorrect sort field` |
| 429 | `RATE_LIMITED` | The request rate limit of Bitrix24 or the platform was exceeded. Retry after the delay in the `Retry-After` header |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Demo flows in the output.** The list includes Bitrix24 demo flows with `demo: true`. Their `groupId` and `plannedCompletionTime` are `0`. To exclude demo flows, pass `filter={"DEMO":false}`.

## See also

- [Flows and flow tasks](/docs/entities/tasks/flows)
- [Get a flow](/docs/entities/tasks/flows-get)
- [Create a flow](/docs/entities/tasks/flows-create)
- [Update a flow](/docs/entities/tasks/flows-update)
- [Tasks](/docs/entities/tasks)