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

List pending flow tasks

GET /v1/tasks/flows/:flowId/tasks/pending

Returns the flow tasks that no one has started yet: the flow queue at the time of the call.

Parameters

Parameter Type Required Default Description
ParameterflowId (path) Typenumber Requiredyes Default— DescriptionFlow ID, a positive integer. List: GET /v1/tasks/flows
Parameterstart (query) Typenumber Requiredno Default0 DescriptionPage offset in steps of 50, a non-negative integer. See the Pagination paragraph below

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.

Examples

curl — personal key

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/tasks/flows/15/tasks/pending" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/tasks/flows/15/tasks/pending" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/flows/15/tasks/pending', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log(`Waiting to start: ${data.totalCount}`)
data.tasks.forEach((task) => {
  const taskId = Number(task.url.split('/').at(-2))
  console.log(taskId, task.title, task.timeInStatus.formatted)
})

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/flows/15/tasks/pending', {
  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 Typeobject DescriptionThe list page and the total number of tasks
Fielddata.tasks Typearray DescriptionPending tasks on this page. An empty array if there are no pending tasks
Fielddata.tasks[].title Typestring DescriptionTask title
Fielddata.tasks[].url Typestring DescriptionRelative 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 /v1/tasks/:id
Fielddata.tasks[].serial Typenumber DescriptionSequence number of the task in the response, starting from 1
Fielddata.tasks[].creator Typeobject DescriptionTask creator
Fielddata.tasks[].creator.id Typestring DescriptionCreator ID, as a string. Get: GET /v1/users/:id
Fielddata.tasks[].creator.name Typestring DescriptionEmployee display name
Fielddata.tasks[].creator.avatar Typestring DescriptionEmployee photo URL
Fielddata.tasks[].creator.workPosition Typestring | null DescriptionJob title. Can be an empty string or null
Fielddata.tasks[].creator.pathToProfile Typestring DescriptionRelative URL of the employee profile in the Bitrix24 account
Fielddata.tasks[].responsible Typeobject DescriptionResponsible person for the task. Same fields as creator. The ID is a string. Get: GET /v1/users/:id
Fielddata.tasks[].timeInStatus Typeobject DescriptionHow long the task has been waiting since it was created
Fielddata.tasks[].timeInStatus.years, months, days, hours, minutes, seconds Typenumber DescriptionDuration components: years, months, days, hours, minutes, seconds
Fielddata.tasks[].timeInStatus.formatted Typestring DescriptionHuman-readable duration in the Bitrix24 account language, for example 1 minute. A duration under a minute is also labeled 1 minute
Fielddata.tasks[].canRead Typenumber Description1 — the employee on whose behalf the call is made can read the task
Fielddata.totalCount Typenumber DescriptionTotal number of pending tasks in the flow, across all pages

Response example

JSON 
{
  "success": true,
  "data": {
    "tasks": [
      {
        "title": "Prepare a sales proposal",
        "url": "/company/personal/user/15/tasks/task/view/4220/",
        "serial": 1,
        "creator": {
          "id": "15",
          "name": "Anna Smith",
          "avatar": "https://example.bitrix24.com/upload/main/a1b/avatar.jpg",
          "workPosition": null,
          "pathToProfile": "/company/personal/user/15/"
        },
        "responsible": {
          "id": "27",
          "name": "David Taylor",
          "avatar": "https://example.bitrix24.com/upload/main/c2d/avatar.jpg",
          "workPosition": null,
          "pathToProfile": "/company/personal/user/27/"
        },
        "timeInStatus": {
          "years": 0,
          "months": 0,
          "days": 0,
          "hours": 0,
          "minutes": 0,
          "seconds": 9,
          "formatted": "1 minute"
        },
        "canRead": 1
      },
      {
        "title": "Review the client contract",
        "url": "/company/personal/user/15/tasks/task/view/4222/",
        "serial": 2,
        "creator": {
          "id": "15",
          "name": "Anna Smith",
          "avatar": "https://example.bitrix24.com/upload/main/a1b/avatar.jpg",
          "workPosition": null,
          "pathToProfile": "/company/personal/user/15/"
        },
        "responsible": {
          "id": "27",
          "name": "David Taylor",
          "avatar": "https://example.bitrix24.com/upload/main/c2d/avatar.jpg",
          "workPosition": null,
          "pathToProfile": "/company/personal/user/27/"
        },
        "timeInStatus": {
          "years": 0,
          "months": 0,
          "days": 0,
          "hours": 0,
          "minutes": 0,
          "seconds": 8,
          "formatted": "1 minute"
        },
        "canRead": 1
      }
    ],
    "totalCount": 2
  }
}

Error response example

400 — the request contains a parameter the method does not accept, here days:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "query contains unsupported fields"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe request contains a parameter other than start, for example days. Message query contains unsupported fields
HTTP400 CodeINVALID_PARAMS DescriptionflowId is not a positive integer. Message flowId must be a positive safe integer
HTTP400 CodeINVALID_PARAMS Descriptionstart is not a non-negative integer. Message start must be a non-negative safe integer
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key 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 lacks the task or tasks scope
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the call. The text is in error.message; the Bitrix24 code, if any, is in error.b24Code
HTTP429 CodeRATE_LIMITED DescriptionThe request rate to Bitrix24 or to the platform was exceeded. Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

Known specifics

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 /v1/tasks/flows/:flowId.

See also