Пагинация и параметр start

Списочные методы REST Битрикс24 (crm.deal.list, tasks.task.list, user.get и другие) всегда возвращают не более 50 записей за вызов. Чтобы получить остальные, используется постраничная навигация через параметр start и служебные поля ответа next и total.

Как устроена постраничность

Размер страницы в REST Битрикс24 фиксирован — 50 записей, изменить его нельзя. Навигация строится на смещении: параметр start указывает, с какого по счёту элемента начинать выборку. Значение всегда кратно 50.

• start=0 (по умолчанию) — первая страница, записи 1–50.
• start=50 — вторая страница, записи 51–100.
• start=100 — третья страница, и так далее.

Ответ содержит два ключевых служебных поля: total — общее число записей, удовлетворяющих фильтру, и next — значение start для следующего запроса. Если next в ответе отсутствует, страницы закончились.

Цикл постраничного обхода

Типовой алгоритм полной выборки — читать страницы, пока в ответе есть next:

1. Отправить запрос со start=0.
2. Обработать полученные до 50 записей.
3. Если в ответе есть next — подставить его значение в start и повторить.
4. Как только next исчез — обход завершён.

Пример запроса второй страницы: crm.deal.list?filter[STAGE_ID]=NEW&select[]=ID&select[]=TITLE&start=50.

Ускорение: start=-1 и отказ от подсчёта total

Подсчёт total — дорогая операция: портал выполняет отдельный COUNT по всей выборке. На больших таблицах это заметно замедляет каждый запрос. Если общее число вам не нужно, отключите подсчёт, передав start=-1.

При start=-1 поле total в ответе не рассчитывается, что ускоряет отклик. Этот приём — основа «быстрого» метода обхода больших списков.

Быстрый обход больших списков по ID

Смещение через start на глубоких страницах деградирует: чтобы вернуть записи с 100000-й, СУБД всё равно перебирает предыдущие. Для больших выгрузок применяют навигацию по последнему ID вместо смещения.

Схема такая:

1. Сортируем по ID по возрастанию: order[ID]=ASC.
2. Отключаем подсчёт: start=-1.
3. Фильтруем по filter[>ID]=последний_полученный_ID.
4. Повторяем, подставляя ID последней записи предыдущей пачки, пока приходит по 50 записей.

Пример: crm.deal.list?order[ID]=ASC&filter[>ID]=1500&select[]=ID&select[]=TITLE&start=-1. Такой обход не зависит от глубины страницы и держит стабильную скорость на миллионах записей.

Пагинация и batch

Пагинацию удобно сочетать с методом batch, но с оговоркой: списочная команда внутри batch всё равно вернёт лишь одну страницу. Batch помогает по-другому — за один HTTP-запрос забрать 50 разных страниц или скомбинировать список с последующими действиями.

Например, зная total из первого запроса, можно сформировать batch, где команды запрашивают start=0, start=50, …, start=2450 — до 50 страниц (2500 записей) за один вызов. Это классический способ быстро выгрузить средний по объёму справочник.

Сортировка, фильтр и select

Стабильность пагинации напрямую зависит от сортировки. Если порядок не задан явно, между страницами он может «плавать», и вы рискуете пропустить или продублировать записи. Всегда указывайте детерминированный order, лучше по уникальному ID.

• select — перечисляйте только нужные поля: меньше данных, быстрее ответ.
• filter — сужайте выборку на стороне портала, а не постфактум в коде.
• order — задавайте явно для предсказуемого порядка страниц.

Для CRM-методов дополнительно доступны префиксы фильтра: >, >=, <, % (подстрока), = — они и делают возможным обход по >ID.

Итог

Пагинация в REST Битрикс24 всегда идёт страницами по 50 записей: листаем через start, ориентируясь на поле next. Для больших выгрузок отключайте подсчёт total через start=-1 и переходите на навигацию по filter[>ID], чтобы не терять скорость на глубоких страницах.

Мы в B2Bsite проектируем выгрузки и синхронизации с Битрикс24, которые стабильно обходят сотни тысяч записей, не упираясь в тайм-ауты и лимиты нагрузки. Если ваша интеграция «захлёбывается» на больших объёмах — поможем переписать обход на быстрый и предсказуемый.