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

List in-progress flow tasks

GET /v1/tasks/flows/:flowId/tasks/progress

Returns the flow tasks that are currently in progress: work on them has started but they are not completed yet.

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/progress" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/tasks/flows/15/tasks/progress" \
  -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/progress', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/flows/15/tasks/progress', {
  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 DescriptionIn-progress tasks on this page. An empty array if there are no such 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 in progress since work on it started
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 in-progress 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": 1,
          "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": 0,
          "formatted": "1 minute"
        },
        "canRead": 1
      }
    ],
    "totalCount": 2
  }
}

Error response example

400 — start is not a non-negative integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "start must be a non-negative safe integer"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionstart is not a non-negative integer, for example abc. Message start must be a non-negative safe integer
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
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 array and "totalCount": 0, just like a flow with no tasks in progress. To check that the flow exists, use GET /v1/tasks/flows/:flowId.

See also