How Poptin API list endpoints use cursor or offset pagination, including query parameters, response metadata, and iteration examples.
List endpoints use one of two pagination methods:
- Cursor pagination for List contacts and List conversions.
- Offset pagination for the other list endpoints.
Always check the individual operation page for its current parameters, defaults, and limits.
Shared parameter
Both methods accept per_page:
| Parameter | Type | Description |
|---|---|---|
per_page | integer | Number of items returned per request. Optional; each operation defines its default and maximum. |
Values outside an operation's accepted range return HTTP 422 with validation details in the standard response envelope.
Cursor pagination
List contacts and List conversions use cursor pagination. Do not send page to these operations.
The first request omits cursor:
GET /v1/contacts?per_page=100A successful response includes:
| Field | Type | Description |
|---|---|---|
per_page | integer | Page size used for this response. |
next_cursor | string | null | Opaque cursor for the next page. null when there is no next page. |
prev_cursor | string | null | Opaque cursor for the previous page. null when there is no previous page. |
has_more | boolean | Whether another page exists in the forward direction. |
{
"success": true,
"message": "Request completed successfully.",
"data": {
"contacts": []
},
"errors": null,
"meta": {
"per_page": 100,
"next_cursor": "eyJjcmVhdGVkX2F0Ijoi...",
"prev_cursor": null,
"has_more": true
}
}To continue forward, pass meta.next_cursor unchanged as cursor:
GET /v1/contacts?per_page=100&cursor=eyJjcmVhdGVkX2F0Ijoi...Continue until has_more is false and next_cursor is null. To move backward, pass meta.prev_cursor as cursor.
Cursors are opaque. Do not decode, edit, or construct them. Keep per_page and all filters, such as email, status, created_from, and created_to unchanged while traversing a result set.
Cursor pagination does not return total, current_page, or last_page.
Offset pagination
Other list endpoints use page and per_page:
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number to return, and defaults to 1. |
per_page | integer | Number of items per page. Optional; defaults and limits vary by operation. |
Their meta object contains:
| Field | Type | Description |
|---|---|---|
current_page | integer | Page returned by this response. |
last_page | integer | Highest available page number. |
per_page | integer | Page size used for this response. |
total | integer | Total rows matching the query. |
Request page + 1 until current_page reaches last_page.
Defaults and limits
Defaults and maximum page sizes vary by resource. Treat each operation page in the API Reference as the source of truth.
For large collections, use a moderate per_page, preserve filters across requests, and back off if the API returns 429 Too Many Requests.
meta is populated on list endpoints. Show, create, update, and delete operations normally return "meta": null.