---
url: /topics/pagination.md
---
# Pagination

When listing resources, the API returns results in **pages**. Pagination ensures responses stay fast and predictable, even when dealing with large datasets.

All collection endpoints implement a **consistent pagination model**.

## Offset-based pagination

By default, the API uses **offset-based pagination** with the following query parameters:

| Parameter | Type    | Description                       |
| --------- | ------- | --------------------------------- |
| `page`    | integer | Page number to retrieve           |
| `perPage` | integer | Number of items returned per page |

Example request:

```http
GET /v1/subscription/subscribers?perPage=50&page=2
```

This request returns the **second page** of subscribers with **50 items per page**.

## Response format

List endpoints return a JSON object containing:

* a `data` array with the resources for the current page
* a `meta` object with pagination information

Example response:

```json
{
  "data": [
    ...
  ],
  "meta": {
    "page": 2,
    "perPage": 50,
    "totalPages": 180,
    "totalCount": 8997,
    "hasNext": true,
    "hasPrevious": true
  }
}
```

### `meta` fields

| Field         | Description                                                 |
| ------------- | ----------------------------------------------------------- |
| `page`        | Current page number                                         |
| `perPage`     | Number of items returned per page                           |
| `totalPages`  | Total number of available pages                             |
| `totalCount`  | Total number of resources available                         |
| `hasNext`     | Indicates whether another page exists after the current one |
| `hasPrevious` | Indicates whether a previous page exists                    |

## Default values

If pagination parameters are not provided, default values are applied.

| Parameter | Default | Maximum |
| --------- | ------- | ------- |
| `perPage` | 20      | 100     |
| `page`    | 1       | —       |

Example:

```http
GET /v1/subscription/subscribers
```

is equivalent to:

```http
GET /v1/subscription/subscribers?page=1&perPage=20
```

Some endpoints may override the maximum `perPage` value depending on resource constraints.

## Best practices

When consuming paginated endpoints:

* Always assume responses may contain **multiple pages**
* Use `hasNext` to determine if additional requests are required
* Avoid requesting unnecessarily large `perPage` values
* Cache results when possible to reduce repeated pagination queries