Skip to main content
Some operations return multiple pages of results, especially searches. This quick guide explains how to handle pagination effectively.

​
Pagination Headers

Each response includes headers to help you navigate:
​
X-Pagination-Next
string
Full URL to fetch the next page — always use this URL as-is for reliable pagination. Contains the cursor for cursor-based pagination.
​
X-Pagination-Previous
string
Full URL to fetch the previous page — use this URL as-is for reliable pagination

​
Pagination Parameters

​
cursor
string
Cursor value for cursor-based pagination. Always obtain this from the X-Pagination-Next response header — do not construct cursor values manually. Cursors expire after 24 hours; if expired, restart pagination from the beginning.
​
page_size
number
Maximum number of items per page (read-only, varies by operation)
​
page
number
deprecated
Page number to retrieve. Removed as of January 15th, 2026 — use cursor-based pagination instead.

​
How to Paginate

Best practice: Always follow the X-Pagination-Next header URL as-is. Stop when it’s no longer present — you’ve reached the last page.
  • Extract the cursor from the X-Pagination-Next response header
  • Pass it as the cursor query parameter (or simply use the full URL from the header)
  • Cursors are valid for 24 hours — after that, you must restart from the beginning

​
Pagination Example

1

1. Make the initial request

Start fetching the first page of results (no cursor needed).
curl -i --request GET \
  --url 'https://api.captaindata.com/v1/people/search?query=(keywords%3Aceo)' \
  --header 'X-API-Key: <your-api-key>'
2

2. Check the response headers

Examine the response headers to find pagination info:
  • X-Pagination-Next: URL for next page (includes cursor) or absent if last page
  • X-Pagination-Previous: URL for previous page or absent if first page
3

3. Fetch the next page

Use the full URL from X-Pagination-Next:
curl -i --request GET \
  --url 'https://api.captaindata.com/v1/people/search?query=(keywords%3Aceo)&cursor=eyJwYWdlIjoyLCJza...' \
  --header 'X-API-Key: <your-api-key>'
4

4. Continue until done

Repeat until the X-Pagination-Next header is no longer present, meaning you’ve reached the last page.
Cursors expire after 24 hours. If you receive an error indicating an invalid or expired cursor, you must restart pagination from the beginning (without a cursor).