Skip to main content

​
Overview

Several Resend API endpoints support cursor-based pagination to help you efficiently browse through large datasets. You can safely navigate lists with guaranteed stability, even if new objects are created or deleted while you’re still requesting pages. Paginated endpoints responses include:
  • object: always set to list.
  • has_more: indicates whether there are more elements available.
  • data: the list of returned items.
You can navigate through the results using the following parameters:
  • limit: the number of items to return per page.
  • after: the cursor to use to get the next page of results.
  • before: the cursor to use to get the previous page of results.
Use the id of objects as the cursor for pagination. The cursor itself is excluded from the results. For an example, see pagination strategies below.

​
Currently-supported endpoints

Existing list endpoints can optionally return paginated results:
Note that for these endpoints, the limit parameter is optional. If you do not provide a limit, all items will be returned in a single response.
Newer list endpoints always return paginated results:

​
Parameters

All paginated endpoints support the following query parameters:
​
limit
number
The number of items to return per page. Default is 20, maximum is 100, and minimum is 1.
​
after
string
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
string
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).
You can only use either after or before, not both simultaneously.

​
Response Format

Paginated endpoints return responses in the following format:
Response Format
{
  "object": "list",
  "has_more": true,
  "data": [
    /* Array of resources */
  ]
}
​
object
string
Always set to list for paginated responses.
​
has_more
boolean
Indicates whether there are more items available beyond the current page.
​
data
array
An array containing the actual resources for the current page.

​
Strategies

​
Forward Pagination

To paginate forward through results (newer to older items), use the after parameter with the ID of the last item from the current page: 
const resend = new Resend('re_xxxxxxxxx');

// First page
const { data: firstPage } = await resend.contacts.list({ limit: 50 });

// Second page (if has_more is true)
if (firstPage.has_more) {
  const lastId = firstPage.data[firstPage.data.length - 1].id;
  const { data: secondPage } = await resend.contacts.list({
    limit: 50,
    after: lastId,
  });
}

​
Backward Pagination

To paginate backward through results (older to newer items), use the before parameter with the ID of the first item from the current page (or the most recent ID you have in your system): 
const resend = new Resend('re_xxxxxxxxx');

// Start from a specific point and go backward
const page = await resend.contacts.list({
  limit: 50,
  before: 'some-contact-id',
});

if (page.data.has_more) {
  const firstId = page.data.data[0].id;
  const previousPage = await resend.contacts.list({
    limit: 50,
    before: firstId,
  });
}

​
Best Practices

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.
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.
Be mindful of API rate limits when paginating through large datasets. Implement appropriate delays or batching strategies if processing many pages.

​
Error Handling

Pagination requests may return the following validation errors:
ErrorDescription
validation_errorInvalid cursor format or limit out of range (1-100)
validation_errorBoth before and after parameters provided
Example error response:
Error Response
{
  "name": "validation_error",
  "statusCode": 422,
  "message": "The pagination limit must be a number between 1 and 100. See https://resend.com/docs/pagination for more information."
}
⌘I