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

# Pagination

> Efficiently retrieve large sets of data

Posta uses cursor-based pagination for endpoints that return lists of objects. This guide explains how to work with paginated responses and retrieve large datasets efficiently.

## How pagination works

When you make a request to an endpoint that returns multiple objects, you can control the number of items returned and navigate through pages using two parameters:

1. `pageSize`: The number of items to return per page.
2. `nextToken`: A cursor for the next page of results.

<Note>
  1) Treat `nextToken` as an opaque identifier that's only used to retrieve the next items in a list and not for other programmatic purposes.
  2) `nextToken` should not be persisted as it's only valid for the given pagination.
</Note>

## Using pagination

### Initial request

For your first request, you typically only need to specify the `pageSize`:

```
GET /v1/letters?pageSize=25
```

### Subsequent requests

The response will include a `nextToken` if there are more results available. Use this token in your next request to retrieve the next page:

```
GET /v1/letters?pageSize=25&nextToken=eyJsYXN0SXRlbUlkIjoxMjM0NX0=
```

Continue using the `nextToken` from each response until you receive a response without a `nextToken`, indicating you've reached the end of the results.

## Response format

A paginated response will have the following structure:

```json theme={null}
{
  "items": [
    // Array of items for the current page
  ],
  "nextToken": "eyJsYXN0SXRlbUlkIjoxMjM0NX0="
}
```

## Best practices

1. **Consistent page size**: Keep the `pageSize` consistent between requests for predictable behavior.
2. **Handle missing tokens**: If a response doesn't include a `nextToken`, you've reached the end of the results.
3. **Error handling**: Implement proper error handling for cases where a `nextToken` might become invalid.
4. **Iterate efficiently**: Use a loop or recursive function to automatically fetch all pages when needed.

## Limitations

* The maximum `pageSize` is 100 items.

<Warning>
  Setting a very large `pageSize` may impact API performance and response times. We recommend using a moderate page size and iterating through results as needed.
</Warning>