> ## 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.

# Pagination

> Retrieve complete result sets from YCloud list endpoints.

## What it is

Pagination lets you retrieve large collections in bounded responses. YCloud
list endpoints use either page-number or cursor pagination.

## Before you begin

Check the endpoint reference for its supported pagination parameters, filters,
sort order, and response shape. Do not assume every list endpoint uses the same
strategy.

## How it works

Request one page, process its items, and continue until the response indicates
that no next page exists. Keep the same filters and sort settings for the
entire traversal.

## Request and response

### Page-number pagination

Most list endpoints support these query parameters:

| Parameter | Description |
| - | - |
| `page` | Page number. It starts at `1` and defaults to `1`. |
| `limit` | Results per page. It ranges from `1` to `100` and defaults to `10`. |
| `includeTotal` | Set to `true` to include the total number of matching items. |

```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"
```

A page response contains:

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

| Response field | Meaning |
| - | - |
| `items` | Objects returned on this page. |
| `offset` | Zero-based starting position: `(page - 1) * limit`. |
| `limit` | Requested page size. |
| `length` | Actual number of items, equal to `items.length` and no greater than `limit`. |
| `total` | Total matching items; returned only when `includeTotal=true`. Counting can add latency, so request it only when needed. |

<Note>
  Offset-based endpoints commonly cap both `page` and `limit` at 100, limiting
  traversal to the first 10,000 items. Check each endpoint's limits and use
  cursor pagination when it is supported and you need a larger result set.
</Note>

Continue requesting the next page while `length` equals `limit`. Stop when `length` is less than `limit`.

### Cursor pagination

Endpoints that return `cursor.after` support cursor pagination. Pass that value as `pageAfter` in the next request.

```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"
```

A cursor response contains `items`, `limit`, `length`, and, when more results
exist, `cursor.after`. The cursor object is returned only by endpoints that
support cursor pagination.

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

Pass the returned cursor unchanged to the next request. Treat it as opaque;
do not modify it or store it as a long-term application identifier. Stop when
`length` is `0` or the response no longer contains `cursor.after`.

<Note>
  Pagination and filter parameters vary by endpoint. Check the API reference before implementing a list operation.
</Note>

## Implementation checklist

* Set an explicit `limit` instead of depending on the default.
* Preserve filters between page requests.
* Stop on the response condition, not on a guessed page count.
* Handle an empty first page as a successful result.
* Add a maximum page or item guard for background jobs.


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