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

List completed flow tasks

GET /v1/tasks/flows/:flowId/tasks/completed

Returns the flow tasks completed within the given number of recent days: the flow's output for the period.

Parameters

Parameter Type Required Default Description
ParameterflowId (path) Typenumber Requiredyes Default— DescriptionFlow ID, a positive integer. List: GET /v1/tasks/flows
Parameterdays (query) Typenumber Requiredyes Default— DescriptionHow 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
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/completed?days=30" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

const { success, data } = await res.json()
console.log(`Completed in the last 30 days: ${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/completed?days=30', {
  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 DescriptionCompleted tasks on this page. An empty array if no tasks were closed within days days
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, 3737 and 3719 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 DescriptionTime from task creation to its closing
Fielddata.tasks[].timeInStatus.years, months, days, hours, minutes, seconds Typenumber DescriptionDuration components: years, months, days, hours, minutes, seconds
Fielddata.tasks[].timeInStatus.formatted Typestring DescriptionDuration as a label in the Bitrix24 account language, for example 8 days. A duration under a minute is 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 flow tasks closed within days days, across all pages

Response example

JSON 
{
  "success": true,
  "data": {
    "tasks": [
      {
        "title": "Approve the supplier contract",
        "url": "/company/personal/user/15/tasks/task/view/3737/",
        "serial": 1,
        "creator": {
          "id": "15",
          "name": "Anna Smith",
          "avatar": "https://example.bitrix24.com/upload/main/a1b/avatar.jpg",
          "workPosition": "",
          "pathToProfile": "/company/personal/user/15/"
        },
        "responsible": {
          "id": "27",
          "name": "David Taylor",
          "avatar": "https://example.bitrix24.com/upload/main/c2d/avatar.jpg",
          "workPosition": "Sales manager",
          "pathToProfile": "/company/personal/user/27/"
        },
        "timeInStatus": {
          "years": 0,
          "months": 0,
          "days": 8,
          "hours": 0,
          "minutes": 0,
          "seconds": 2,
          "formatted": "8 days"
        },
        "canRead": 1
      },
      {
        "title": "Update the price list",
        "url": "/company/personal/user/15/tasks/task/view/3719/",
        "serial": 2,
        "creator": {
          "id": "15",
          "name": "Anna Smith",
          "avatar": "https://example.bitrix24.com/upload/main/a1b/avatar.jpg",
          "workPosition": "",
          "pathToProfile": "/company/personal/user/15/"
        },
        "responsible": {
          "id": "27",
          "name": "David Taylor",
          "avatar": "https://example.bitrix24.com/upload/main/c2d/avatar.jpg",
          "workPosition": "Sales manager",
          "pathToProfile": "/company/personal/user/27/"
        },
        "timeInStatus": {
          "years": 0,
          "months": 0,
          "days": 29,
          "hours": 0,
          "minutes": 0,
          "seconds": 17,
          "formatted": "29 days"
        },
        "canRead": 1
      }
    ],
    "totalCount": 2
  }
}

Error response example

400 — days is not passed:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptiondays is not passed or is not a non-negative integer. Message days must be a non-negative safe integer
HTTP400 CodeINVALID_PARAMS DescriptionThe request contains a parameter other than days and start. 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 array and "totalCount": 0, just like a flow with no tasks completed within days days. To check that the flow exists, use GET /v1/tasks/flows/:flowId.

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

See also