Pagination for List Endpoints

When retrieving data, it's important for it to be quick and easy. Our list endpoints have always returned all existing data when called. While this default is convenient, it can lead to performance issues when dealing with large datasets.

Today, we've introduced optional pagination to our existing list endpoints to help you efficiently browse through large datasets when needed.

How to use it

When calling an existing list endpoint, you can optionally add the limit query parameter to the request.

curl -X GET https://api.resend.com/api-keys?limit=30 \
-H "Authorization: Bearer re_xxxxxxxxx"

This will return the first 30 API keys in the list.

{
  "object": "list",
  "has_more": true,
  "data": [
    /* Array of 30 API keys */
  ]
}

To retrieve additional pages, use the before or after params to go through the list.

Forward pagination

curl -X GET 'https://api.resend.com/api-keys?limit=10&after=LAST_ID_FROM_PREVIOUS_PAGE' \
     -H 'Authorization: Bearer re_xxxxxxxxx'

Backwards pagination

curl -X GET 'https://api.resend.com/api-keys?limit=10&before=SOME-EMAIL-ID' \
     -H 'Authorization: Bearer re_xxxxxxxxx'

You can safely navigate lists with guaranteed stability, even if new objects are created or deleted while you’re still requesting pages.

Supported endpoints

The following endpoints support optional pagination:

• GET /api-keys
• GET /audiences
• GET /contacts
• GET /domains
• GET /broadcasts

Query Parameters

All paginated endpoints support the following parameters:

• limit: The number of items to return per page. Maximum is 100. Minimum is 1.
• after: The cursor after which to start retrieving items. To get the next page, use the ID of the last item from the current page. This will return the page that starts after the object with this ID (excluding the passed ID itself).
• before: The cursor before which to start retrieving items. To get the previous page, use the ID of the first item from the current page. This will return the page that ends before the object with this ID (excluding the passed ID itself).

List Endpoints Response

When you request a paginated endpoint, the response includes:

{
  "object": "list", // Always set to list.
  "has_more": true, // Indicates whether there are more elements available.
  "data": [
    /* Array of resources */
  ]
}

Pagination may return the following validation errors:

• validation_error: Invalid cursor format or limit out of range (1-100).
• validation_error: Both before and after parameters provided.

{
  "name": "validation_error",
  "statusCode": 422,
  "message": "The pagination limit must be a number between 1 and 100. See https://resend.com/docs/api-reference/pagination for more information."
}

Best Practices

Follow these best practices when using pagination:

1. Choose a limit that balances performance and usability. Smaller pages are good for real-time applications, while larger pages (hundreds of items) work better for bulk processing.
2. Handle pagination gracefully. Always check the has_more field before attempting to fetch additional pages. This prevents unnecessary API calls when you’ve reached the end of the dataset.
3. Consider rate limits. Implement appropriate delays or batching strategies if processing many pages.

Conclusion

We're excited for the new control pagination gives you over your data and plan to include pagination by default in the future.

If you have any questions, please reach out to us and we'll be happy to help.