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

List task kanban stages

GET /v1/tasks/stages/:entityId

Returns the current kanban columns of a workgroup or the key owner's My Plan. Use it to display the board's set of stages and their order.

Scope: task

Parameters

Parameter Type Required Default Description
entityId (path) number yes — Owner of the stages: a workgroup identifier or 0 — the key owner's My Plan. Group list: GET /v1/workgroups

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/tasks/stages/7" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/stages/7', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of columns, sorted by sort
data[].id number Stage identifier
data[].title string Column name
data[].sort number Sort order on the board
data[].color string Column color in RRGGBB format
data[].systemType string | null NEW for the default stage, which is the first on the board, null for the others
data[].entityId number Owner identifier — group or user
data[].entityType string Owner type: G — group, U — My Plan

Response example

Kanban stages of group 7:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 87,
      "title": "New",
      "sort": 100,
      "color": "00C4FB",
      "systemType": "NEW",
      "entityId": 7,
      "entityType": "G"
    },
    {
      "id": 88,
      "title": "In progress",
      "sort": 200,
      "color": "47D1E2",
      "systemType": null,
      "entityId": 7,
      "entityType": "G"
    },
    {
      "id": 89,
      "title": "Done",
      "sort": 300,
      "color": "75D900",
      "systemType": null,
      "entityId": 7,
      "entityType": "G"
    }
  ]
}

Error response example

400 — entityId is less than zero:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "entityId must be a non-negative integer (0 = personal plan)"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS entityId is less than zero or not a number
400 UNSUPPORTED_FILTER A filter parameter was passed, and this endpoint has none. The error text names what to use instead
403 BITRIX_ACCESS_DENIED No access to this group's tasks, or no group exists with the given entityId
403 SCOPE_DENIED The key lacks the task or tasks scope
401 TOKEN_MISSING The key has no access tokens configured
401 MISSING_API_KEY The X-Api-Key header was not passed
422 BITRIX_ERROR Bitrix24 rejected the request; the text is in message

Full list of common API errors — Errors.

Known specifics

Bitrix24 account administrator rights do not grant access to other groups. If the key's user is not a member of the group, reading its stages returns 403 BITRIX_ACCESS_DENIED, even when that user is a Bitrix24 account administrator.

A new group already has a kanban. The first read of a newly created group's stages returns three default stages: "New", "In progress", "Done".

Group columns and task history do not match. The method returns the current columns of the group kanban. In the task history, the STAGE event stores the stage name at the moment of transition — it may differ from the group's current columns, and sprint stages are not part of the group kanban. To analyze past transitions, rely on the value from the history rather than on this reference.

See also