Pagination

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.

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:

{
  "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.

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.

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.

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.

{
  "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.

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

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.

Getting Started

Guides

Endpoints

Webhooks

What it is

Before you begin

How it works

Request and response

Implementation checklist

​What it is

​Before you begin

​How it works

​Request and response

​Page-number pagination

​Cursor pagination

​Implementation checklist

What it is

Before you begin

How it works

Request and response

Page-number pagination

Cursor pagination

Implementation checklist