Поиск задач

POST /v1/tasks/search

Поиск задач с фильтрами и сортировкой. Аналог GET /v1/tasks, но параметры передаются в теле запроса — подходит для длинных и сложных фильтров. Дополнительно поддерживает автоматическое разбиение запроса по временны́м окнам для выборок свыше 5000 записей.

Поля запроса (body)

Параметр Тип По умолч. Описание
filter object — Фильтрация по полям GET /v1/tasks/fields.
Синтаксис фильтрации. Пример: {"status": 2, "responsibleId": 1}
select string[] — Выборка полей: ["id", "title", "status", "responsibleId"]
order object id desc Сортировка: { "createdDate": "desc" }
limit number 50 Количество записей (до 5000)
offset number 0 Пропустить N записей
autoWindow boolean false Разбить запрос по временны́м окнам — обход лимита Битрикс24 в 5000 записей на один вызов
windowFrom datetime — Начало диапазона для разбиения по временны́м окнам (ISO 8601)
windowTo datetime — Конец диапазона для разбиения по временны́м окнам (ISO 8601)

⚠ status vs realStatus. filter.status в Bitrix24 — виртуальный (мета-)фильтр (−1 просрочена, −2 не просмотрена, −3 почти просрочена), а не число из поля status ответа: {"filter": {"status": 2}} не вернёт задачи со статусом 2. Для фильтра/сортировки по фактическому статусу используйте realStatus: {"filter": {"realStatus": 2}}, {"sort": {"realStatus": "asc"}}.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/tasks/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "status": 2, "responsibleId": 1 },
    "select": ["id", "title", "status", "deadline"],
    "order": { "id": "desc" },
    "limit": 50
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/tasks/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "status": 2, "responsibleId": 1 },
    "select": ["id", "title", "status", "deadline"],
    "order": { "id": "desc" },
    "limit": 50
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { status: 2, responsibleId: 1 },
    select: ['id', 'title', 'status', 'deadline'],
    order: { id: 'desc' },
    limit: 50,
  }),
})

const { success, data, meta } = await res.json()
console.log(`Найдено ${data.length} из ${meta.total} задач`)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/tasks/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { status: 2, responsibleId: 1 },
    select: ['id', 'title', 'status', 'deadline'],
    order: { id: 'desc' },
    limit: 50,
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив задач (все поля — см. Поля задачи)
meta.total number Общее количество записей, соответствующих фильтру
meta.hasMore boolean Есть ли ещё записи за пределами limit
meta.durationMs number Длительность выполнения запроса в миллисекундах
meta.autoWindowed boolean true, если запрос был разбит по временны́м окнам
meta.windowCount number Количество окон (только при autoWindowed: true)
meta.batchWaves number Сколько волн параллельных запросов потребовалось (только при autoWindowed: true)

URL карточки любой задачи из массива data строится из её id и ID сотрудника:

https://<portal>.bitrix24.ru/company/personal/user/<responsibleId>/tasks/task/view/<id>/

<responsibleId> — ID ответственного (поле responsibleId каждого элемента): задача откроется в его личном кабинете. Сегмент user/<...> задаёт, в чьём кабинете отображается страница задач — подставьте ID нужного сотрудника, например текущего. <portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24.

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": "289",
      "title": "Подготовить отчёт за квартал",
      "status": "2",
      "deadline": "2026-05-19T18:00:00+03:00"
    },
    {
      "id": "311",
      "title": "Свериться с бухгалтерией",
      "status": "2",
      "deadline": "2026-05-15T17:00:00+03:00"
    }
  ],
  "meta": {
    "total": 182,
    "hasMore": true,
    "durationMs": 1226
  }
}

С autoWindow: true дополнительно появятся autoWindowed, windowCount, batchWaves:

JSON 
{
  "success": true,
  "data": [ /* ... */ ],
  "meta": {
    "total": 50,
    "hasMore": false,
    "autoWindowed": true,
    "windowCount": 157,
    "batchWaves": 4,
    "durationMs": 4357
  }
}

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

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'tasks' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа tasks
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
— WINDOWED_SEARCH_FAILED Ретайрнут: при полном отказе окон возвращается реальный код Битрикс24 — UNKNOWN_FILTER_FIELD / BITRIX_ACCESS_DENIED / RATE_LIMITED / BITRIX_UNAVAILABLE

Полный список общих ошибок API — Ошибки.

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

Когда выбирать search вместо list. GET /v1/tasks подходит для коротких фильтров в URL. POST /v1/tasks/search применяется, когда условий много — вложенные объекты, массивы, диапазоны дат: параметры в теле читаются и собираются проще, чем длинная query-строка.

Разбиение по временны́м окнам. Если задач больше 5000, передайте autoWindow: true вместе с диапазоном windowFrom/windowTo. Запрос автоматически разбивается на окна, выполняется параллельными волнами, и в meta приходит число окон (windowCount) и волн (batchWaves). Этим обходится лимит Битрикс24 в 5000 записей на один вызов.

Числовые значения как строки. Поля-идентификаторы и числовые перечисления (id, status, priority, responsibleId, createdBy, groupId) приходят строками. Для арифметики и сравнений приводите через Number(value).

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