## Список задач
`GET /v1/tasks`
Возвращает список задач портала с поддержкой фильтрации, сортировки и авто-пагинации.
## Параметры
| Параметр | Тип | По умолч. | Описание |
|----------|-----|-----------|---------|
| `limit` | number | `50` | Количество записей (до 5000). При `limit > 50` API автоматически запрашивает несколько страниц |
| `offset` | number | `0` | Пропустить N записей. При `offset > 0` рекомендуется `limit ≤ 500` |
| `select` | string | — | Выборка полей: `?select=id,title,status,responsibleId` |
| `order` | object | `id desc` | Сортировка: `?order[id]=desc`, `?order[createdDate]=desc` |
| `filter` | object | — | Фильтрация по полям `GET /v1/tasks/fields`.
[Синтаксис фильтрации](/docs/filtering). Пример: `?filter[status]=2&filter[responsibleId]=1` |
| `withTotal` | string | — | Нужно ли количество: `true` или `false`. `false` — убрать количество из ответа. Это единственный способ гарантированно убрать `meta.total`. При `limit` больше 50 подсчёт платформе всё равно нужен для плана обхода, поэтому параметр убирает число, а не нагрузку. Без параметра — настройка ключа, затем платформенное умолчание. [Листание и количество](/docs/entity-api#листание-и-количество-записей) |
> **Какие даты фильтруются.** B24 `tasks.task.list` поддерживает фильтры по `createdDate`, `changedDate`, `closedDate`, `deadline`, `dateStart`. Поля `statusChangedDate` и `activityDate` **не фильтруются** на стороне Bitrix24 (их нет в списке фильтруемых полей метода) — такой фильтр будет молча проигнорирован. Используйте `changedDate` как ближайшую замену. Так же молча игнорируется фильтр по `timeSpentInLogs` — фактически затраченное время отбором не сужается, сумму по выборке даёт [агрегация](./aggregate.md). Соисполнители/наблюдатели фильтруются по одному пользователю: `?filter[accomplices]=25`, `?filter[auditors]=25`. Метки — `?filter[tags]=метка`.
> **`status` vs `realStatus`.** `filter[status]` в Битрикс24 — **виртуальный (мета-)фильтр**: значения `−1` (просрочена), `−2` (не просмотрена), `−3` (почти просрочена), а не число из поля `status` ответа — поэтому `filter[status]=2` вернёт не все задачи со статусом `2`: этот виртуальный фильтр присваивает каждой задаче ровно одно значение, и помеченные `−1`, `−2` или `−3` под условие не попадут. Для фильтра и сортировки по фактическому статусу используйте `realStatus`: `?filter[realStatus]=2` (ждёт выполнения), `?filter[realStatus]=5` (завершена), `?sort=realStatus`. Значение `realStatus` совпадает с полем `status` в ответе.
> **`meta.total` приходит не на каждый вызов.** При `limit` не больше 50 и `offset`, равном нулю, подсчёт можно не заказывать: если страница пришла короче `limit`, `meta.total` всё равно придёт с точным числом — коллекция на такой странице закончилась (пустой результат даёт `0`). Если страница пришла полной, поля не будет. При `limit` больше 50 `meta.total` приходит — подсчёт платформа выполняет, только когда без него не обойтись, — и убрать его оттуда можно явным `withTotal=false`. Проверяйте наличие поля в конкретном ответе, а листайте по `meta.hasMore`.
## Примеры
### curl — личный ключ
```bash
curl "https://vibecode.bitrix24.tech/v1/tasks?limit=10&filter[status]=2&order[id]=desc" \
-H "X-Api-Key: YOUR_API_KEY"
```
### curl — OAuth-приложение
```bash
curl "https://vibecode.bitrix24.tech/v1/tasks?limit=10&filter[status]=2&order[id]=desc" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
```
### JavaScript — личный ключ
```javascript
const url = 'https://vibecode.bitrix24.tech/v1/tasks?limit=10&filter[status]=2&order[id]=desc'
const res = await fetch(url, {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
},
})
const { success, data, meta } = await res.json()
console.log(`Получено ${data.length} из ${meta.total} задач`)
```
### JavaScript — OAuth-приложение
```javascript
const url = 'https://vibecode.bitrix24.tech/v1/tasks?limit=10&filter[status]=2&order[id]=desc'
const res = await fetch(url, {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const { success, data, meta } = await res.json()
```
## Поля ответа
| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив задач (все поля — см. [Поля задачи](./fields.md)) |
| `meta.total` | number | Общее количество записей, соответствующих фильтру. Необязательное поле — см. заметку выше |
| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |
URL карточки любой задачи из массива `data` строится из её `id` и ID сотрудника:
```
https://.bitrix24.ru/company/personal/user//tasks/task/view//
```
`` — ID ответственного (поле `responsibleId` каждого элемента): задача откроется в его личном кабинете. Сегмент `user/<...>` задаёт, в чьём кабинете отображается страница задач — подставьте ID нужного сотрудника, например текущего. `` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.
## Пример ответа
```json
{
"success": true,
"data": [
{
"id": 289,
"title": "Подготовить отчёт за квартал",
"status": 2,
"priority": 1,
"responsibleId": 79,
"createdBy": 99,
"createdDate": "2026-05-12T06:11:18.000Z",
"deadline": "2026-05-19T15:00:00.000Z",
"groupId": 0,
"accomplices": [],
"auditors": [],
"tags": {},
"notViewed": false,
"chatId": 3567,
"creator": {
"id": "99",
"name": "Анна Соколова",
"link": "/company/personal/user/99/"
},
"responsible": {
"id": "79",
"name": "Дмитрий Орлов",
"link": "/company/personal/user/79/"
}
}
],
"meta": {
"total": 184,
"hasMore": true
}
}
```
## Пример ответа при ошибке
403 — нет скоупа:
```json
{
"success": false,
"error": {
"code": "SCOPE_DENIED",
"message": "This endpoint requires 'tasks' scope"
}
}
```
## Ошибки
| HTTP | Код | Описание |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Передан некорректный или несуществующий ключ |
Полный список общих ошибок API — [Ошибки](/docs/errors).
## Известные особенности
**Когда переходить на `POST /v1/tasks/search`.** Если у запроса много условий фильтра или нужна выгрузка по большому диапазону дат, выбирайте `POST /v1/tasks/search` — параметры передаются в body, плюс доступно автоматическое разбиение запроса по временны́м окнам для выборок свыше 5000 записей. См. [Поиск задач](./search.md).
**Приведение типов работает на верхнем уровне, внутрь объектов не заходит.** Поля-карточки (`creator`, `responsible`, `group`, `accomplicesData`, `auditorsData`) объявлены объектами и приходят от Битрикс24 как есть — значения внутри них остаются в том виде, в каком их отдал портал, в том числе `creator.id` строкой (`"99"`). Это не то же самое, что верхнеуровневый `createdBy`, который приходит числом. Для арифметики по вложенному идентификатору приводите через `Number()`.
**Типы значений соответствуют схеме.** Поля, объявленные в [схеме](./fields.md) числами (`id`, `status`, `priority`, `responsibleId`, `createdBy`, `groupId`, `chatId` и подобные), приходят числами. Признаки «да/нет» приходят значениями `true`/`false`. Пустые `tags`, `group`, `accomplicesData`, `auditorsData` — пустым объектом `{}`. Приведение через `Number(value)` больше не требуется. Раньше эти значения приходили строками — если ваш код сравнивает их со строкой (`status === "2"`), его нужно поправить.
## Смотрите также
- [Получить задачу](./get.md)
- [Поиск задач](./search.md)
- [Поля задачи](./fields.md)
- [Агрегация задач](./aggregate.md)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Лимиты и оптимизация](/docs/optimization)