[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-entities\u002Ftasks":3,"docs-tabs-entities\u002Ftasks":6},{"content":4,"lastmod":5},"# Задачи\n\nУправление задачами портала: создание, чтение, обновление, удаление, фильтрация, агрегация. Задача — единица работы с ответственным, постановщиком, сроком и статусом. У одной задачи могут быть комментарии и записи учёта времени — это отдельные вложенные ресурсы.\n\nБитрикс24 API: `tasks.task.*`\nСкоуп: `tasks`\n\n## Операции\n\n- [Создать задачу](.\u002Ftasks\u002Fcreate.md) — `POST \u002Fv1\u002Ftasks`\n- [Список задач](.\u002Ftasks\u002Flist.md) — `GET \u002Fv1\u002Ftasks`\n- [Получить задачу](.\u002Ftasks\u002Fget.md) — `GET \u002Fv1\u002Ftasks\u002F:id`\n- [Обновить задачу](.\u002Ftasks\u002Fupdate.md) — `PATCH \u002Fv1\u002Ftasks\u002F:id`\n- [Удалить задачу](.\u002Ftasks\u002Fdelete.md) — `DELETE \u002Fv1\u002Ftasks\u002F:id`\n- [Поиск задач](.\u002Ftasks\u002Fsearch.md) — `POST \u002Fv1\u002Ftasks\u002Fsearch`\n- [Поля задачи](.\u002Ftasks\u002Ffields.md) — `GET \u002Fv1\u002Ftasks\u002Ffields`\n- [Агрегация задач](.\u002Ftasks\u002Faggregate.md) — `POST \u002Fv1\u002Ftasks\u002Faggregate`\n\nУ задачи есть вложенные ресурсы со своими CRUD-операциями: [Комментарии задач](.\u002Ftask-comments.md) (`\u002Fv1\u002Ftasks\u002F:taskId\u002Fcomments`), [Учёт времени задач](.\u002Ftasks\u002Ftime.md) (`\u002Fv1\u002Ftasks\u002F:taskId\u002Ftime`) и [Чат задачи](.\u002Ftasks\u002Fchat.md) (`GET \u002Fv1\u002Ftasks\u002F:taskId\u002Fchat\u002Fmessages`). Скрам-размещение задачи (бэклог\u002Fспринт, эпик, story points) — отдельный раздел [Scrum API](\u002Fdocs\u002Fscrum).\n\nИстория изменений задачи и текущие стадии канбана доступны отдельными эндпоинтами для чтения: [История изменений задачи](\u002Fdocs\u002Ftask-history) (`GET \u002Fv1\u002Ftasks\u002F:taskId\u002Fhistory`) и [Стадии канбана задач](\u002Fdocs\u002Ftask-stages) (`GET \u002Fv1\u002Ftasks\u002Fstages\u002F:entityId`).\n\n## Ключевые поля\n\n| Поле | Описание |\n|------|---------|\n| `title` | Название задачи |\n| `description` | Текст задачи (поддерживает BB-код, флаг `descriptionInBbcode`) |\n| `responsibleId` | Ответственный. Список сотрудников: `GET \u002Fv1\u002Fusers` |\n| `createdBy` | Постановщик. По умолчанию — пользователь ключа; можно передать при создании (в пределах прав B24-пользователя). Список сотрудников: `GET \u002Fv1\u002Fusers` |\n| `status` | Статус задачи (число). Расшифровка значений: `GET \u002Fv1\u002Ftasks\u002Ffields` → `fields.status.enum` |\n| `priority` | Приоритет (число). Расшифровка значений: `GET \u002Fv1\u002Ftasks\u002Ffields` → `fields.priority.enum` |\n| `deadline` | Крайний срок (ISO 8601) |\n| `groupId` | Рабочая группа. Список: `GET \u002Fv1\u002Fworkgroups` |\n\nПолный список полей — [`GET \u002Fv1\u002Ftasks\u002Ffields`](.\u002Ftasks\u002Ffields.md).\n\n## Что нужно знать перед работой\n\n1. **Минимум для создания:** `title` и `responsibleId`. Если ответственный не указан, портал возвращает ошибку «Не указан исполнитель».\n2. **Статус и приоритет — числовые коды**, а не строки. Полная таблица соответствий приходит в ответе `GET \u002Fv1\u002Ftasks\u002Ffields` в поле `fields.status.enum` \u002F `fields.priority.enum`. Например, `status: 2` — задача ждёт выполнения, `status: 5` — завершена.\n3. **`realStatus` — имя только для ФИЛЬТРА, в ответах его нет.** `status` (виртуальный) приходит и в списке, и в карточке; `subStatus` приходит **только в списке** — карточка `GET \u002Fv1\u002Ftasks\u002F:id` его НЕ возвращает (под-статус просрочки `-1`\u002F`-2`\u002F`-3` читается только из списка). Для просроченных и почти просроченных задач `status`\u002F`subStatus` принимают значения `-1` \u002F `-2` \u002F `-3` поверх реальных `1..7`. `REAL_STATUS` — фильтруемое поле B24 (реальный хранимый статус, всегда `1..7`); ключа `realStatus` в JSON-ответе не бывает — читайте `status` + `subStatus`. Из этого выходит ловушка фильтрации: запрос `?filter[STATUS][]=2&filter[STATUS][]=3&filter[STATUS][]=4` тихо теряет просроченные задачи — у них `STATUS = -2`, хотя `REAL_STATUS` всё ещё `2`. Рецепты по сценариям:\n   - «Активные без просроченных»: `filter[STATUS][]=2&filter[STATUS][]=3&filter[STATUS][]=4`.\n   - «Активные включая просроченные»: `filter[REAL_STATUS][]=2&filter[REAL_STATUS][]=3&filter[REAL_STATUS][]=4`.\n   - «Только просроченные»: `filter[STATUS]=-2`.\n4. **Числовые поля сериализуются строками.** В ответах списка и одиночной задачи поля-идентификаторы (`id`, `responsibleId`, `createdBy`, `groupId`) и числовые перечисления (`status`, `priority`) приходят как строки, например `\"id\": \"289\"`, `\"status\": \"2\"`. Конвертация на стороне клиента — простой `Number(...)`.\n5. **Даты в собственном часовом поясе портала.** Поля `createdDate`, `changedDate`, `closedDate`, `deadline` и подобные приходят в формате ISO 8601 со смещением (`2026-05-12T11:46:12+03:00`), а не в UTC. Для расчётов приводите к `Date` или `Date.parse`.\n6. **Пользователи внутри задачи.** Поля `creator` и `responsible` приходят встроенно как объекты вида `{ id, name, link, icon, workPosition }` — отдельный запрос на профили не нужен.\n7. **`accomplices` и `auditors` — массивы строковых идентификаторов** пользователей (соисполнители и наблюдатели). Если задача только что создана и в ней нет соисполнителей и наблюдателей, поля приходят пустыми массивами.\n\n## Типичный сценарий\n\n1. Найти ответственного: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) (или фильтрованный поиск с нужным именем).\n2. Создать задачу: [`POST \u002Fv1\u002Ftasks`](.\u002Ftasks\u002Fcreate.md) с `title` и `responsibleId`.\n3. Дополнить детали: [`PATCH \u002Fv1\u002Ftasks\u002F:id`](.\u002Ftasks\u002Fupdate.md) — `deadline`, `priority`, `description`, `auditors`.\n4. Зафиксировать прогресс — комментарий: [`POST \u002Fv1\u002Ftasks\u002F:taskId\u002Fcomments`](.\u002Ftask-comments\u002Fcreate.md).\n5. Учесть время: [`POST \u002Fv1\u002Ftasks\u002F:taskId\u002Ftime`](.\u002Ftasks\u002Ftime\u002Fcreate.md).\n6. Закрыть задачу: [`PATCH \u002Fv1\u002Ftasks\u002F:id`](.\u002Ftasks\u002Fupdate.md) → `status: 5`.\n\n## Лимиты\n\n| Лимит | Значение |\n|-------|----------|\n| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |\n| Авто-пагинация | включается при `limit > 50` |\n| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |\n| Разбиение по временны́м окнам для больших выборок | `POST \u002Fv1\u002Ftasks\u002Fsearch` с `autoWindow: true` |\n| Batch-запросы | до 50 операций в [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch) |\n| Rate limit | общий для API — см. [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) |\n\n## Смотрите также\n\n- [Комментарии задач](.\u002Ftask-comments.md)\n- [Учёт времени задач](.\u002Ftasks\u002Ftime.md)\n- [История изменений задачи](\u002Fdocs\u002Ftask-history)\n- [Стадии канбана задач](\u002Fdocs\u002Ftask-stages)\n- [Справочник сущностей](\u002Fdocs\u002Fentity-api)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch-запросы](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","2026-07-15",{"tasks\u002Fcreate.md":7,"tasks\u002Flist.md":8,"tasks\u002Fget.md":9,"tasks\u002Fupdate.md":10,"tasks\u002Fdelete.md":11,"tasks\u002Fsearch.md":12,"tasks\u002Ffields.md":13,"tasks\u002Faggregate.md":14},"\n## Создать задачу\n\n`POST \u002Fv1\u002Ftasks`\n\nСоздаёт новую задачу. Минимум — название и ответственный.\n\n## Поля запроса (body)\n\n| Поле | Тип | Обяз. | Описание |\n|------|-----|:-----:|---------|\n| `title` | string | ★ | Название задачи |\n| `responsibleId` | number | ★ | Ответственный. Список сотрудников: `GET \u002Fv1\u002Fusers` |\n| `description` | string | | Описание задачи. Поддерживает BB-код (`[USER=ID]Имя[\u002FUSER]`, `[B]...[\u002FB]`, `[QUOTE]...[\u002FQUOTE]`) |\n| `priority` | number | | Приоритет: `0` — низкий, `1` — обычный (по умолчанию), `2` — высокий |\n| `status` | number | | Статус. По умолчанию `2` (ждёт выполнения). Полный список значений: `GET \u002Fv1\u002Ftasks\u002Ffields` → `fields.status.enum` |\n| `deadline` | datetime | | Крайний срок (ISO 8601) |\n| `startDatePlan` | datetime | | Плановая дата начала |\n| `endDatePlan` | datetime | | Плановая дата окончания |\n| `timeEstimate` | number | | Оценка трудозатрат в секундах |\n| `groupId` | number | | Рабочая группа. Список: `GET \u002Fv1\u002Fworkgroups` |\n| `parentId` | number | | Родительская задача. Список: `GET \u002Fv1\u002Ftasks` |\n| `accomplices` | number[] | | Соисполнители. Список сотрудников: `GET \u002Fv1\u002Fusers` |\n| `auditors` | number[] | | Наблюдатели. Список сотрудников: `GET \u002Fv1\u002Fusers` |\n| `tags` | string[] | | Метки задачи (массив строк-имён; принимаются прямо при создании) |\n| `createdBy` | number | | Постановщик. По умолчанию — пользователь ключа; переопределение применяется в пределах прав B24-пользователя |\n\nПолный список полей — [`GET \u002Fv1\u002Ftasks\u002Ffields`](.\u002Ffields.md). Поля `id`, `dateStart`, `createdDate`, `changedDate`, `closedDate`, `activityDate` заполняются системой и в body не передаются.\n\n> ⚠️ `title` ограничен 250 символами — более длинное название отклоняется порталом с ошибкой `TASKS_BAD_TITLE`.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"title\": \"Подготовить отчёт за квартал\",\n    \"responsibleId\": 1,\n    \"priority\": 2,\n    \"deadline\": \"2026-05-19T18:00:00+03:00\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"title\": \"Подготовить отчёт за квартал\",\n    \"responsibleId\": 1,\n    \"priority\": 2,\n    \"deadline\": \"2026-05-19T18:00:00+03:00\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    title: 'Подготовить отчёт за квартал',\n    responsibleId: 1,\n    priority: 2,\n    deadline: '2026-05-19T18:00:00+03:00',\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('ID новой задачи:', data.id)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    title: 'Подготовить отчёт за квартал',\n    responsibleId: 1,\n    priority: 2,\n    deadline: '2026-05-19T18:00:00+03:00',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | object | Полный объект созданной задачи (как у `GET \u002Fv1\u002Ftasks\u002F:id`) — см. [Поля задачи](.\u002Ffields.md) |\n\nURL карточки задачи в Битрикс24 строится из `id` и ID сотрудника:\n\n```\nhttps:\u002F\u002F\u003Cportal>.bitrix24.ru\u002Fcompany\u002Fpersonal\u002Fuser\u002F\u003CresponsibleId>\u002Ftasks\u002Ftask\u002Fview\u002F\u003Cid>\u002F\n```\n\n`\u003CresponsibleId>` — ID ответственного (поле `responsibleId` в ответе): задача откроется в его личном кабинете. Сегмент `user\u002F\u003C...>` задаёт, в чьём кабинете отображается страница задач — подставьте ID нужного сотрудника, например текущего. `\u003Cportal>` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"3871\",\n    \"title\": \"Подготовить отчёт за квартал\",\n    \"description\": \"\",\n    \"status\": \"2\",\n    \"priority\": \"2\",\n    \"responsibleId\": \"1\",\n    \"createdBy\": \"1\",\n    \"createdDate\": \"2026-05-12T11:46:12+03:00\",\n    \"deadline\": \"2026-05-19T18:00:00+03:00\",\n    \"groupId\": \"0\",\n    \"accomplices\": [],\n    \"auditors\": [],\n    \"creator\": {\n      \"id\": \"1\",\n      \"name\": \"Текущий пользователь\",\n      \"link\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F1\u002F\"\n    },\n    \"responsible\": {\n      \"id\": \"1\",\n      \"name\": \"Текущий пользователь\",\n      \"link\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F1\u002F\"\n    }\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n422 — не указан ответственный:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Не указан исполнитель\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Битрикс24 отклонил создание задачи — например, не передано обязательное поле `title` или `responsibleId`, либо переданное значение отклонено порталом |\n| 400 | `READONLY_FIELD` | В теле запроса передано поле, доступное только на чтение (`id`, `dateStart`, `createdDate`, `changedDate`, `closedDate`, `activityDate`) |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Поля задачи](.\u002Ffields.md) — что можно передавать\n- [Получить задачу](.\u002Fget.md) — чтение деталей\n- [Обновить задачу](.\u002Fupdate.md) — изменить состояние или сроки\n- [Список задач](.\u002Flist.md) — поиск задач после создания\n- [Batch-запросы](\u002Fdocs\u002Fbatch) — массовое создание\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) — rate limits\n","\n## Список задач\n\n`GET \u002Fv1\u002Ftasks`\n\nВозвращает список задач портала с поддержкой фильтрации, сортировки и авто-пагинации.\n\n## Параметры\n\n| Параметр | Тип | По умолч. | Описание |\n|----------|-----|-----------|---------|\n| `limit` | number | `50` | Количество записей (до 5000). При `limit > 50` API автоматически запрашивает несколько страниц |\n| `offset` | number | `0` | Пропустить N записей. При `offset > 0` рекомендуется `limit ≤ 500` |\n| `select` | string | — | Выборка полей: `?select=id,title,status,responsibleId` |\n| `order` | object | `id desc` | Сортировка: `?order[id]=desc`, `?order[createdDate]=desc` |\n| `filter` | object | — | Фильтрация по полям `GET \u002Fv1\u002Ftasks\u002Ffields`.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering). Пример: `?filter[status]=2&filter[responsibleId]=1` |\n\n> ⚠ **Какие даты фильтруются.** B24 `tasks.task.list` поддерживает фильтры по `createdDate`, `changedDate`, `closedDate`, `deadline`, `dateStart`. Поля `statusChangedDate` и `activityDate` **не фильтруются** на стороне Bitrix24 (их нет в списке фильтруемых полей метода) — такой фильтр будет молча проигнорирован; используйте `changedDate` как ближайшую замену. Соисполнители\u002Fнаблюдатели фильтруются по одному пользователю: `?filter[accomplices]=25`, `?filter[auditors]=25`; метки — `?filter[tags]=метка`.\n\n> ⚠ **`status` vs `realStatus`.** `filter[status]` в Bitrix24 — **виртуальный (мета-)фильтр**: значения `−1` (просрочена), `−2` (не просмотрена), `−3` (почти просрочена), а не число из поля `status` ответа — поэтому `filter[status]=2` не вернёт задачи со статусом `2`. Для фильтра и сортировки по фактическому статусу используйте `realStatus`: `?filter[realStatus]=2` (ждёт выполнения), `?filter[realStatus]=5` (завершена), `?sort=realStatus`. Значение `realStatus` совпадает с полем `status` в ответе.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks?limit=10&filter[status]=2&order[id]=desc\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks?limit=10&filter[status]=2&order[id]=desc\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst url = 'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks?limit=10&filter[status]=2&order[id]=desc'\nconst res = await fetch(url, {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`Получено ${data.length} из ${meta.total} задач`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst url = 'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks?limit=10&filter[status]=2&order[id]=desc'\nconst res = await fetch(url, {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив задач (все поля — см. [Поля задачи](.\u002Ffields.md)) |\n| `meta.total` | number | Общее количество записей, соответствующих фильтру |\n| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |\n\nURL карточки любой задачи из массива `data` строится из её `id` и ID сотрудника:\n\n```\nhttps:\u002F\u002F\u003Cportal>.bitrix24.ru\u002Fcompany\u002Fpersonal\u002Fuser\u002F\u003CresponsibleId>\u002Ftasks\u002Ftask\u002Fview\u002F\u003Cid>\u002F\n```\n\n`\u003CresponsibleId>` — ID ответственного (поле `responsibleId` каждого элемента): задача откроется в его личном кабинете. Сегмент `user\u002F\u003C...>` задаёт, в чьём кабинете отображается страница задач — подставьте ID нужного сотрудника, например текущего. `\u003Cportal>` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"289\",\n      \"title\": \"Подготовить отчёт за квартал\",\n      \"status\": \"2\",\n      \"priority\": \"1\",\n      \"responsibleId\": \"79\",\n      \"createdBy\": \"99\",\n      \"createdDate\": \"2026-05-12T09:11:18+03:00\",\n      \"deadline\": \"2026-05-19T18:00:00+03:00\",\n      \"groupId\": \"0\",\n      \"accomplices\": [],\n      \"auditors\": [],\n      \"creator\": {\n        \"id\": \"99\",\n        \"name\": \"Анна Соколова\",\n        \"link\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F99\u002F\"\n      },\n      \"responsible\": {\n        \"id\": \"79\",\n        \"name\": \"Дмитрий Орлов\",\n        \"link\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F79\u002F\"\n      }\n    }\n  ],\n  \"meta\": {\n    \"total\": 184,\n    \"hasMore\": true\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'tasks' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Передан некорректный или несуществующий ключ |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Когда переходить на `POST \u002Fv1\u002Ftasks\u002Fsearch`.** Если у запроса много условий фильтра или нужна выгрузка по большому диапазону дат, выбирайте `POST \u002Fv1\u002Ftasks\u002Fsearch` — параметры передаются в body, плюс доступно автоматическое разбиение запроса по временны́м окнам для выборок свыше 5000 записей. См. [Поиск задач](.\u002Fsearch.md).\n\n**Числовые значения как строки.** Поля-идентификаторы и числовые перечисления (`id`, `status`, `priority`, `responsibleId`, `createdBy`, `groupId`) приходят в виде строк. Для арифметики и сравнений приводите через `Number(value)`.\n\n## Смотрите также\n\n- [Получить задачу](.\u002Fget.md) — одна задача по ID\n- [Поиск задач](.\u002Fsearch.md) — POST с фильтрами в body и разбиением выборки по временны́м окнам\n- [Поля задачи](.\u002Ffields.md) — полный список полей и расшифровка `status`\u002F`priority`\n- [Агрегация задач](.\u002Faggregate.md) — подсчёт и группировка\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch-запросы](\u002Fdocs\u002Fbatch)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","\n## Получить задачу\n\n`GET \u002Fv1\u002Ftasks\u002F:id`\n\nВозвращает одну задачу со всеми полями. Дополнительно к полям списка приходят встроенные объекты постановщика и ответственного, чек-лист, разрешённые действия и расширенная информация о соисполнителях и наблюдателях.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | ID задачи |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F289\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F289\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F289', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log(data.title, '— статус:', data.status)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F289', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | object | Объект задачи. Базовые поля — см. [Поля задачи](.\u002Ffields.md). Дополнительные блоки описаны ниже |\n\n**Дополнительные блоки одиночного ответа:**\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `data.creator` | object | Постановщик: `{ id, name, link, icon, workPosition }` |\n| `data.responsible` | object | Ответственный: тот же формат, что и `creator` |\n| `data.accomplicesData` | object[] | Подробности по соисполнителям (тот же формат, что и `creator`) |\n| `data.auditorsData` | object[] | Подробности по наблюдателям (тот же формат, что и `creator`) |\n| `data.action` | object | Карта разрешённых действий (boolean): `complete`, `start`, `pause`, `delegate`, `remove`, `edit`, `defer`, `changeDeadline`, `checklistAddItems` и другие |\n| `data.checklist` | array | Пункты чек-листа (пустой массив, если чек-лист не заполнен) |\n| `data.checkListTree` | object | Дерево чек-листа с метаданными |\n| `data.newCommentsCount` | number | Количество непрочитанных комментариев |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"289\",\n    \"title\": \"Подготовить отчёт за квартал\",\n    \"description\": \"\",\n    \"status\": \"2\",\n    \"priority\": \"1\",\n    \"groupId\": \"0\",\n    \"responsibleId\": \"79\",\n    \"createdBy\": \"99\",\n    \"createdDate\": \"2026-05-12T09:11:18+03:00\",\n    \"changedDate\": \"2026-05-12T09:11:18+03:00\",\n    \"deadline\": \"2026-05-19T18:00:00+03:00\",\n    \"accomplices\": [],\n    \"auditors\": [],\n    \"checklist\": [],\n    \"creator\": {\n      \"id\": \"99\",\n      \"name\": \"Анна Соколова\",\n      \"link\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F99\u002F\",\n      \"icon\": \"https:\u002F\u002Fexample.bitrix24.ru\u002F...\u002Favatar.png\",\n      \"workPosition\": null\n    },\n    \"responsible\": {\n      \"id\": \"79\",\n      \"name\": \"Дмитрий Орлов\",\n      \"link\": \"\u002Fcompany\u002Fpersonal\u002Fuser\u002F79\u002F\",\n      \"icon\": \"\u002Fbitrix\u002Fimages\u002Ftasks\u002Fdefault_avatar.png\",\n      \"workPosition\": null\n    },\n    \"newCommentsCount\": 0,\n    \"action\": {\n      \"complete\": true,\n      \"start\": true,\n      \"delegate\": true,\n      \"edit\": true,\n      \"remove\": true,\n      \"defer\": true,\n      \"changeDeadline\": true\n    }\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n404 — задача не найдена:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"task 999999999 not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 404 | `ENTITY_NOT_FOUND` | Задача с таким ID не найдена |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Встроенные данные пользователей.** Поля `creator` и `responsible` приходят вложенным объектом с именем, ссылкой на профиль и аватаркой. Отдельный `GET \u002Fv1\u002Fusers\u002F:id` для отображения автора задачи не требуется.\n\n**Числовые значения как строки.** Большинство числовых полей (`id`, `status`, `priority`, `responsibleId`, `createdBy`, `groupId` и подобные) приходят строками. Для арифметики и сравнений приводите через `Number(value)`. Исключения: `newCommentsCount` приходит **числом** (и в списке, и в карточке); `commentsCount`\u002F`serviceCommentsCount` приходят либо `null`, либо строкой (`\"0\"`\u002F`\"N\"`) — числом не бывают. `chatId` непоследователен: в списке строка (`\"255\"`), в карточке число (`255`) — приводите через `Number()`.\n\n## Смотрите также\n\n- [Список задач](.\u002Flist.md) — поиск задачи перед чтением\n- [Поля задачи](.\u002Ffields.md) — полный список полей и расшифровка значений `status`\u002F`priority`\n- [Обновить задачу](.\u002Fupdate.md) — изменить состояние или сроки\n- [Удалить задачу](.\u002Fdelete.md) — снять задачу\n- [Комментарии задачи](\u002Fdocs\u002Fentities\u002Ftask-comments) — обсуждение\n- [Учёт времени](.\u002Ftime.md) — записи о трудозатратах\n- [Чек-лист задачи](.\u002Fchecklist.md) — пункты чек-листа (add\u002Fupdate\u002Fcomplete)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) — rate limits\n","\n## Обновить задачу\n\n`PATCH \u002Fv1\u002Ftasks\u002F:id`\n\nОбновляет поля существующей задачи. Передавайте только изменяемые поля. Полный список — [Поля задачи](.\u002Ffields.md).\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | ID задачи |\n\n## Поля запроса (body)\n\nПередавайте только изменяемые поля — поведение PATCH, остальные значения не затрагиваются.\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `title` | string | Название |\n| `description` | string | Описание задачи (поддерживает BB-код) |\n| `responsibleId` | number | Новый ответственный. Список сотрудников: `GET \u002Fv1\u002Fusers` |\n| `status` | number | Статус задачи. Полный список значений: `GET \u002Fv1\u002Ftasks\u002Ffields` → `fields.status.enum` |\n| `priority` | number | Приоритет: `0` — низкий, `1` — обычный, `2` — высокий |\n| `deadline` | datetime | Крайний срок (ISO 8601) |\n| `startDatePlan` | datetime | Плановая дата начала |\n| `endDatePlan` | datetime | Плановая дата окончания |\n| `timeEstimate` | number | Оценка трудозатрат в секундах |\n| `groupId` | number | Рабочая группа. Список: `GET \u002Fv1\u002Fworkgroups` |\n| `parentId` | number | Родительская задача. Список: `GET \u002Fv1\u002Ftasks` |\n| `accomplices` | number[] | Соисполнители. Список сотрудников: `GET \u002Fv1\u002Fusers` |\n| `auditors` | number[] | Наблюдатели. Список сотрудников: `GET \u002Fv1\u002Fusers` |\n| `tags` | string[] | Метки задачи |\n\nПоля `id`, `dateStart`, `createdDate`, `changedDate`, `closedDate`, `activityDate` — read-only, в body не передаются. Поле `createdBy` (постановщик) задаётся только при создании ([`POST \u002Fv1\u002Ftasks`](.\u002Fcreate.md)) — в PATCH отклоняется. Попытка → `400 READONLY_FIELD`.\n\n## Часто обновляемые поля\n\n| Поле | Когда используется |\n|------|-------------------|\n| `status` | Закрытие (`5`), возврат в работу (`3`), отказ (`7`). Расшифровка: `GET \u002Fv1\u002Ftasks\u002Ffields` → `fields.status.enum` |\n| `responsibleId` | Передача задачи другому сотруднику. Источник: `GET \u002Fv1\u002Fusers` |\n| `deadline` | Перенос срока (ISO 8601 со смещением часового пояса портала) |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F3871\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"status\": 5,\n    \"priority\": 2\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F3871\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"status\": 5,\n    \"priority\": 2\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F3871', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    status: 5,\n    priority: 2,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F3871', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    status: 5,\n    priority: 2,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | object | Обновлённый объект задачи со всеми полями — см. [Поля задачи](.\u002Ffields.md) |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"3871\",\n    \"title\": \"Подготовить отчёт за квартал\",\n    \"status\": \"5\",\n    \"priority\": \"2\",\n    \"responsibleId\": \"1\",\n    \"createdBy\": \"1\",\n    \"createdDate\": \"2026-05-12T11:46:12+03:00\",\n    \"changedDate\": \"2026-05-12T13:02:48+03:00\",\n    \"closedDate\": \"2026-05-12T13:02:48+03:00\",\n    \"deadline\": \"2026-05-19T18:00:00+03:00\",\n    \"accomplices\": [],\n    \"auditors\": []\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n400 — попытка изменить read-only поле:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"READONLY_FIELD\",\n    \"message\": \"Field 'createdDate' is read-only and cannot be set\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Битрикс24 отклонил обновление — например, задача с таким ID недоступна или не существует, либо переданное значение отклонено порталом |\n| 404 | `ENTITY_NOT_FOUND` | Связанная сущность не найдена — например, `responsibleId` указывает на несуществующего сотрудника |\n| 400 | `READONLY_FIELD` | Попытка обновить поле, доступное только на чтение (`id`, `dateStart`, `createdDate`, `changedDate`, `closedDate`, `activityDate`), или `createdBy` (задаётся только при создании) |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Закрытие задачи.** Чтобы пометить задачу выполненной, отправьте `status: 5`. После этого автоматически заполняется `closedDate` — это поле read-only и обновляется только при переводе в статус `5` (завершена) или `6` (отложена).\n\n## Смотрите также\n\n- [Получить задачу](.\u002Fget.md) — текущее состояние перед изменением\n- [Поля задачи](.\u002Ffields.md) — какие поля можно изменять, какие — read-only\n- [Удалить задачу](.\u002Fdelete.md) — полное удаление\n- [Список задач](.\u002Flist.md) — найти задачу перед изменением\n- [Batch-запросы](\u002Fdocs\u002Fbatch) — массовое обновление\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) — rate limits\n","\n## Удалить задачу\n\n`DELETE \u002Fv1\u002Ftasks\u002F:id`\n\nУдаляет задачу. Восстановить удалённую задачу через API нельзя — создавайте новую при необходимости. Вместе с задачей становятся недоступными её комментарии и записи учёта времени.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | ID задачи |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F3871\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F3871\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F3871', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Задача удалена')\n}\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002F3871', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Удалено')\n}\n```\n\n## Ответ\n\nПри успешном удалении возвращается HTTP-статус `204 No Content` с пустым телом — признак успеха проверяется по статусу.\n\n## Пример ответа\n\n```\nHTTP\u002F1.1 204 No Content\n```\n\n## Пример ответа при ошибке\n\n404 — задача не найдена (или уже удалена):\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"task 999999999 not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 404 | `ENTITY_NOT_FOUND` | Задача с таким ID не найдена (в том числе если она уже была удалена) |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Каскадное удаление вложенных ресурсов.** После удаления задачи становятся недоступными её комментарии и записи учёта времени — отдельный `DELETE` для каждого из них не нужен. Попытка обратиться к ним по прежнему ID вернёт `422 BITRIX_ERROR` с сообщением `ITEM_NOT_FOUND_OR_NOT_ACCESSIBLE`.\n\n## Смотрите также\n\n- [Список задач](.\u002Flist.md) — найти задачу перед удалением\n- [Получить задачу](.\u002Fget.md) — проверить состояние перед удалением\n- [Обновить задачу](.\u002Fupdate.md) — альтернатива: перевести в статус `6` (отложена), если задача может понадобиться позже\n- [Batch-запросы](\u002Fdocs\u002Fbatch) — массовое удаление\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) — rate limits\n","\n## Поиск задач\n\n`POST \u002Fv1\u002Ftasks\u002Fsearch`\n\nПоиск задач с фильтрами и сортировкой. Аналог `GET \u002Fv1\u002Ftasks`, но параметры передаются в теле запроса — подходит для длинных и сложных фильтров. Дополнительно поддерживает автоматическое разбиение запроса по временны́м окнам для выборок свыше 5000 записей.\n\n## Поля запроса (body)\n\n| Параметр | Тип | По умолч. | Описание |\n|----------|-----|-----------|---------|\n| `filter` | object | — | Фильтрация по полям `GET \u002Fv1\u002Ftasks\u002Ffields`.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering). Пример: `{\"status\": 2, \"responsibleId\": 1}` |\n| `select` | string[] | — | Выборка полей: `[\"id\", \"title\", \"status\", \"responsibleId\"]` |\n| `order` | object | `id desc` | Сортировка: `{ \"createdDate\": \"desc\" }` |\n| `limit` | number | `50` | Количество записей (до 5000) |\n| `offset` | number | `0` | Пропустить N записей |\n| `autoWindow` | boolean | `false` | Разбить запрос по временны́м окнам — обход лимита Битрикс24 в 5000 записей на один вызов |\n| `windowFrom` | datetime | — | Начало диапазона для разбиения по временны́м окнам (ISO 8601) |\n| `windowTo` | datetime | — | Конец диапазона для разбиения по временны́м окнам (ISO 8601) |\n\n> ⚠ **`status` vs `realStatus`.** `filter.status` в Bitrix24 — виртуальный (мета-)фильтр (`−1` просрочена, `−2` не просмотрена, `−3` почти просрочена), а не число из поля `status` ответа: `{\"filter\": {\"status\": 2}}` не вернёт задачи со статусом `2`. Для фильтра\u002Fсортировки по фактическому статусу используйте `realStatus`: `{\"filter\": {\"realStatus\": 2}}`, `{\"sort\": {\"realStatus\": \"asc\"}}`.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"status\": 2, \"responsibleId\": 1 },\n    \"select\": [\"id\", \"title\", \"status\", \"deadline\"],\n    \"order\": { \"id\": \"desc\" },\n    \"limit\": 50\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"status\": 2, \"responsibleId\": 1 },\n    \"select\": [\"id\", \"title\", \"status\", \"deadline\"],\n    \"order\": { \"id\": \"desc\" },\n    \"limit\": 50\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { status: 2, responsibleId: 1 },\n    select: ['id', 'title', 'status', 'deadline'],\n    order: { id: 'desc' },\n    limit: 50,\n  }),\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`Найдено ${data.length} из ${meta.total} задач`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { status: 2, responsibleId: 1 },\n    select: ['id', 'title', 'status', 'deadline'],\n    order: { id: 'desc' },\n    limit: 50,\n  }),\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив задач (все поля — см. [Поля задачи](.\u002Ffields.md)) |\n| `meta.total` | number | Общее количество записей, соответствующих фильтру |\n| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |\n| `meta.durationMs` | number | Длительность выполнения запроса в миллисекундах |\n| `meta.autoWindowed` | boolean | `true`, если запрос был разбит по временны́м окнам |\n| `meta.windowCount` | number | Количество окон (только при `autoWindowed: true`) |\n| `meta.batchWaves` | number | Сколько волн параллельных запросов потребовалось (только при `autoWindowed: true`) |\n\nURL карточки любой задачи из массива `data` строится из её `id` и ID сотрудника:\n\n```\nhttps:\u002F\u002F\u003Cportal>.bitrix24.ru\u002Fcompany\u002Fpersonal\u002Fuser\u002F\u003CresponsibleId>\u002Ftasks\u002Ftask\u002Fview\u002F\u003Cid>\u002F\n```\n\n`\u003CresponsibleId>` — ID ответственного (поле `responsibleId` каждого элемента): задача откроется в его личном кабинете. Сегмент `user\u002F\u003C...>` задаёт, в чьём кабинете отображается страница задач — подставьте ID нужного сотрудника, например текущего. `\u003Cportal>` — домен портала. Доступ ограничен правами сотрудника в Битрикс24.\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": \"289\",\n      \"title\": \"Подготовить отчёт за квартал\",\n      \"status\": \"2\",\n      \"deadline\": \"2026-05-19T18:00:00+03:00\"\n    },\n    {\n      \"id\": \"311\",\n      \"title\": \"Свериться с бухгалтерией\",\n      \"status\": \"2\",\n      \"deadline\": \"2026-05-15T17:00:00+03:00\"\n    }\n  ],\n  \"meta\": {\n    \"total\": 182,\n    \"hasMore\": true,\n    \"durationMs\": 1226\n  }\n}\n```\n\nС `autoWindow: true` дополнительно появятся `autoWindowed`, `windowCount`, `batchWaves`:\n\n```json\n{\n  \"success\": true,\n  \"data\": [ \u002F* ... *\u002F ],\n  \"meta\": {\n    \"total\": 50,\n    \"hasMore\": false,\n    \"autoWindowed\": true,\n    \"windowCount\": 157,\n    \"batchWaves\": 4,\n    \"durationMs\": 4357\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'tasks' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n| — | `WINDOWED_SEARCH_FAILED` | Ретайрнут: при полном отказе окон возвращается реальный код Битрикс24 — `UNKNOWN_FILTER_FIELD` \u002F `BITRIX_ACCESS_DENIED` \u002F `RATE_LIMITED` \u002F `BITRIX_UNAVAILABLE` |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Когда выбирать search вместо list.** `GET \u002Fv1\u002Ftasks` подходит для коротких фильтров в URL. `POST \u002Fv1\u002Ftasks\u002Fsearch` применяется, когда условий много — вложенные объекты, массивы, диапазоны дат: параметры в теле читаются и собираются проще, чем длинная query-строка.\n\n**Разбиение по временны́м окнам.** Если задач больше 5000, передайте `autoWindow: true` вместе с диапазоном `windowFrom`\u002F`windowTo`. Запрос автоматически разбивается на окна, выполняется параллельными волнами, и в `meta` приходит число окон (`windowCount`) и волн (`batchWaves`). Этим обходится лимит Битрикс24 в 5000 записей на один вызов.\n\n**Числовые значения как строки.** Поля-идентификаторы и числовые перечисления (`id`, `status`, `priority`, `responsibleId`, `createdBy`, `groupId`) приходят строками. Для арифметики и сравнений приводите через `Number(value)`.\n\n## Смотрите также\n\n- [Список задач](.\u002Flist.md) — GET-вариант с query-параметрами\n- [Поля задачи](.\u002Ffields.md) — какие поля принимает `filter` и `select`\n- [Агрегация задач](.\u002Faggregate.md) — подсчёт и группировка\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch-запросы](\u002Fdocs\u002Fbatch) — объединение нескольких запросов\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) — rate limits\n","\n## Поля задачи\n\n`GET \u002Fv1\u002Ftasks\u002Ffields`\n\nВозвращает схему полей задачи: типы, флаги «только чтение», статические перечисления значений для `status` и `priority`.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Полей:', Object.keys(data.fields).length)\nconsole.log('Значения status:', data.fields.status.enum)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\nНиже описаны основные поля задачи в camelCase. Помимо них в ответе приходят дополнительные поля в формате UPPER_SNAKE_CASE, у которых нет camelCase-версии — например `STAGE_ID`, `SPRINT_ID`, `BACKLOG_ID`, `FLOW_ID`, `MARK`, `CHECKLIST`. Полный набор полей виден в живом ответе `GET \u002Fv1\u002Ftasks\u002Ffields`.\n\n| Поле | Битрикс24 | Тип | RO | Описание |\n|------|----------|-----|:--:|---------|\n| `id` | `ID` | number | да | Идентификатор задачи |\n| `title` | `TITLE` | string | | Название задачи |\n| `description` | `DESCRIPTION` | string | | Описание (поддерживает BB-код) |\n| `responsibleId` | `RESPONSIBLE_ID` | number | | Ответственный. Список: `GET \u002Fv1\u002Fusers` |\n| `createdBy` | `CREATED_BY` | number | | Постановщик. Задаётся только при создании (по умолчанию — пользователь ключа); в PATCH отклоняется. Список: `GET \u002Fv1\u002Fusers` |\n| `status` | `STATUS` | number | | Статус задачи. Допустимые значения в `fields.status.enum`. ⚠ **`filter[status]` — виртуальный (мета-)фильтр**: Bitrix24 понимает здесь `−1` (просрочена), `−2` (не просмотрена), `−3` (почти просрочена), а не число из поля `status` ответа — поэтому `filter[status]=2` НЕ вернёт все задачи со статусом `2`. Для фильтра по фактическому статусу используйте `realStatus` |\n| `realStatus` | `REAL_STATUS` | number | да | Реальный (фактически сохранённый) статус задачи — совпадает со значением поля `status` в ответе. Только для `filter`\u002F`sort`: `?filter[realStatus]=2`, `?sort=realStatus` — в отличие от виртуального `filter[status]`, фильтрует по хранимому статусу. Значения те же, что у `status` (см. `fields.status.enum`). В теле ответа отдельно не возвращается (реальный статус уже есть в `status`); менять статус — через `status` |\n| `priority` | `PRIORITY` | number | | Приоритет задачи. Допустимые значения в `fields.priority.enum` |\n| `groupId` | `GROUP_ID` | number | | Рабочая группа. Список: `GET \u002Fv1\u002Fworkgroups` |\n| `parentId` | `PARENT_ID` | number | | Родительская задача. Список: `GET \u002Fv1\u002Ftasks` |\n| `deadline` | `DEADLINE` | datetime | | Крайний срок (ISO 8601) |\n| `dateStart` | `DATE_START` | datetime | да | Фактическая дата начала работы над задачей. Фильтруется: `?filter[>=dateStart]=2026-05-01T00:00:00` |\n| `startDatePlan` | `START_DATE_PLAN` | datetime | | Плановая дата начала |\n| `endDatePlan` | `END_DATE_PLAN` | datetime | | Плановая дата окончания |\n| `timeEstimate` | `TIME_ESTIMATE` | number | | Оценка трудозатрат в секундах |\n| `tags` | `TAGS` | object \\| array | | Метки задачи. У задачи С метками — объект-словарь `{ \"\u003Cid>\": { \"id\": \u003Cid>, \"title\": \"\u003Cметка>\" } }`; у задачи БЕЗ меток приходит пустой массив `[]` (а не пустой объект) — тип зависит от данных, проверяйте `Array.isArray()` перед обращением по ключу. Фильтр по одной метке: `?filter[tags]=метка` (транслируется в B24 `TAG`) |\n| `accomplices` | `ACCOMPLICES` | array | | Соисполнители. Список: `GET \u002Fv1\u002Fusers`. Фильтр по одному пользователю: `?filter[accomplices]=25` (транслируется в B24 `ACCOMPLICE`) |\n| `auditors` | `AUDITORS` | array | | Наблюдатели. Список: `GET \u002Fv1\u002Fusers`. Фильтр по одному пользователю: `?filter[auditors]=25` (транслируется в B24 `AUDITOR`) |\n| `closedDate` | `CLOSED_DATE` | datetime | да | Дата закрытия (заполняется при переводе в статус `5` или `6`) |\n| `createdDate` | `CREATED_DATE` | datetime | да | Дата создания |\n| `changedDate` | `CHANGED_DATE` | datetime | да | Дата последнего изменения |\n| `activityDate` | `ACTIVITY_DATE` | datetime | да | Дата последней активности (учитывает комментарии, в отличие от `changedDate`). Возвращается всегда и выбирается через `?select=activityDate`. ⚠ Не фильтруется на стороне Bitrix24 — для фильтра используйте `changedDate` |\n\n**Расшифровка `status`** — поле `fields.status.enum`:\n\n| Значение | Метка | Описание |\n|----------|-------|----------|\n| `1` | New | Начальное состояние. Новые задачи создаются со статусом `2`; `1` встречается у задач, импортированных из внешних систем или мигрированных со старых версий портала |\n| `2` | Pending | Ждёт выполнения. Статус по умолчанию для новых задач |\n| `3` | In Progress | Выполняется |\n| `4` | Awaiting Control | Ожидает контроля. Исполнитель пометил задачу как сделанную, постановщик должен подтвердить |\n| `5` | Completed | Завершена |\n| `6` | Deferred | Отложена |\n| `7` | Declined | Отклонена |\n\n**Расшифровка `priority`** — поле `fields.priority.enum`:\n\n| Значение | Метка |\n|----------|-------|\n| `0` | Низкий |\n| `1` | Обычный |\n| `2` | Высокий |\n\n**Пользовательские поля (`UF_*`)** принимаются при создании\u002Fобновлении и в фильтрах в обоих написаниях — `ufCrmTask` и `UF_CRM_TASK` (camelCase конвертируется автоматически). ⚠ `UF_CRM_TASK` (привязка к CRM) принимает **массив** идентификаторов привязок — `[\"D_123\"]` (сделка), `[\"C_45\"]` (контакт), `[\"CO_7\"]` (компания), `[\"L_9\"]` (лид). Строка вместо массива (`\"D_123\"`) молча игнорируется Bitrix24 — значение не сохранится (проверено на живом портале).\n\n**Нульность.** Многие необязательные поля приходят `null`, когда не заполнены: `parentId`, `dateStart`, `startDatePlan`, `endDatePlan`, `deadline`, `closedBy`, `closedDate`, `mark`, `sprintId`, `backlogId`, `durationFact`, `durationPlan`, `timeSpentInLogs`, `sorting`, `flowId`, `xmlId`, `ufCrmTask`, `ufMailMessage` и др. Типобезопасным клиентам (TS) объявляйте такие поля как `T | null`. Документированные пустые случаи `accomplices`\u002F`auditors`\u002F`checklist` приходят как `[]`; **`tags` — исключение**: без меток приходит `[]`, с метками — объект (см. выше).\n\n## Пример ответа\n\nПоказаны основные поля. Полный ответ дополнительно содержит UPPER_SNAKE-эквиваленты и системные служебные поля.\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": {\n      \"id\": { \"type\": \"number\", \"readonly\": true },\n      \"title\": { \"type\": \"string\", \"readonly\": false },\n      \"description\": { \"type\": \"string\", \"readonly\": false },\n      \"responsibleId\": { \"type\": \"number\", \"readonly\": false },\n      \"createdBy\": { \"type\": \"number\", \"readonly\": false, \"createOnly\": true },\n      \"status\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"enum\": [\n          { \"value\": 1, \"label\": \"New\", \"labelRu\": \"Новая\" },\n          { \"value\": 2, \"label\": \"Pending\", \"labelRu\": \"Ждёт выполнения\" },\n          { \"value\": 3, \"label\": \"In Progress\", \"labelRu\": \"Выполняется\" },\n          { \"value\": 4, \"label\": \"Awaiting Control\", \"labelRu\": \"Ожидает контроля\" },\n          { \"value\": 5, \"label\": \"Completed\", \"labelRu\": \"Завершена\" },\n          { \"value\": 6, \"label\": \"Deferred\", \"labelRu\": \"Отложена\" },\n          { \"value\": 7, \"label\": \"Declined\", \"labelRu\": \"Отклонена\" }\n        ]\n      },\n      \"priority\": {\n        \"type\": \"number\",\n        \"readonly\": false,\n        \"enum\": [\n          { \"value\": 0, \"label\": \"Low\", \"labelRu\": \"Низкий\" },\n          { \"value\": 1, \"label\": \"Normal\", \"labelRu\": \"Обычный\" },\n          { \"value\": 2, \"label\": \"High\", \"labelRu\": \"Высокий\" }\n        ]\n      },\n      \"deadline\": { \"type\": \"datetime\", \"readonly\": false },\n      \"createdDate\": { \"type\": \"datetime\", \"readonly\": true },\n      \"changedDate\": { \"type\": \"datetime\", \"readonly\": true }\n    }\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'tasks' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Создать задачу](.\u002Fcreate.md) — какие поля передавать\n- [Обновить задачу](.\u002Fupdate.md) — какие поля можно изменять\n- [Список задач](.\u002Flist.md) — фильтрация и сортировка по полям\n- [Поиск задач](.\u002Fsearch.md) — те же поля в POST-варианте\n- [Агрегация задач](.\u002Faggregate.md) — группировка по полям\n- [Entity API](\u002Fdocs\u002Fentity-api) — `select` для выборки нужных полей\n","\n## Агрегация задач\n\n`POST \u002Fv1\u002Ftasks\u002Faggregate`\n\nПодсчёт количества задач с фильтрацией и группировкой. Числовые функции работают по числовым полям задачи и пользовательским полям подходящих типов.\n\n**Стандартные поля:**\n\n- `status` — статус задачи (для `groupBy`; для числовых функций смысла нет — это категориальный код). `groupBy: \"status\"` группирует по **фактическому сохранённому** статусу — это значение поля `status` в ответе, а не виртуальная мета-ось фильтра `filter[status]`\n- `priority` — приоритет (для `groupBy`)\n- `responsibleId` — ответственный (для `groupBy`; идентификатор)\n- `groupId` — рабочая группа (для `groupBy`; идентификатор)\n\nВсе стандартные `aggregatable` поля — идентификаторы или категориальные коды, поэтому по ним работают `count` и `groupBy`. Для числовых функций (`sum`\u002F`avg`\u002F`min`\u002F`max`) подходящий встроенный кандидат — `timeEstimate` (оценка трудозатрат в секундах); либо пользовательские поля.\n\n> ⚠ **Ограничение выборки по статусу.** Чтобы посчитать только открытые\u002Fзавершённые задачи, добавьте в `filter` поле `realStatus` (фактический статус): `{\"filter\": {\"realStatus\": 2}}`. `filter[status]` здесь тоже виртуальный (мета-ось `−1\u002F−2\u002F−3`), а не число из ответа. Само `realStatus` — только для `filter`\u002F`sort`, в `groupBy` его нет: для разбивки по статусу используйте `groupBy: \"status\"` (он группирует по фактическому статусу, см. выше).\n\n**Пользовательские поля (UF):** UF-поля типов `integer`, `double`, `money` принимаются в числовых функциях; UF любого типа — в `groupBy`. Полный список UF-полей конкретного портала приходит в тексте ошибки `INVALID_PARAMS`, если передать несуществующее имя.\n\n## Поля запроса (body)\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `aggregate` | array | нет | Массив агрегаций. Каждый элемент: `{ \"field\": \"timeEstimate\", \"function\": \"sum\" }`. Функции: `count`, `sum`, `avg`, `min`, `max`. Для `count` поле — `\"*\"`. Без параметра — только count |\n| `filter` | object | нет | Фильтрация по полям `GET \u002Fv1\u002Ftasks\u002Ffields`.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering). Пример: `{\"responsibleId\": 1}` |\n| `groupBy` | string \\| string[] | нет | Поле или массив полей для группировки (максимум 5). Принимает UF-поля любого типа |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"aggregate\": [\n      { \"field\": \"timeEstimate\", \"function\": \"sum\" }\n    ],\n    \"groupBy\": \"status\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Faggregate\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"aggregate\": [\n      { \"field\": \"timeEstimate\", \"function\": \"sum\" }\n    ],\n    \"groupBy\": \"status\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    aggregate: [{ field: 'timeEstimate', function: 'sum' }],\n    groupBy: 'status',\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('Всего задач:', data.count)\nconsole.log('По статусам:', data.groups)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Ftasks\u002Faggregate', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    aggregate: [{ field: 'timeEstimate', function: 'sum' }],\n    groupBy: 'status',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n> Для группировки по нескольким полям передайте массив: `\"groupBy\": [\"status\", \"responsibleId\"]` (максимум 5).\n\n## Другие сценарии\n\nПодсчёт записей — `count` с полем `\"*\"`, самый быстрый запрос без выгрузки записей. Без массива `aggregate` результат тот же:\n\n```json\n{ \"aggregate\": [{ \"field\": \"*\", \"function\": \"count\" }] }\n```\n\nСколько задач у каждого ответственного:\n\n```json\n{ \"groupBy\": \"responsibleId\" }\n```\n\nСумма по UF-полю числового типа в разрезе приоритета:\n\n```json\n{\n  \"aggregate\": [{ \"field\": \"UF_CRM_TASK_BUDGET\", \"function\": \"sum\" }],\n  \"groupBy\": \"priority\"\n}\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data.count` | number | Количество записей, соответствующих фильтру |\n| `data.aggregates` | object | Результаты агрегаций. Без `aggregate` — пустой объект |\n| `data.groups` | array | Группы (только при `groupBy`). Каждый элемент: поля группировки + `count` + `aggregates` |\n| `data.meta.totalRecords` | number | Общее количество записей |\n| `data.meta.recordsProcessed` | number | Сколько записей реально обработано |\n| `data.meta.truncated` | boolean | `true`, если попали в ограничение 5000 — агрегация и группы построены по первым 5000 записям |\n| `data.meta.groupTotal` | number | Общее количество групп (только при `groupBy`) |\n| `data.meta.groupsTruncated` | boolean | Был ли список групп ограничен `groupLimit` |\n\n## Пример ответа\n\nОтвет на основной запрос (`aggregate: [{field: \"timeEstimate\", function: \"sum\"}]` + `groupBy: \"status\"`):\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"count\": 599,\n    \"aggregates\": {\n      \"timeEstimate\": { \"sum\": 54000 }\n    },\n    \"groups\": [\n      { \"status\": \"2\", \"count\": 247, \"aggregates\": { \"timeEstimate\": { \"sum\": 18000 } } },\n      { \"status\": \"5\", \"count\": 341, \"aggregates\": { \"timeEstimate\": { \"sum\": 32400 } } },\n      { \"status\": \"3\", \"count\": 7,   \"aggregates\": { \"timeEstimate\": { \"sum\": 2400 } } },\n      { \"status\": \"4\", \"count\": 4,   \"aggregates\": { \"timeEstimate\": { \"sum\": 1200 } } }\n    ],\n    \"meta\": {\n      \"totalRecords\": 599,\n      \"recordsProcessed\": 599,\n      \"truncated\": false,\n      \"groupTotal\": 4,\n      \"groupsTruncated\": false\n    }\n  }\n}\n```\n\nБез `groupBy` поле `data.groups` в ответе отсутствует.\n\n## Пример ответа при ошибке\n\n400 — несуществующее поле:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Unknown field 'noSuchField'. Available: status, priority, responsibleId, groupId, UF_CRM_TASK_BUDGET, …\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | Неизвестная функция или несуществующее поле — сообщение содержит список допустимых (стандартных + UF) |\n| 400 | `INVALID_PARAMS` | UF-поле нечислового типа (`string`, `enumeration`, `date`) в `sum`\u002F`avg`\u002F`min`\u002F`max` — сообщение называет тип |\n| 400 | `INVALID_PARAMS` | `groupBy` по стандартному полю вне списка `aggregatable` |\n| 400 | `INVALID_PARAMS` | Больше 5 полей в `groupBy` |\n| 400 | `INVALID_PARAMS` | Зарезервированные ключевые слова в `groupBy`: `count`, `aggregates`, `meta`, `groups` |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `tasks` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**`count` против числовых функций.** `count` считается одним вызовом и работает на любом объёме. `sum`\u002F`avg`\u002F`min`\u002F`max` подгружают записи постранично (максимум 5000) и считают на стороне API. При выборках свыше 5000 — `meta.truncated: true`, агрегация по первым 5000. Для точных счётчиков на больших выборках используйте `count` или сужайте фильтр.\n\n## Смотрите также\n\n- [Список задач](.\u002Flist.md) — `meta.total` показывает точное число записей под фильтр\n- [Поиск задач](.\u002Fsearch.md) — POST-запрос с фильтрами в body\n- [Поля задачи](.\u002Ffields.md) — список стандартных полей и расшифровка `status`\u002F`priority`\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) — rate limits\n"]