[{"data":1,"prerenderedAt":16},["ShallowReactive",2],{"docs-entities\u002Ftasks\u002Fflows":3,"docs-tabs-entities\u002Ftasks\u002Fflows":6},{"content":4,"lastmod":5},"# Flows and flow tasks\n\nA flow is a shared queue of tasks on one topic: employees submit tasks to the flow, and Bitrix24 passes them to the responsible people and tracks the completion deadline. The methods in this subsection create flows, read them as a list or one at a time, change, delete, enable and disable them, and return flow tasks for each of three statuses.\n\nBitrix24 API: `tasks.flow.Flow.*`, `tasks.flow.Task.Pending.list`, `tasks.flow.Task.Progress.list`, `tasks.flow.Task.Completed.list`\nScope: `task`\n\n## Operations\n\n- [Create a flow](.\u002Fflows-create.md) — `POST \u002Fv1\u002Ftasks\u002Fflows`\n- [List flows](.\u002Fflows-list.md) — `GET \u002Fv1\u002Ftasks\u002Fflows`\n- [Get a flow](.\u002Fflows-get.md) — `GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`\n- [Update a flow](.\u002Fflows-update.md) — `PATCH \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`\n- [Delete a flow](.\u002Fflows-delete.md) — `DELETE \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`\n- [Toggle flow activity](.\u002Fflows-activate.md) — `POST \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Factivate`\n- [List pending flow tasks](.\u002Fflows-pending.md) — `GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Ftasks\u002Fpending`\n- [List in-progress flow tasks](.\u002Fflows-progress.md) — `GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Ftasks\u002Fprogress`\n- [List completed flow tasks](.\u002Fflows-completed.md) — `GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Ftasks\u002Fcompleted`\n\n## Key fields\n\nFlow fields in the response are named in camelCase. The full set is in the response of [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](.\u002Fflows-get.md).\n\n| Field | Description |\n|------|----------|\n| `id` | Flow ID |\n| `name` | Flow name. You cannot create two flows with the same name in one Bitrix24 account |\n| `groupId` | ID of the workgroup the flow is bound to. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist) |\n| `ownerId` | Flow administrator ID. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `plannedCompletionTime` | Time to complete a task, in seconds |\n| `distributionType` | How tasks reach assignees: `manually` — a moderator assigns them, `queue` — in turn among employees, `himself` — employees take tasks themselves |\n| `responsibleList` | Who receives the tasks: an array of pairs like `[\"user\", \"3\"]`, where the second element is the employee ID. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `active` | `true` — the flow is enabled |\n| `demo` | `true` — a Bitrix24 demo flow |\n\n## What to know before you start\n\n1. **Field names differ between the list request and the response.** In the list's `select`, `filter`, `order` and `group`, fields are uppercase: `ID`, `NAME`, `ACTIVE`. In create and update request bodies and in the response, they are camelCase: `id`, `name`, `active`.\n2. **Creation needs four fields:** `name`, `plannedCompletionTime`, `distributionType` and `responsibleList`. If any of them is missing, the flow is not created and the response is `422 BITRIX_ERROR`.\n3. **A flow without `groupId` gets a new workgroup** with the same name. When the flow is deleted, the group stays in the Bitrix24 account.\n4. **An update resets settings that are missing from the body.** The description, deadline rules, review of completed tasks and notifications not passed in `PATCH` revert to their defaults. The completion time, distribution, responsible people and group are kept.\n5. **Toggling activity does not take a target state.** Each call switches the state to the opposite one, and the response is always `true`. The current state is the flow's `active` field.\n6. **Flow tasks are split by status.** Pending tasks have not been started yet, in-progress tasks have been started, and completed tasks were closed within the last `days` days. A task moves from one list to another when its status changes.\n7. **Methods respond differently to a flow that does not exist.** Get, update, delete and activity toggle return `422 BITRIX_ERROR`, while the task lists return `200` with an empty list, as for a flow with no tasks.\n8. **A read-only key can read flows and their tasks.** With such a key, create, update, delete and activity toggle return `403 WRITE_BLOCKED_READONLY_KEY`.\n\n## Typical scenario\n\n1. Find the responsible people: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist).\n2. Create a flow: [`POST \u002Fv1\u002Ftasks\u002Fflows`](.\u002Fflows-create.md).\n3. Disable the flow or enable it again: [`POST \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Factivate`](.\u002Fflows-activate.md), and check the state in [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](.\u002Fflows-get.md).\n4. Monitor the workload: [pending](.\u002Fflows-pending.md), [in-progress](.\u002Fflows-progress.md) and [completed](.\u002Fflows-completed.md) flow tasks.\n\n## Limits\n\n| Limit | Value |\n|-------|----------|\n| Pagination | One page per call, up to 50 records per page. To get the next page, repeat the request with `start` increased by 50: any `start` from `0` to `49` returns the first page. Pages are not loaded automatically |\n| Request rate | Common API limits — [Limits and optimization](\u002Fdocs\u002Foptimization) |\n\n## See also\n\n- [Tasks](\u002Fdocs\u002Fentities\u002Ftasks)\n- [Take task](\u002Fdocs\u002Fentities\u002Ftasks\u002Ftake)\n- [Flow form](\u002Fdocs\u002Fchats\u002Fservice\u002Fflow-form)\n- [Workgroups](\u002Fdocs\u002Fentities\u002Fworkgroups)\n- [Employees](\u002Fdocs\u002Fentities\u002Fusers)\n","2026-10-20",{"flows-create.md":7,"flows-list.md":8,"flows-get.md":9,"flows-update.md":10,"flows-delete.md":11,"flows-activate.md":12,"flows-pending.md":13,"flows-progress.md":14,"flows-completed.md":15},"## Create a flow\n\n`POST \u002Fv1\u002Ftasks\u002Fflows`\n\nCreates a task flow — a shared queue from which tasks go to the responsible employees. Flow fields are passed in the `flowData` object and sent to Bitrix24 unchanged.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `flowData` | object | yes | Flow fields |\n| `flowData.name` | string | yes | Flow name. You cannot create two flows with the same name in one Bitrix24 account |\n| `flowData.plannedCompletionTime` | number | yes | Time to complete a task, in seconds, for example `86400` — one day |\n| `flowData.distributionType` | string | yes | How tasks reach assignees: `manually` — a moderator assigns them, `queue` — in turn among the employees in `responsibleList`, `himself` — employees take tasks themselves |\n| `flowData.responsibleList` | array | yes | Who receives the tasks: an array of pairs like `[\"user\", \"3\"]`, where the second element is the employee ID as a string. With `manually`, the list holds the flow moderator. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `flowData.groupId` | number | no | ID of the workgroup the flow is bound to. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist). If the field is not passed, a new group named after the flow is created |\n| `flowData.ownerId` | number | no | Flow administrator ID. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist). If the field is not passed, the employee on whose behalf the request is made becomes the administrator |\n| `flowData.description` | string | no | Flow description. Defaults to an empty string |\n| `flowData.taskCreators` | array | no | Who can submit tasks to the flow: an array of pairs. `[[\"meta-user\", \"all-users\"]]` — all employees |\n| `flowData.matchWorkTime` | number | no | `1` — weekends and holidays are skipped when the deadline is calculated, `0` — they are counted. Defaults to `1` |\n| `flowData.responsibleCanChangeDeadline` | number | no | `1` — the assignee can change the task deadline, `0` — cannot. Defaults to `1` |\n| `flowData.taskControl` | number | no | `1` — a completed task goes to its creator for review, `0` — no review. Defaults to `0` |\n| `flowData.notifyAtHalfTime` | number | no | `1` — remind the assignee halfway to the deadline, `0` — no reminder. Defaults to `0` |\n| `flowData.notifyOnQueueOverflow` | number | no | Notify the flow administrator when the number of tasks in the queue exceeds this value. Defaults to `null` — no notification |\n| `flowData.notifyOnTasksInProgressOverflow` | number | no | Notify the flow administrator when the number of tasks in progress exceeds this value. Defaults to `null` — no notification |\n| `flowData.notifyWhenEfficiencyDecreases` | number | no | Notify the flow administrator when efficiency drops below this value, in percent. Defaults to `null` — no notification |\n| `analyticsParams` | object | no | Internal Bitrix24 analytics tags. They do not affect the flow |\n\nThe body must not contain keys other than `flowData` and `analyticsParams`. The `matchWorkTime`, `responsibleCanChangeDeadline`, `taskControl`, and `notifyAtHalfTime` flags are passed as the numbers `1` and `0` and come back in the response as `true` and `false`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\" \\\n -H \"X-Api-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application\u002Fjson\" \\\n -d '{\n \"flowData\": {\n \"name\": \"Request processing\",\n \"description\": \"Customer requests from the website\",\n \"plannedCompletionTime\": 86400,\n \"distributionType\": \"queue\",\n \"responsibleList\": [[\"user\", \"3\"]]\n }\n }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\" \\\n -H \"X-Api-Key: YOUR_APP_KEY\" \\\n -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n -H \"Content-Type: application\u002Fjson\" \\\n -d '{\n \"flowData\": {\n \"name\": \"Request processing\",\n \"description\": \"Customer requests from the website\",\n \"plannedCompletionTime\": 86400,\n \"distributionType\": \"queue\",\n \"responsibleList\": [[\"user\", \"3\"]]\n }\n }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows', {\n method: 'POST',\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n 'Content-Type': 'application\u002Fjson',\n },\n body: JSON.stringify({\n flowData: {\n name: 'Request processing',\n description: 'Customer requests from the website',\n plannedCompletionTime: 86400,\n distributionType: 'queue',\n responsibleList: [['user', '3']],\n },\n }),\n})\n\nconst { success, data } = await res.json()\nif (success) {\n console.log('Flow ID:', data.id, 'Group ID:', data.groupId)\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows', {\n method: 'POST',\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n 'Content-Type': 'application\u002Fjson',\n },\n body: JSON.stringify({\n flowData: {\n name: 'Request processing',\n description: 'Customer requests from the website',\n plannedCompletionTime: 86400,\n distributionType: 'queue',\n responsibleList: [['user', '3']],\n },\n }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data` | object | The created flow. The set of fields is the same as in the [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) response |\n| `data.id` | number | ID of the new flow |\n| `data.creatorId` | number | ID of the employee on whose behalf the request was made |\n| `data.ownerId` | number | Flow administrator ID |\n| `data.groupId` | number | ID of the flow's workgroup. If the request had no `groupId`, the ID of the created group |\n| `data.active` | boolean | `true` — the flow is enabled. A new flow is created enabled |\n| `data.efficiency` | number | Flow efficiency in percent. For a new flow — `100` |\n| `data.activity` | string | Date and time of the flow's activity in ISO 8601 format. For a new flow — the moment of creation |\n| `data.taskCreators` | array | An empty array, even if `taskCreators` was passed in the request. The saved value is returned by [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) |\n| `data.team` | array | An empty array. The flow team is returned by [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) |\n\nFields from the request come back with the passed values; fields that were not passed come back with the defaults from the request fields table.\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"id\": 20,\n \"creatorId\": 1,\n \"ownerId\": 1,\n \"groupId\": 178,\n \"templateId\": 0,\n \"efficiency\": 100,\n \"active\": true,\n \"plannedCompletionTime\": 86400,\n \"activity\": \"2026-10-20T00:23:04+00:00\",\n \"name\": \"Request processing\",\n \"description\": \"Customer requests from the website\",\n \"distributionType\": \"queue\",\n \"responsibleList\": [\n [\"user\", \"3\"]\n ],\n \"demo\": false,\n \"responsibleCanChangeDeadline\": true,\n \"matchWorkTime\": true,\n \"matchSchedule\": false,\n \"taskControl\": false,\n \"notifyAtHalfTime\": false,\n \"notifyOnQueueOverflow\": null,\n \"notifyOnTasksInProgressOverflow\": null,\n \"notifyWhenEfficiencyDecreases\": null,\n \"taskCreators\": [],\n \"team\": [],\n \"trialFeatureEnabled\": false\n }\n}\n```\n\n## Error response example\n\n422 — the required `distributionType` field is not passed:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"BITRIX_ERROR\",\n \"message\": \"Property distributionType cannot be null\",\n \"b24Code\": \"0\"\n }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | The body is not an object or contains keys other than `flowData` and `analyticsParams`. Message: `body must be an object with supported fields only` |\n| 400 | `INVALID_PARAMS` | `flowData` is not passed or is not an object. Message: `flowData must be an object` |\n| 400 | `INVALID_PARAMS` | `analyticsParams` is not an object. Message: `analyticsParams must be an object` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key has neither the `task` nor the `tasks` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode. `error.details.switchUrl` holds the address of the section where the mode is changed |\n| 422 | `BITRIX_ERROR` | A required field is not passed. Messages: `Property name cannot be null`, `Property plannedCompletionTime cannot be null`, `Property distributionType cannot be null`, `'responsibleList': field's value must not be empty` |\n| 422 | `BITRIX_ERROR` | `distributionType` is not one of `manually`, `queue`, `himself`. Message: `distributionType: unexpected value` |\n| 422 | `BITRIX_ERROR` | `groupId` is not passed, and a group with the same name as the flow already exists on the portal, including one left over from a deleted flow. Message: `A group with this name already exists`, `error.b24Code` is `ERROR_GROUP_NAME_EXISTS` |\n| 429 | `RATE_LIMITED` | The request rate to Bitrix24 or to the platform is exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unreachable or returned a server error |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**Creation is not retried automatically.** The `502 BITRIX_UNAVAILABLE` and `503 BITRIX_TIMEOUT` responses do not tell whether the flow was created, and the platform does not retry such a request on its own. Before sending it again, look for the flow by name in [`GET \u002Fv1\u002Ftasks\u002Fflows`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list).\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [List flows](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list)\n- [Get a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get)\n- [Update a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-update)\n- [Toggle flow activity](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-activate)\n- [Employees](\u002Fdocs\u002Fentities\u002Fusers)\n- [Workgroups](\u002Fdocs\u002Fentities\u002Fworkgroups)\n","## List flows\n\n`GET \u002Fv1\u002Ftasks\u002Fflows`\n\nReturns one page of task flows in the Bitrix24 account, with filtering, sorting, and field selection passed as JSON in the query parameters.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `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\"]` |\n| `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}` |\n| `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\"}` |\n| `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 |\n| `start` (query) | number | no | `0` | Page offset in steps of 50. See the **Pagination** paragraph below |\n\nThe method accepts no other query parameters. URL-encode the values of `select`, `filter`, `order`, and `group`.\n\n**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.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -G \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\" \\\n --data-urlencode 'select=[\"ID\",\"NAME\",\"ACTIVE\"]' \\\n --data-urlencode 'filter={\">ID\":10}' \\\n --data-urlencode 'order={\"ID\":\"DESC\"}' \\\n -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -G \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\" \\\n --data-urlencode 'select=[\"ID\",\"NAME\",\"ACTIVE\"]' \\\n --data-urlencode 'filter={\">ID\":10}' \\\n --data-urlencode 'order={\"ID\":\"DESC\"}' \\\n -H \"X-Api-Key: YOUR_APP_KEY\" \\\n -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst query = new URLSearchParams({\n select: JSON.stringify(['ID', 'NAME', 'ACTIVE']),\n filter: JSON.stringify({ '>ID': 10 }),\n order: JSON.stringify({ ID: 'DESC' }),\n})\n\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows?${query}`, {\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Flows:', data.map((flow) => `${flow.id}: ${flow.name}`))\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst query = new URLSearchParams({\n select: JSON.stringify(['ID', 'NAME', 'ACTIVE']),\n filter: JSON.stringify({ '>ID': 10 }),\n order: JSON.stringify({ ID: 'DESC' }),\n})\n\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows?${query}`, {\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data` | array | Flows on the page. Past the last page, an empty array |\n| `data[].id` | number | Flow ID |\n| `data[].ownerId` | number | ID of the flow administrator. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `data[].creatorId` | number | ID of the employee who created the flow. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `data[].groupId` | number | ID of the flow's workgroup. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist) |\n| `data[].templateId` | number | ID of the template used to create tasks in the flow. `0` means no template. List: [`GET \u002Fv1\u002Ftask-templates`](\u002Fdocs\u002Fentities\u002Ftasks\u002Ftemplates-list) |\n| `data[].efficiency` | number | Flow efficiency as a percentage |\n| `data[].active` | boolean | `true` means the flow is enabled |\n| `data[].plannedCompletionTime` | number | Time to complete a task, in seconds |\n| `data[].activity` | string | Date and time of the flow's last activity, ISO 8601 with a time zone offset |\n| `data[].name` | string | Flow name |\n| `data[].description` | string | Flow description. An empty string when there is no description |\n| `data[].distributionType` | string | How tasks reach assignees: `manually` — a moderator distributes them, `queue` — in turn among employees, `himself` — employees take tasks themselves |\n| `data[].demo` | boolean | `true` means a Bitrix24 demo flow |\n\nWith `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 \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get).\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": [\n {\n \"id\": 15,\n \"active\": true,\n \"name\": \"Request handling\"\n },\n {\n \"id\": 13,\n \"active\": false,\n \"name\": \"Legal department\"\n },\n {\n \"id\": 11,\n \"active\": false,\n \"name\": \"Certificate requests to accounting\"\n }\n ]\n}\n```\n\n## Error response example\n\n422 — the field names in `select` are in lowercase:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"BITRIX_ERROR\",\n \"message\": \"Invalid select data\",\n \"b24Code\": \"0\"\n }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | A query parameter other than `select`, `filter`, `order`, `group`, and `start` was passed: `query contains unsupported fields` |\n| 400 | `INVALID_PARAMS` | `select` or `group` is not a JSON array: `select must be a JSON array`, `group must be a JSON array` |\n| 400 | `INVALID_PARAMS` | `filter` or `order` is not a JSON object: `filter must be a JSON object`, `order must be a JSON object` |\n| 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 |\n| 400 | `INVALID_PARAMS` | `start` is not a non-negative integer: `start must be a non-negative safe integer` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key does not have the `task` or `tasks` scope |\n| 422 | `BITRIX_ERROR` | `select` contains an unknown field name or a name not in uppercase: `Invalid select data` |\n| 422 | `BITRIX_ERROR` | `filter` contains an unknown field name or a name not in uppercase: `Invalid filter data` |\n| 422 | `BITRIX_ERROR` | `group` contains an unknown field name or a name not in uppercase: `Invalid group data` |\n| 422 | `BITRIX_ERROR` | `order` contains an unknown field name: `Incorrect sort field` |\n| 429 | `RATE_LIMITED` | The request rate limit of Bitrix24 or the platform was exceeded. Retry after the delay in the `Retry-After` header |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**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}`.\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [Get a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get)\n- [Create a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-create)\n- [Update a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-update)\n- [Tasks](\u002Fdocs\u002Fentities\u002Ftasks)\n","## Get a flow\n\n`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`\n\nReturns a task flow by ID, together with the settings that the flow list omits.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|----------|\n| `flowId` (path) | number | yes | Flow ID. List: [`GET \u002Fv1\u002Ftasks\u002Fflows`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\" \\\n -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\" \\\n -H \"X-Api-Key: YOUR_APP_KEY\" \\\n -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15', {\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n },\n})\n\nconst { success, data } = await res.json()\nconsole.log(`${data.name}: ${data.active ? 'enabled' : 'disabled'}`)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15', {\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data.id` | number | Flow ID |\n| `data.creatorId` | number | ID of the employee who created the flow. Get: [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget) |\n| `data.ownerId` | number | ID of the flow administrator. Get: [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget) |\n| `data.groupId` | number | ID of the flow's workgroup. `0` for a demo flow. Get: [`GET \u002Fv1\u002Fworkgroups\u002F:id`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fget) |\n| `data.templateId` | number | ID of the template used to create tasks in the flow. `0` means no template. Get: [`GET \u002Fv1\u002Ftask-templates\u002F:templateId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Ftemplates-get) |\n| `data.efficiency` | number | Flow efficiency as a percentage |\n| `data.active` | boolean | `true` means the flow is enabled |\n| `data.plannedCompletionTime` | number | Time to complete a task, in seconds |\n| `data.activity` | string | Date and time of the flow's last activity, ISO 8601 with a time zone offset |\n| `data.name` | string | Flow name |\n| `data.description` | string | Flow description. An empty string when there is no description |\n| `data.distributionType` | string | How tasks reach assignees: `manually` — a moderator distributes them, `queue` — in turn among employees, `himself` — employees take tasks themselves |\n| `data.responsibleList` | array | Who receives the tasks: an array of pairs such as `[\"user\", \"1\"]`, where the second element is the employee ID as a string. With `manually`, this is the moderator. An empty array for a demo flow. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `data.demo` | boolean | `true` means the flow is a Bitrix24 demo flow |\n| `data.responsibleCanChangeDeadline` | boolean | `true` means the assignee can change the task deadline |\n| `data.matchWorkTime` | boolean | `true` means weekends and holidays are skipped when the deadline is calculated |\n| `data.matchSchedule` | boolean | `true` means the deadline is counted only in working hours according to the work schedule, excluding weekends and holidays |\n| `data.taskControl` | boolean | `true` means a completed task goes to the task creator for review |\n| `data.notifyAtHalfTime` | boolean | `true` means the assignee gets a reminder halfway to the deadline |\n| `data.notifyOnQueueOverflow` | number \\| null | The administrator is notified when the number of pending tasks in the flow exceeds this value. `null` means the notification is off |\n| `data.notifyOnTasksInProgressOverflow` | number \\| null | The administrator is notified when the number of tasks in progress exceeds this value. `null` means the notification is off |\n| `data.notifyWhenEfficiencyDecreases` | number \\| null | The administrator is notified when flow efficiency drops below this value, as a percentage. `null` means the notification is off |\n| `data.taskCreators` | array | Who can create tasks in the flow: pairs of the same form as in `responsibleList`. `[\"meta-user\", \"all-users\"]` means all employees |\n| `data.team` | array | Employees who receive the flow's tasks: pairs of the same form as in `responsibleList`. An empty array for a demo flow |\n| `data.trialFeatureEnabled` | boolean | Internal Bitrix24 flag |\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"id\": 15,\n \"creatorId\": 29,\n \"ownerId\": 29,\n \"groupId\": 57,\n \"templateId\": 0,\n \"efficiency\": 0,\n \"active\": true,\n \"plannedCompletionTime\": 432000,\n \"activity\": \"2025-02-06T16:13:59+00:00\",\n \"name\": \"Request handling\",\n \"description\": \"Customer service requests\",\n \"distributionType\": \"himself\",\n \"responsibleList\": [\n [\n \"user\",\n \"1\"\n ]\n ],\n \"demo\": false,\n \"responsibleCanChangeDeadline\": true,\n \"matchWorkTime\": true,\n \"matchSchedule\": false,\n \"taskControl\": true,\n \"notifyAtHalfTime\": true,\n \"notifyOnQueueOverflow\": 50,\n \"notifyOnTasksInProgressOverflow\": 50,\n \"notifyWhenEfficiencyDecreases\": 70,\n \"taskCreators\": [\n [\n \"meta-user\",\n \"all-users\"\n ]\n ],\n \"team\": [\n [\n \"user\",\n \"1\"\n ]\n ],\n \"trialFeatureEnabled\": false\n }\n}\n```\n\n## Error response example\n\n422 — no flow with this ID exists:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"BITRIX_ERROR\",\n \"message\": \"Flow with this ID does not exist.\",\n \"b24Code\": \"0\"\n }\n}\n```\n\nThe `error.message` text comes in the language of the Bitrix24 account.\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `flowId` is not a positive integer: `flowId must be a positive safe integer` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key does not have the `task` or `tasks` scope |\n| 422 | `BITRIX_ERROR` | No flow with this `flowId` exists, or it was deleted: `Flow with this ID does not exist.` |\n| 429 | `RATE_LIMITED` | The request rate limit of Bitrix24 or the platform was exceeded. Retry after the delay in the `Retry-After` header |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [List flows](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list)\n- [Update a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-update)\n- [Toggle flow activity](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-activate)\n- [List pending flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-pending)\n- [Tasks](\u002Fdocs\u002Fentities\u002Ftasks)\n","## Update a flow\n\n`PATCH \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`\n\nChanges the settings of an existing task flow by its ID.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|----------|\n| `flowId` (path) | number | yes | Flow ID, a positive integer. List: [`GET \u002Fv1\u002Ftasks\u002Fflows`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `flowData` | object | yes | New values of the flow fields. Sent to Bitrix24 unchanged; the flow ID is taken from the path |\n| `flowData.id` | number | no | Flow ID. If passed, it must be a number equal to `flowId` from the path |\n| `flowData.name` | string | no | Flow name. It must not match the name of another flow in the Bitrix24 account |\n| `flowData.plannedCompletionTime` | number | no | Time to complete a task, in seconds, for example `86400` — one day |\n| `flowData.distributionType` | string | no | How tasks reach assignees: `manually` — a moderator assigns them, `queue` — in turn among the employees in `responsibleList`, `himself` — employees take tasks themselves |\n| `flowData.responsibleList` | array | no | Who receives the tasks: an array of pairs like `[\"user\", \"3\"]`, where the second element is the employee ID as a string. With `manually`, the list holds the flow moderator. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `flowData.groupId` | number | no | ID of the workgroup to bind the flow to. List: [`GET \u002Fv1\u002Fworkgroups`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Flist) |\n| `flowData.ownerId` | number | no | Flow administrator ID. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `flowData.taskCreators` | array | no | Who can submit tasks to the flow: an array of pairs. `[[\"meta-user\", \"all-users\"]]` — all employees |\n| `flowData.description` | string | no | Flow description. If not passed, reset to an empty string |\n| `flowData.matchWorkTime` | number | no | `1` — weekends and holidays are skipped when the deadline is calculated, `0` — they are counted. If not passed, reset to `1` |\n| `flowData.responsibleCanChangeDeadline` | number | no | `1` — the assignee can change the task deadline, `0` — cannot. If not passed, reset to `1` |\n| `flowData.taskControl` | number | no | `1` — a completed task goes to its creator for review, `0` — no review. If not passed, reset to `0` |\n| `flowData.notifyAtHalfTime` | number | no | `1` — remind the assignee halfway to the deadline, `0` — no reminder. If not passed, reset to `0` |\n| `flowData.notifyOnQueueOverflow` | number | no | Notify the flow administrator when the number of tasks in the queue exceeds this number. If not passed, reset to `null` — no notification |\n| `flowData.notifyOnTasksInProgressOverflow` | number | no | Notify the flow administrator when the number of tasks in progress exceeds this number. If not passed, reset to `null` — no notification |\n| `flowData.notifyWhenEfficiencyDecreases` | number | no | Notify the flow administrator when efficiency drops below this value, in percent. If not passed, reset to `null` — no notification |\n| `analyticsParams` | object | no | Internal Bitrix24 analytics tags. They do not affect the flow |\n\nThe body must not contain keys other than `flowData` and `analyticsParams`. Flags are passed as the numbers `1` and `0` and come back in the response as `true` and `false`.\n\n**Important:** the fields marked \"If not passed, reset to …\" are reset on every call, including a call with `\"flowData\": {}`. Other fields missing from `flowData` keep their current values. To change one setting without losing the others, read the flow with [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) and pass the resettable fields with their current values.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20\" \\\n -H \"X-Api-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application\u002Fjson\" \\\n -d '{\n \"flowData\": {\n \"name\": \"Website request processing\",\n \"description\": \"Customer requests from the website\",\n \"plannedCompletionTime\": 172800\n }\n }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20\" \\\n -H \"X-Api-Key: YOUR_APP_KEY\" \\\n -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n -H \"Content-Type: application\u002Fjson\" \\\n -d '{\n \"flowData\": {\n \"name\": \"Website request processing\",\n \"description\": \"Customer requests from the website\",\n \"plannedCompletionTime\": 172800\n }\n }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20', {\n method: 'PATCH',\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n 'Content-Type': 'application\u002Fjson',\n },\n body: JSON.stringify({\n flowData: {\n name: 'Website request processing',\n description: 'Customer requests from the website',\n plannedCompletionTime: 172800,\n },\n }),\n})\n\nconst { success, data } = await res.json()\nif (success) {\n console.log('New name:', data.name)\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20', {\n method: 'PATCH',\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n 'Content-Type': 'application\u002Fjson',\n },\n body: JSON.stringify({\n flowData: {\n name: 'Website request processing',\n description: 'Customer requests from the website',\n plannedCompletionTime: 172800,\n },\n }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data` | object | The flow after the change. The set of fields is the same as in the [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) response |\n| `data.id` | number | Flow ID |\n| `data.taskCreators` | array | An empty array, even if `taskCreators` was passed in the request or set earlier. The saved value is in [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) |\n| `data.team` | array | An empty array. The flow team is in [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) |\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"id\": 20,\n \"creatorId\": 1,\n \"ownerId\": 1,\n \"groupId\": 178,\n \"templateId\": 0,\n \"efficiency\": 100,\n \"active\": true,\n \"plannedCompletionTime\": 172800,\n \"activity\": \"2026-10-20T00:23:04+00:00\",\n \"name\": \"Website request processing\",\n \"description\": \"Customer requests from the website\",\n \"distributionType\": \"queue\",\n \"responsibleList\": [\n [\"user\", \"3\"]\n ],\n \"demo\": false,\n \"responsibleCanChangeDeadline\": true,\n \"matchWorkTime\": true,\n \"matchSchedule\": false,\n \"taskControl\": false,\n \"notifyAtHalfTime\": false,\n \"notifyOnQueueOverflow\": null,\n \"notifyOnTasksInProgressOverflow\": null,\n \"notifyWhenEfficiencyDecreases\": null,\n \"taskCreators\": [],\n \"team\": [],\n \"trialFeatureEnabled\": false\n }\n}\n```\n\n## Error response example\n\n422 — no flow with this `flowId` exists:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"BITRIX_ERROR\",\n \"message\": \"Unknown error. [Flow: 267]\",\n \"b24Code\": \"0\"\n }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `flowId` is not a positive integer. Message: `flowId must be a positive safe integer` |\n| 400 | `INVALID_PARAMS` | The body is not an object or contains keys other than `flowData` and `analyticsParams`. Message: `body must be an object with supported fields only` |\n| 400 | `INVALID_PARAMS` | `flowData` is not passed or is not an object. Message: `flowData must be an object` |\n| 400 | `INVALID_PARAMS` | `flowData.id` is not equal to `flowId` from the path or is passed as a string. Message: `flowData.id must match flowId` |\n| 400 | `INVALID_PARAMS` | `analyticsParams` is not an object. Message: `analyticsParams must be an object` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key has neither the `task` nor the `tasks` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode. `error.details.switchUrl` holds the address of the section where the mode is changed |\n| 422 | `BITRIX_ERROR` | No flow with this `flowId` exists. The message looks like `Unknown error. [Flow: 267]`; there is no `404` response in this case |\n| 422 | `BITRIX_ERROR` | The name is taken by another flow. Message: `A flow with this name already exists` |\n| 429 | `RATE_LIMITED` | The request rate to Bitrix24 or to the platform is exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unreachable or returned a server error |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [Get a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get)\n- [List flows](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list)\n- [Create a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-create)\n- [Toggle flow activity](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-activate)\n- [Employees](\u002Fdocs\u002Fentities\u002Fusers)\n- [Workgroups](\u002Fdocs\u002Fentities\u002Fworkgroups)\n","## Delete a flow\n\n`DELETE \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`\n\nDeletes a task flow by its ID.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|----------|\n| `flowId` (path) | number | yes | Flow ID, a positive integer. List: [`GET \u002Fv1\u002Ftasks\u002Fflows`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list) |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20\" \\\n -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20\" \\\n -H \"X-Api-Key: YOUR_APP_KEY\" \\\n -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20', {\n method: 'DELETE',\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n },\n})\n\nconst { success, data } = await res.json()\nif (success && data.deleted) {\n console.log('Flow deleted')\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20', {\n method: 'DELETE',\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n },\n})\n\nconst { success, data } = await res.json()\nif (success && data.deleted) {\n console.log('Flow deleted')\n}\n```\n\n## Response fields\n\nA successful deletion returns `200` with a body, not `204 No Content`.\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data.deleted` | boolean | `true` — the flow is deleted |\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"deleted\": true\n }\n}\n```\n\n## Error response example\n\n422 — no flow with this `flowId` exists, or it is already deleted:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"BITRIX_ERROR\",\n \"message\": \"Unknown error. [Flow: 312]\",\n \"b24Code\": \"0\"\n }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `flowId` is not a positive integer. Message: `flowId must be a positive safe integer` |\n| 400 | `FST_ERR_CTP_EMPTY_JSON_BODY` | The `Content-Type: application\u002Fjson` header is sent with an empty body. Remove the header |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key has neither the `task` nor the `tasks` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode. `error.details.switchUrl` holds the address of the section where the mode is changed |\n| 422 | `BITRIX_ERROR` | No flow with this `flowId` exists, including on a repeated deletion. The message looks like `Unknown error. [Flow: 312]`; there is no `404` response in this case |\n| 429 | `RATE_LIMITED` | The request rate to Bitrix24 or to the platform is exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unreachable or returned a server error |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**The flow's workgroup stays.** Deletion does not touch the group the flow was bound to, including a group created together with the flow. While the group exists, a new flow with the same name cannot be created without `groupId` — the response is `422` with the message `A group with this name already exists`. To delete the group as well, save the `groupId` from [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) before deleting the flow and call [`DELETE \u002Fv1\u002Fworkgroups\u002F:id`](\u002Fdocs\u002Fentities\u002Fworkgroups\u002Fdelete).\n\n**Disabling instead of deleting.** To stop a flow and keep its settings, disable it: [`POST \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Factivate`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-activate) switches an enabled flow to disabled.\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [List flows](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list)\n- [Get a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get)\n- [Create a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-create)\n- [Toggle flow activity](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-activate)\n- [Workgroups](\u002Fdocs\u002Fentities\u002Fworkgroups)\n","## Toggle flow activity\n\n`POST \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Factivate`\n\nTurns an inactive flow on and an active flow off: each call switches the flow to the opposite state.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `flowId` (path) | number | yes | Flow ID. List: [`GET \u002Fv1\u002Ftasks\u002Fflows`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list) |\n\nNo request body is required; fields in the body are ignored.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST 'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20\u002Factivate' \\\n -H 'X-Api-Key: YOUR_API_KEY'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST 'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20\u002Factivate' \\\n -H 'X-Api-Key: YOUR_APP_KEY' \\\n -H 'Authorization: Bearer USER_SESSION_TOKEN'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20\u002Factivate', {\n method: 'POST',\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n },\n})\nconst result = await response.json()\nconsole.log(result.data)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F20\u002Factivate', {\n method: 'POST',\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n },\n})\nconst result = await response.json()\nconsole.log(result.data)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` on success |\n| `data` | boolean | `true` — the flow was toggled. The response is the same whether the flow was turned on or off. Read the new state from the `active` field in [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get) |\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": true\n}\n```\n\n## Error response example\n\n422 — no flow with this ID exists:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"BITRIX_ERROR\",\n \"message\": \"Flow with this ID does not exist.\",\n \"b24Code\": \"0\"\n }\n}\n```\n\nThe `error.message` text comes in the Bitrix24 account language.\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `flowId` is not a positive integer: `flowId must be a positive safe integer` |\n| 400 | `FST_ERR_CTP_EMPTY_JSON_BODY` | The `Content-Type: application\u002Fjson` header is sent with an empty body. Remove the header |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key has neither the `task` nor the `tasks` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode. `error.details.switchUrl` holds the address of the section where the mode is changed |\n| 422 | `BITRIX_ERROR` | No flow with this `flowId` exists: `Flow with this ID does not exist.` |\n| 429 | `RATE_LIMITED` | The request rate to Bitrix24 or to the platform is exceeded. Retry after the delay in the `Retry-After` header |\n| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unreachable or returned a server error |\n| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**The toggle is not retried automatically.** The `503 BITRIX_TIMEOUT` and `502 BITRIX_UNAVAILABLE` responses do not tell whether the flow was toggled, and the platform does not retry such a call on its own: a retry would return the flow to its previous state. Before calling the method again, read the `active` field in [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get).\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [Get a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get)\n- [List flows](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list)\n- [Update a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-update)\n- [Tasks](\u002Fdocs\u002Fentities\u002Ftasks)\n","## List pending flow tasks\n\n`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Ftasks\u002Fpending`\n\nReturns the flow tasks that no one has started yet: the flow queue at the time of the call.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `flowId` (path) | number | yes | — | Flow ID, a positive integer. List: [`GET \u002Fv1\u002Ftasks\u002Fflows`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list) |\n| `start` (query) | number | no | `0` | Page offset in steps of 50, a non-negative integer. See the Pagination paragraph below |\n\n**Pagination.** The response is one page of up to 50 tasks; the total number of tasks in the list is in `data.totalCount`. `start` selects the page in steps of 50: values from `0` to `49` return the first page, `50` returns the second. Request the next page with `start` increased by exactly 50. Pages are not loaded automatically.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fpending\" \\\n -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fpending\" \\\n -H \"X-Api-Key: YOUR_APP_KEY\" \\\n -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fpending', {\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n },\n})\n\nconst { success, data } = await res.json()\nconsole.log(`Waiting to start: ${data.totalCount}`)\ndata.tasks.forEach((task) => {\n const taskId = Number(task.url.split('\u002F').at(-2))\n console.log(taskId, task.title, task.timeInStatus.formatted)\n})\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fpending', {\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data` | object | The list page and the total number of tasks |\n| `data.tasks` | array | Pending tasks on this page. An empty array if there are no pending tasks |\n| `data.tasks[].title` | string | Task title |\n| `data.tasks[].url` | string | Relative URL of the task in the Bitrix24 account. There is no separate task ID field: the ID is the last path segment, `4220` and `4222` in the example. The full task: [`GET \u002Fv1\u002Ftasks\u002F:id`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fget) |\n| `data.tasks[].serial` | number | Sequence number of the task in the response, starting from `1` |\n| `data.tasks[].creator` | object | Task creator |\n| `data.tasks[].creator.id` | string | Creator ID, as a string. Get: [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget) |\n| `data.tasks[].creator.name` | string | Employee display name |\n| `data.tasks[].creator.avatar` | string | Employee photo URL |\n| `data.tasks[].creator.workPosition` | string \\| null | Job title. Can be an empty string or `null` |\n| `data.tasks[].creator.pathToProfile` | string | Relative URL of the employee profile in the Bitrix24 account |\n| `data.tasks[].responsible` | object | Responsible person for the task. Same fields as `creator`. The ID is a string. Get: [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget) |\n| `data.tasks[].timeInStatus` | object | How long the task has been waiting since it was created |\n| `data.tasks[].timeInStatus.years`, `months`, `days`, `hours`, `minutes`, `seconds` | number | Duration components: years, months, days, hours, minutes, seconds |\n| `data.tasks[].timeInStatus.formatted` | string | Human-readable duration in the Bitrix24 account language, for example `1 minute`. A duration under a minute is also labeled `1 minute` |\n| `data.tasks[].canRead` | number | `1` — the employee on whose behalf the call is made can read the task |\n| `data.totalCount` | number | Total number of pending tasks in the flow, across all pages |\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"tasks\": [\n {\n \"title\": \"Prepare a sales proposal\",\n \"url\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002Ftasks\u002Ftask\u002Fview\u002F4220\u002F\",\n \"serial\": 1,\n \"creator\": {\n \"id\": \"15\",\n \"name\": \"Anna Smith\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fa1b\u002Favatar.jpg\",\n \"workPosition\": null,\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002F\"\n },\n \"responsible\": {\n \"id\": \"27\",\n \"name\": \"David Taylor\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fc2d\u002Favatar.jpg\",\n \"workPosition\": null,\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F27\u002F\"\n },\n \"timeInStatus\": {\n \"years\": 0,\n \"months\": 0,\n \"days\": 0,\n \"hours\": 0,\n \"minutes\": 0,\n \"seconds\": 9,\n \"formatted\": \"1 minute\"\n },\n \"canRead\": 1\n },\n {\n \"title\": \"Review the client contract\",\n \"url\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002Ftasks\u002Ftask\u002Fview\u002F4222\u002F\",\n \"serial\": 2,\n \"creator\": {\n \"id\": \"15\",\n \"name\": \"Anna Smith\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fa1b\u002Favatar.jpg\",\n \"workPosition\": null,\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002F\"\n },\n \"responsible\": {\n \"id\": \"27\",\n \"name\": \"David Taylor\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fc2d\u002Favatar.jpg\",\n \"workPosition\": null,\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F27\u002F\"\n },\n \"timeInStatus\": {\n \"years\": 0,\n \"months\": 0,\n \"days\": 0,\n \"hours\": 0,\n \"minutes\": 0,\n \"seconds\": 8,\n \"formatted\": \"1 minute\"\n },\n \"canRead\": 1\n }\n ],\n \"totalCount\": 2\n }\n}\n```\n\n## Error response example\n\n400 — the request contains a parameter the method does not accept, here `days`:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"INVALID_PARAMS\",\n \"message\": \"query contains unsupported fields\"\n }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | The request contains a parameter other than `start`, for example `days`. Message `query contains unsupported fields` |\n| 400 | `INVALID_PARAMS` | `flowId` is not a positive integer. Message `flowId must be a positive safe integer` |\n| 400 | `INVALID_PARAMS` | `start` is not a non-negative integer. Message `start must be a non-negative safe integer` |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `task` or `tasks` scope |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call. The text is in `error.message`; the Bitrix24 code, if any, is in `error.b24Code` |\n| 429 | `RATE_LIMITED` | The request rate to Bitrix24 or to the platform was exceeded. Retry after the delay in the `Retry-After` header |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**A nonexistent flow does not cause an error.** A nonexistent or deleted `flowId` returns `200` with an empty `tasks` and `\"totalCount\": 0`, just like a flow with no pending tasks. To check that the flow exists, use [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get).\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [List in-progress flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-progress)\n- [List completed flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-completed)\n- [Get a flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get)\n- [Start task](\u002Fdocs\u002Fentities\u002Ftasks\u002Fstart)\n- [Get task](\u002Fdocs\u002Fentities\u002Ftasks\u002Fget)\n","## List in-progress flow tasks\n\n`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Ftasks\u002Fprogress`\n\nReturns the flow tasks that are currently in progress: work on them has started but they are not completed yet.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `flowId` (path) | number | yes | — | Flow ID, a positive integer. List: [`GET \u002Fv1\u002Ftasks\u002Fflows`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list) |\n| `start` (query) | number | no | `0` | Page offset in steps of 50, a non-negative integer. See the Pagination paragraph below |\n\n**Pagination.** The response is one page of up to 50 tasks; the total number of tasks in the list is in `data.totalCount`. `start` selects the page in steps of 50: values from `0` to `49` return the first page, `50` returns the second. Request the next page with `start` increased by exactly 50. Pages are not loaded automatically.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fprogress\" \\\n -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fprogress\" \\\n -H \"X-Api-Key: YOUR_APP_KEY\" \\\n -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fprogress', {\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n },\n})\n\nconst { success, data } = await res.json()\nconsole.log(`In progress: ${data.totalCount}`)\ndata.tasks.forEach((task) => {\n const taskId = Number(task.url.split('\u002F').at(-2))\n console.log(taskId, task.title, task.responsible.name, task.timeInStatus.formatted)\n})\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fprogress', {\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data` | object | The list page and the total number of tasks |\n| `data.tasks` | array | In-progress tasks on this page. An empty array if there are no such tasks |\n| `data.tasks[].title` | string | Task title |\n| `data.tasks[].url` | string | Relative URL of the task in the Bitrix24 account. There is no separate task ID field: the ID is the last path segment, `4220` and `4222` in the example. The full task: [`GET \u002Fv1\u002Ftasks\u002F:id`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fget) |\n| `data.tasks[].serial` | number | Sequence number of the task in the response, starting from `1` |\n| `data.tasks[].creator` | object | Task creator |\n| `data.tasks[].creator.id` | string | Creator ID, as a string. Get: [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget) |\n| `data.tasks[].creator.name` | string | Employee display name |\n| `data.tasks[].creator.avatar` | string | Employee photo URL |\n| `data.tasks[].creator.workPosition` | string \\| null | Job title. Can be an empty string or `null` |\n| `data.tasks[].creator.pathToProfile` | string | Relative URL of the employee profile in the Bitrix24 account |\n| `data.tasks[].responsible` | object | Responsible person for the task. Same fields as `creator`. The ID is a string. Get: [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget) |\n| `data.tasks[].timeInStatus` | object | How long the task has been in progress since work on it started |\n| `data.tasks[].timeInStatus.years`, `months`, `days`, `hours`, `minutes`, `seconds` | number | Duration components: years, months, days, hours, minutes, seconds |\n| `data.tasks[].timeInStatus.formatted` | string | Human-readable duration in the Bitrix24 account language, for example `1 minute`. A duration under a minute is also labeled `1 minute` |\n| `data.tasks[].canRead` | number | `1` — the employee on whose behalf the call is made can read the task |\n| `data.totalCount` | number | Total number of in-progress tasks in the flow, across all pages |\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"tasks\": [\n {\n \"title\": \"Prepare a sales proposal\",\n \"url\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002Ftasks\u002Ftask\u002Fview\u002F4220\u002F\",\n \"serial\": 1,\n \"creator\": {\n \"id\": \"15\",\n \"name\": \"Anna Smith\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fa1b\u002Favatar.jpg\",\n \"workPosition\": null,\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002F\"\n },\n \"responsible\": {\n \"id\": \"27\",\n \"name\": \"David Taylor\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fc2d\u002Favatar.jpg\",\n \"workPosition\": null,\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F27\u002F\"\n },\n \"timeInStatus\": {\n \"years\": 0,\n \"months\": 0,\n \"days\": 0,\n \"hours\": 0,\n \"minutes\": 0,\n \"seconds\": 1,\n \"formatted\": \"1 minute\"\n },\n \"canRead\": 1\n },\n {\n \"title\": \"Review the client contract\",\n \"url\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002Ftasks\u002Ftask\u002Fview\u002F4222\u002F\",\n \"serial\": 2,\n \"creator\": {\n \"id\": \"15\",\n \"name\": \"Anna Smith\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fa1b\u002Favatar.jpg\",\n \"workPosition\": null,\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002F\"\n },\n \"responsible\": {\n \"id\": \"27\",\n \"name\": \"David Taylor\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fc2d\u002Favatar.jpg\",\n \"workPosition\": null,\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F27\u002F\"\n },\n \"timeInStatus\": {\n \"years\": 0,\n \"months\": 0,\n \"days\": 0,\n \"hours\": 0,\n \"minutes\": 0,\n \"seconds\": 0,\n \"formatted\": \"1 minute\"\n },\n \"canRead\": 1\n }\n ],\n \"totalCount\": 2\n }\n}\n```\n\n## Error response example\n\n400 — `start` is not a non-negative integer:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"INVALID_PARAMS\",\n \"message\": \"start must be a non-negative safe integer\"\n }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `start` is not a non-negative integer, for example `abc`. Message `start must be a non-negative safe integer` |\n| 400 | `INVALID_PARAMS` | The request contains a parameter other than `start`, for example `days`. Message `query contains unsupported fields` |\n| 400 | `INVALID_PARAMS` | `flowId` is not a positive integer. Message `flowId must be a positive safe integer` |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `task` or `tasks` scope |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call. The text is in `error.message`; the Bitrix24 code, if any, is in `error.b24Code` |\n| 429 | `RATE_LIMITED` | The request rate to Bitrix24 or to the platform was exceeded. Retry after the delay in the `Retry-After` header |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**A nonexistent flow does not cause an error.** A nonexistent or deleted `flowId` returns `200` with an empty `tasks` array and `\"totalCount\": 0`, just like a flow with no tasks in progress. To check that the flow exists, use [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get).\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [List pending flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-pending)\n- [List completed flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-completed)\n- [Get flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get)\n- [Complete task](\u002Fdocs\u002Fentities\u002Ftasks\u002Fcomplete)\n- [Get task](\u002Fdocs\u002Fentities\u002Ftasks\u002Fget)\n","## List completed flow tasks\n\n`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId\u002Ftasks\u002Fcompleted`\n\nReturns the flow tasks completed within the given number of recent days: the flow's output for the period.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `flowId` (path) | number | yes | — | Flow ID, a positive integer. List: [`GET \u002Fv1\u002Ftasks\u002Fflows`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-list) |\n| `days` (query) | number | yes | — | How many recent days to cover, by closing date. A non-negative integer. With `0` the list is empty, even if a task was closed a minute ago |\n| `start` (query) | number | no | `0` | Page offset in steps of 50, a non-negative integer. See the Pagination paragraph below |\n\n**Pagination.** The response is one page of up to 50 tasks; the total number of tasks in the list is in `data.totalCount`. `start` selects the page in steps of 50: values from `0` to `49` return the first page, `50` returns the second. Request the next page with `start` increased by exactly 50. Pages are not loaded automatically.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fcompleted?days=30\" \\\n -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X GET \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fcompleted?days=30\" \\\n -H \"X-Api-Key: YOUR_APP_KEY\" \\\n -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fcompleted?days=30', {\n headers: {\n 'X-Api-Key': 'YOUR_API_KEY',\n },\n})\n\nconst { success, data } = await res.json()\nconsole.log(`Completed in the last 30 days: ${data.totalCount}`)\ndata.tasks.forEach((task) => {\n const taskId = Number(task.url.split('\u002F').at(-2))\n console.log(taskId, task.title, task.responsible.name, task.timeInStatus.formatted)\n})\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Ftasks\u002Fflows\u002F15\u002Ftasks\u002Fcompleted?days=30', {\n headers: {\n 'X-Api-Key': 'YOUR_APP_KEY',\n 'Authorization': 'Bearer USER_SESSION_TOKEN',\n },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` on success |\n| `data` | object | The list page and the total number of tasks |\n| `data.tasks` | array | Completed tasks on this page. An empty array if no tasks were closed within `days` days |\n| `data.tasks[].title` | string | Task title |\n| `data.tasks[].url` | string | Relative URL of the task in the Bitrix24 account. There is no separate task ID field: the ID is the last path segment, `3737` and `3719` in the example. The full task: [`GET \u002Fv1\u002Ftasks\u002F:id`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fget) |\n| `data.tasks[].serial` | number | Sequence number of the task in the response, starting from `1` |\n| `data.tasks[].creator` | object | Task creator |\n| `data.tasks[].creator.id` | string | Creator ID, as a string. Get: [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget) |\n| `data.tasks[].creator.name` | string | Employee display name |\n| `data.tasks[].creator.avatar` | string | Employee photo URL |\n| `data.tasks[].creator.workPosition` | string \\| null | Job title. Can be an empty string or `null` |\n| `data.tasks[].creator.pathToProfile` | string | Relative URL of the employee profile in the Bitrix24 account |\n| `data.tasks[].responsible` | object | Responsible person for the task. Same fields as `creator`. The ID is a string, get: [`GET \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers\u002Fget) |\n| `data.tasks[].timeInStatus` | object | Time from task creation to its closing |\n| `data.tasks[].timeInStatus.years`, `months`, `days`, `hours`, `minutes`, `seconds` | number | Duration components: years, months, days, hours, minutes, seconds |\n| `data.tasks[].timeInStatus.formatted` | string | Duration as a label in the Bitrix24 account language, for example `8 days`. A duration under a minute is labeled `1 minute` |\n| `data.tasks[].canRead` | number | `1` — the employee on whose behalf the call is made can read the task |\n| `data.totalCount` | number | Total number of flow tasks closed within `days` days, across all pages |\n\n## Response example\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"tasks\": [\n {\n \"title\": \"Approve the supplier contract\",\n \"url\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002Ftasks\u002Ftask\u002Fview\u002F3737\u002F\",\n \"serial\": 1,\n \"creator\": {\n \"id\": \"15\",\n \"name\": \"Anna Smith\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fa1b\u002Favatar.jpg\",\n \"workPosition\": \"\",\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002F\"\n },\n \"responsible\": {\n \"id\": \"27\",\n \"name\": \"David Taylor\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fc2d\u002Favatar.jpg\",\n \"workPosition\": \"Sales manager\",\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F27\u002F\"\n },\n \"timeInStatus\": {\n \"years\": 0,\n \"months\": 0,\n \"days\": 8,\n \"hours\": 0,\n \"minutes\": 0,\n \"seconds\": 2,\n \"formatted\": \"8 days\"\n },\n \"canRead\": 1\n },\n {\n \"title\": \"Update the price list\",\n \"url\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002Ftasks\u002Ftask\u002Fview\u002F3719\u002F\",\n \"serial\": 2,\n \"creator\": {\n \"id\": \"15\",\n \"name\": \"Anna Smith\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fa1b\u002Favatar.jpg\",\n \"workPosition\": \"\",\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F15\u002F\"\n },\n \"responsible\": {\n \"id\": \"27\",\n \"name\": \"David Taylor\",\n \"avatar\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fupload\u002Fmain\u002Fc2d\u002Favatar.jpg\",\n \"workPosition\": \"Sales manager\",\n \"pathToProfile\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F27\u002F\"\n },\n \"timeInStatus\": {\n \"years\": 0,\n \"months\": 0,\n \"days\": 29,\n \"hours\": 0,\n \"minutes\": 0,\n \"seconds\": 17,\n \"formatted\": \"29 days\"\n },\n \"canRead\": 1\n }\n ],\n \"totalCount\": 2\n }\n}\n```\n\n## Error response example\n\n400 — `days` is not passed:\n\n```json\n{\n \"success\": false,\n \"error\": {\n \"code\": \"INVALID_PARAMS\",\n \"message\": \"days must be a non-negative safe integer\"\n }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_PARAMS` | `days` is not passed or is not a non-negative integer. Message `days must be a non-negative safe integer` |\n| 400 | `INVALID_PARAMS` | The request contains a parameter other than `days` and `start`. Message `query contains unsupported fields` |\n| 400 | `INVALID_PARAMS` | `flowId` is not a positive integer. Message `flowId must be a positive safe integer` |\n| 400 | `INVALID_PARAMS` | `start` is not a non-negative integer. Message `start must be a non-negative safe integer` |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` is missing |\n| 401 | `INVALID_API_KEY` | The key is not found |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |\n| 403 | `SCOPE_DENIED` | The key lacks the `task` or `tasks` scope |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call. The text is in `error.message`; the Bitrix24 code, if any, is in `error.b24Code` |\n| 429 | `RATE_LIMITED` | The request rate to Bitrix24 or to the platform was exceeded. Retry after the delay in the `Retry-After` header |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**A nonexistent flow does not cause an error.** A nonexistent or deleted `flowId` returns `200` with an empty `tasks` array and `\"totalCount\": 0`, just like a flow with no tasks completed within `days` days. To check that the flow exists, use [`GET \u002Fv1\u002Ftasks\u002Fflows\u002F:flowId`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get).\n\n**The `timeInStatus` numbers do not add up to the exact duration.** Only the largest unit, rounded to a whole number, and the seconds are filled in; the units between them are `0`. A task closed 28 days 19 hours after creation appears in the response as `\"days\": 29` with `\"hours\": 0` and `\"minutes\": 0`. For the exact completion time, use the `createdDate` and `closedDate` fields in [`GET \u002Fv1\u002Ftasks\u002F:id`](\u002Fdocs\u002Fentities\u002Ftasks\u002Fget).\n\n## See also\n\n- [Flows and flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows)\n- [List pending flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-pending)\n- [List in-progress flow tasks](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-progress)\n- [Get flow](\u002Fdocs\u002Fentities\u002Ftasks\u002Fflows-get)\n- [Complete task](\u002Fdocs\u002Fentities\u002Ftasks\u002Fcomplete)\n- [Get task](\u002Fdocs\u002Fentities\u002Ftasks\u002Fget)\n",1794739433985]