# 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`](/docs/entities/workgroups/list) |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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](/docs/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

- [Task kanban stages](/docs/task-stages)
- [Tasks: kanban, My Plan and day plan](/docs/tasks)
- [Create a task stage](/docs/tasks/stages)
- [Update a task stage](/docs/task-stages/update)
- [Delete an empty task stage](/docs/task-stages/delete)
- [Move a task with ordering](/docs/tasks/move-stage)
- [Task change history](/docs/task-history)
- [Tasks](/docs/entities/tasks)
- [API overview](/docs/entity-api)
- [Errors](/docs/errors)