> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Пагинация

> Получение полных наборов результатов из эндпоинтов со списками YCloud.

## Что это такое

Пагинация позволяет получать большие коллекции данных в виде ограниченных ответов. Эндпоинты со списками YCloud используют либо пагинацию по номерам страниц, либо пагинацию по курсору.

## Перед началом работы

Ознакомьтесь со справочником по эндпоинту, чтобы узнать поддерживаемые параметры пагинации, фильтры, порядок сортировки и структуру ответа. Не предполагайте, что каждый эндпоинт списка использует одну и ту же стратегию.

## Как это работает

Запросите одну страницу, обработайте ее элементы и продолжайте до тех пор, пока ответ не покажет, что следующей страницы нет. Сохраняйте одинаковые фильтры и параметры сортировки на протяжении всего обхода.

## Запрос и ответ

### Пагинация по номерам страниц

Большинство эндпоинтов списков поддерживают следующие параметры запроса:

| Параметр | Описание |
| - | - |
| `page` | Номер страницы. Начинается с `1`, по умолчанию равен `1`. |
| `limit` | Количество результатов на странице. Диапазон от `1` до `100`, по умолчанию — `10`. |
| `includeTotal` | Установите значение `true`, чтобы включить общее количество подходящих элементов. |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/contact/contacts?page=1&limit=100&includeTotal=true" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

Ответ со страницей содержит:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "offset": 0,
  "limit": 100,
  "length": 2,
  "total": 2,
  "items": [{ "id": "ITEM_1" }, { "id": "ITEM_2" }]
}
```

| Поле ответа | Значение |
| - | - |
| `items` | Объекты, возвращенные на этой странице. |
| `offset` | Начальная позиция с отсчетом от нуля: `(page - 1) * limit`. |
| `limit` | Запрошенный размер страницы. |
| `length` | Фактическое количество элементов, равное `items.length` и не превышающее `limit`. |
| `total` | Общее количество подходящих элементов; возвращается только при `includeTotal=true`. Подсчет может увеличить задержку, поэтому запрашивайте его только при необходимости. |

<Note>
  Эндпоинты на основе смещения обычно ограничивают как `page`, так и `limit` значением 100, ограничивая
  обход первыми 10 000 элементами. Проверяйте ограничения каждого эндпоинта и используйте
  пагинацию по курсору, если она поддерживается и вам требуется больший набор результатов.
</Note>

Продолжайте запрашивать следующую страницу, пока `length` равно `limit`. Остановитесь, когда `length` станет меньше `limit`.

### Пагинация по курсору

Эндпоинты, возвращающие `cursor.after`, поддерживают пагинацию по курсору. Передавайте это значение в качестве `pageAfter` в следующем запросе.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.ycloud.com/v2/unsubscribers?limit=100&pageAfter=id%3Afoo" \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

Ответ с курсором содержит `items`, `limit`, `length` и, если есть дополнительные результаты, `cursor.after`. Объект курсора возвращается только теми эндпоинтами, которые поддерживают пагинацию по курсору.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [{ "id": "ITEM_1" }],
  "limit": 1,
  "length": 1,
  "cursor": { "after": "id:foo" }
}
```

Передавайте возвращенный курсор в следующий запрос без изменений. Относитесь к нему как к непрозрачному значению; не изменяйте его и не сохраняйте в качестве постоянного идентификатора в приложении. Остановитесь, когда `length` примет значение `0` или ответ больше не будет содержать `cursor.after`.

<Note>
  Параметры пагинации и фильтрации различаются в зависимости от эндпоинта. Перед реализацией операции получения списка обратитесь к справочнику API.
</Note>

## Чек-лист по реализации

* Указывайте явное значение `limit`, а не полагайтесь на значение по умолчанию.
* Сохраняйте фильтры между запросами страниц.
* Останавливайтесь по условию в ответе, а не по предполагаемому количеству страниц.
* Обрабатывайте пустую первую страницу как успешный результат.
* Добавьте ограничение на максимальное количество страниц или элементов для фоновых задач.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.