Skip to main content

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.

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

​
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.
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.
Last modified on December 23, 2025