Поиск задач

POST /v1/tasks/search

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

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

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

meta.total приходит не на каждый вызов. При limit не больше 50 и offset, равном нулю, подсчёт можно не заказывать: если страница пришла короче limit, meta.total всё равно придёт с точным числом (пустой результат даёт 0). На полной странице поля не будет. При limit больше 50 meta.total приходит — подсчёт платформа выполняет, только когда без него не обойтись, — и убрать его оттуда можно явным withTotal=false. При разбиении на окна (autoWindowed: true) подсчёт заказывается как раньше, а withTotal игнорируется. Проверяйте наличие поля в конкретном ответе, а листайте по meta.hasMore.

Примеры

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

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-приложение

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 — личный ключ

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-приложение

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()

Поля ответа

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

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

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

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

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

С фильтром по диапазону дат шире 14 дней в meta дополнительно приходят autoWindowed, windowCount и batchWaves:

{
  "success": true,
  "data": [ /* ... */ ],
  "meta": {
    "total": 179,
    "hasMore": true,
    "autoWindowed": true,
    "windowCount": 131,
    "batchWaves": 3,
    "durationMs": 1543
  }
}

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

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

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

Ошибки

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

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

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

Разбиение по временны́м окнам. Фильтр по диапазону дат шире 14 дней автоматически разбивается на недельные окна, которые выполняются параллельными волнами — так выборка обходит потолок в 5000 записей на один вызов. В meta тогда приходят autoWindowed: true, число окон windowCount и число волн batchWaves. Отключает разбиение параметр autoWindow: false. При активном разбиении offset больше нуля отклоняется с UNSTABLE_OFFSET_PAGINATION.

Типы значений соответствуют схеме. Поля, объявленные в схеме числами — id, status, priority, responsibleId, createdBy, groupId и подобные, — приходят числами. Признаки «да/нет» приходят значениями true и false. Приведение через Number(value) не требуется.

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

• Список задач
• Поля задачи
• Агрегация задач
• Синтаксис фильтрации
• Batch
• Лимиты и оптимизация