Pagination

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.

​

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:

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