# История изменений задачи

`GET /v1/tasks/:taskId/history`

Возвращает историю изменений одной задачи целиком за один вызов — переходы по колонкам канбана, перемещения между спринтом и бэклогом, смены статуса, ответственного, срока и другие события. Применяется для восстановления фактического пути задачи по доске с реальными датами переходов.

Битрикс24 API: `tasks.task.history.list`
Скоуп: `task`

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|----------|
| `taskId` (path) | number | да | — | Идентификатор задачи. Источник: `GET /v1/tasks` |
| `field` (query) | string | нет | — | Фильтр по типу события. Одно значение — `?field=STAGE`, несколько — через запятую `?field=STAGE,MOVE_TO_SPRINT`. Переход по колонкам канбана — значение `STAGE`. Другие значения: `MOVE_TO_SPRINT`, `MOVE_TO_BACKLOG`, `STATUS`, `RESPONSIBLE_ID`, `DEADLINE`, `NEW`, `COMMENT`, `TAGS` и другие |
| `order` (query) | string | нет | `asc` | Порядок по дате: `asc` — от старых к новым, `desc` — от новых к старым |

Без параметра `field` метод возвращает события всех типов. Метод отдаёт всю историю задачи за один вызов — постраничного обхода нет, `meta.hasMore` всегда `false`.

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/tasks/61/history?field=STAGE&order=asc" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/tasks/61/history?field=STAGE&order=asc" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const params = new URLSearchParams({ field: 'STAGE', order: 'asc' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/tasks/61/history?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

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

### JavaScript — OAuth-приложение

```javascript
const params = new URLSearchParams({ field: 'STAGE', order: 'asc' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/tasks/61/history?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив событий, порядок задаётся параметром `order` |
| `data[].id` | number | Идентификатор записи журнала. Стабилен, подходит для проверки события на повтор |
| `data[].createdDate` | string | Момент события в часовом поясе пользователя (ISO 8601) |
| `data[].field` | string | Тип события: `STAGE`, `MOVE_TO_SPRINT`, `STATUS` и другие |
| `data[].value` | object | Прежнее и новое значение поля |
| `data[].value.from` | string \| null | Прежнее значение. Для `STAGE` — название колонки. Пустая строка или `null`, когда прежнего значения нет |
| `data[].value.to` | string \| null | Новое значение. Для `STAGE` — название колонки. `null` для событий без значения, например `NEW` |
| `data[].user` | object | Автор изменения |
| `data[].user.id` | number | Идентификатор автора. Источник: `GET /v1/users` |
| `meta.total` | number | Количество записей в ответе |
| `meta.hasMore` | boolean | Всегда `false` — ответ содержит всю историю задачи |

## Пример ответа

Задача 61, фильтр по колонкам канбана `field=STAGE`:

```json
{
  "success": true,
  "data": [
    {
      "id": 378,
      "createdDate": "2026-06-11T14:14:14+02:00",
      "field": "STAGE",
      "value": { "from": "", "to": "Беклог" },
      "user": { "id": 1 }
    },
    {
      "id": 413,
      "createdDate": "2026-06-17T00:35:43+02:00",
      "field": "STAGE",
      "value": { "from": "Работа со спецификациями", "to": "Ревью кода" },
      "user": { "id": 1 }
    }
  ],
  "meta": {
    "total": 22,
    "hasMore": false
  }
}
```

## Пример ответа при ошибке

400 — `taskId` не является положительным числом:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "taskId must be a positive integer"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `taskId` меньше единицы или не число |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `task` |
| 401 | `TOKEN_MISSING` | У ключа не настроены токены доступа |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Значение `value` для `STAGE` — название колонки.** Поля `value.from` и `value.to` для события `STAGE` содержат название колонки канбана на момент перехода, а не её идентификатор. Значение `value.from` пустое при первом попадании задачи на доску.

## Смотрите также

- [Стадии канбана задач](/docs/task-stages)
- [Задачи](/docs/entities/tasks)
- [Справочник сущностей](/docs/entity-api)
- [Ошибки](/docs/errors)