For AI agents: markdown of this page — /docs-content-en/entities/tasks/flows-list.md documentation index — /llms.txt

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
Parameterselect (query) Typestring Requiredno Defaultall fields DescriptionJSON 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"]
Parameterfilter (query) Typestring Requiredno Default— DescriptionJSON 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}
Parameterorder (query) Typestring Requiredno Defaultascending id DescriptionJSON 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"}
Parametergroup (query) Typestring Requiredno Default— DescriptionJSON array of field names in uppercase. It does not change the output: with ["ACTIVE"] you get the same list as without the parameter
Parameterstart (query) Typenumber Requiredno Default0 DescriptionPage 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

Terminal 
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

Terminal 
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
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typearray DescriptionFlows on the page. Past the last page, an empty array
Fielddata[].id Typenumber DescriptionFlow ID
Fielddata[].ownerId Typenumber DescriptionID of the flow administrator. List: GET /v1/users
Fielddata[].creatorId Typenumber DescriptionID of the employee who created the flow. List: GET /v1/users
Fielddata[].groupId Typenumber DescriptionID of the flow's workgroup. List: GET /v1/workgroups
Fielddata[].templateId Typenumber DescriptionID of the template used to create tasks in the flow. 0 means no template. List: GET /v1/task-templates
Fielddata[].efficiency Typenumber DescriptionFlow efficiency as a percentage
Fielddata[].active Typeboolean Descriptiontrue means the flow is enabled
Fielddata[].plannedCompletionTime Typenumber DescriptionTime to complete a task, in seconds
Fielddata[].activity Typestring DescriptionDate and time of the flow's last activity, ISO 8601 with a time zone offset
Fielddata[].name Typestring DescriptionFlow name
Fielddata[].description Typestring DescriptionFlow description. An empty string when there is no description
Fielddata[].distributionType Typestring DescriptionHow tasks reach assignees: manually — a moderator distributes them, queue — in turn among employees, himself — employees take tasks themselves
Fielddata[].demo Typeboolean Descriptiontrue 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.

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
HTTP400 CodeINVALID_PARAMS DescriptionA query parameter other than select, filter, order, group, and start was passed: query contains unsupported fields
HTTP400 CodeINVALID_PARAMS Descriptionselect or group is not a JSON array: select must be a JSON array, group must be a JSON array
HTTP400 CodeINVALID_PARAMS Descriptionfilter or order is not a JSON object: filter must be a JSON object, order must be a JSON object
HTTP400 CodeINVALID_PARAMS Descriptionselect, filter, order, or group was passed in bracket notation filter[…]=… instead of a JSON string: filter must be JSON, and likewise for the others
HTTP400 CodeINVALID_PARAMS Descriptionstart is not a non-negative integer: start must be a non-negative safe integer
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not found
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the task or tasks scope
HTTP422 CodeBITRIX_ERROR Descriptionselect contains an unknown field name or a name not in uppercase: Invalid select data
HTTP422 CodeBITRIX_ERROR Descriptionfilter contains an unknown field name or a name not in uppercase: Invalid filter data
HTTP422 CodeBITRIX_ERROR Descriptiongroup contains an unknown field name or a name not in uppercase: Invalid group data
HTTP422 CodeBITRIX_ERROR Descriptionorder contains an unknown field name: Incorrect sort field
HTTP429 CodeRATE_LIMITED DescriptionThe 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.

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