#Лимиты и оптимизация

Vibe API сам объединяет вызовы и пагинирует выборки на стороне сервера. Эта статья описывает встроенные механизмы и подсказывает, какой эндпоинт выбирать под задачу.

Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

#Авто-пагинация в `list`

Параметр limit в GET /v1/{entity} принимает значения до 5000. Если limit > 50, Вайбкод сам разбивает выборку на внутренние страницы по 50 записей и собирает их в один ответ:

GET /v1/deals?limit=500&filter[stageId]=NEW

Возвращается до 500 записей плюс мета-поля meta.total и meta.hasMore. Если под фильтр попадает больше 5000 записей, ответ обрезается, а в meta.truncated приходит true — для остатка нужно либо сузить фильтр, либо использовать POST /v1/{entity}/search.

#Пакетные вызовы по нескольким сущностям

POST /v1/batch объединяет до 50 операций над разными сущностями в один HTTP-запрос. Каждый вызов идентифицируется собственным id, ошибка одного не отменяет остальные.

Подходит для дашбордов и страниц-сводок, где одной загрузкой нужны данные из разных мест:

{
  "calls": [
    { "id": "deals", "entity": "deals", "action": "list", "params": { "filter": { "stageId": "NEW" }, "limit": 50 } },
    { "id": "tasks", "entity": "tasks", "action": "list", "params": { "filter": { "responsibleId": 1 }, "limit": 20 } },
    { "id": "user", "entity": "users", "action": "get", "entityId": 1 }
  ]
}

Полная спецификация — Пакетные вызовы.

#Пакетные операции по одной сущности

POST /v1/{entity}/batch массово создаёт, обновляет или удаляет до 500 записей одной сущности. Внутри Вайбкод разбивает запрос на пакеты по 50 элементов:

curl -X POST https://vibecode.bitrix24.tech/v1/deals/batch \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update",
    "items": [
      { "id": 575, "stageId": "WON" },
      { "id": 741, "stageId": "WON" }
    ]
  }'

Действия: create, update, delete, list, get, fields. Для delete передаётся массив ids, для остальных — items (CUD) или calls (read).

#Массовое сканирование с дозагрузкой связанных данных

Когда нужно прочитать тысячи записей одной сущности и подтянуть к ним связанные данные из других сущностей, поток выглядит так:

1. Выгрузить корневой список одним вызовом — Вайбкод сам пагинирует на сервере:

   Копировать

   GET /v1/deals?limit=5000&select=id,title,companyId,assignedById

2. Собрать id связанных сущностей и догрузить пакетами по 50 через POST /v1/batch:

   JSON Копировать

   {
     "calls": [
       { "id": "company-15", "entity": "companies", "action": "get", "entityId": 15 },
       { "id": "company-22", "entity": "companies", "action": "get", "entityId": 22 },
       { "id": "user-1",     "entity": "users",     "action": "get", "entityId": 1 }
     ]
   }

   Один HTTP-запрос — до 50 связанных записей; цикл повторяется для следующего пакета id.

В таком сценарии корневая выгрузка занимает один сетевой запрос (Вайбкод сам поднимает страницы по 50), а ассоциации догружаются в темпе один HTTP-запрос на 50 элементов вместо запроса на каждый элемент.

#Поиск с разбиением по датам

POST /v1/{entity}/search рассчитан на крупные выборки. Если в фильтре есть условие по дате с диапазоном больше 14 дней, Вайбкод автоматически делит запрос на окна по 7 дней и обрабатывает их параллельно:

{
  "filter": { "$gte": { "createdAt": "2026-01-01" }, "$lte": { "createdAt": "2026-04-30" } },
  "select": ["id", "title", "stageId"],
  "limit": 5000
}

В ответе появляются мета-поля:

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

#Агрегация вместо выборки записей

Когда нужны только счётчики, суммы, минимумы, максимумы или средние — POST /v1/{entity}/aggregate возвращает результат одним вызовом, без выгрузки самих записей:

{
  "aggregate": [
    { "field": "amount", "function": "sum" },
    { "field": "amount", "function": "avg" }
  ],
  "filter": { "stageId": "WON" },
  "groupBy": "assignedById"
}

Ответ содержит data.count, data.aggregates и (при наличии groupBy) массив data.groups с разбивкой по полю группировки. Без groupBy ответ ограничен одним объектом сводных значений. Для функции count Битрикс24 возвращает результат одним вызовом независимо от размера выборки; sum / avg / min / max подгружают записи постранично до 5000 штук — при большем объёме приходит meta.truncated: true.

#Очередь портала

У каждого портала Битрикс24 своя очередь к Vibe API: одновременно выполняются до двух запросов, остальные ждут места. Если запрос провисел в очереди дольше 30 секунд, возвращается 504 QUEUE_TIMEOUT с подсказкой userMessage и hint.

Что снижает нагрузку на очередь:

• Объединять разнородные обращения через POST /v1/batch — один HTTP-запрос вместо нескольких.
• Для массового CRUD по одной сущности — POST /v1/{entity}/batch (до 500 записей за запрос).
• Для широких выборок — GET /v1/{entity}?limit=... (Вайбкод пагинирует на стороне сервера) или POST /v1/{entity}/search (разбивка по датам).
• Когда нужны числа, а не записи — POST /v1/{entity}/aggregate.

#Загрузка сообщений из нескольких диалогов

POST /v1/chats/messages/bulk возвращает сообщения не более чем из 50 диалогов в одном ответе и принимает курсоры lastId / firstId и limit для каждого диалога:

{
  "dialogs": [
    { "dialogId": "chat253", "limit": 20 },
    { "dialogId": "chat741", "lastId": 9357, "limit": 50 }
  ]
}

Скоуп: im. Формат ответа — { results, errors, summary }, аналогично /v1/batch.

#Сводные лимиты

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

• Пакетные вызовы — полная спецификация POST /v1/batch
• Синтаксис фильтрации — три синтаксиса фильтра для list, search, aggregate
• Entity API — справочник сущностей и одиночных эндпоинтов
• Коды ошибок — общий справочник
• Быстрый старт — первый запрос за две минуты