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

​
Pagination Parameters

​
page_size
number
Maximum number of items per page (read-only, varies by operation)
​
page
number
Page number to retrieve (defaults to 1)

​
Pagination Headers

Each response includes headers to help you navigate:
​
X-Pagination-Next
string
URL for the next page — follow this exactly
​
X-Pagination-Previous
string
URL for the previous page — follow this exactly

​
How to iterate pages

  • Use page parameter to navigate (e.g., ?page=1, ?page=2)
  • X-Pagination-Previous header is available for backward navigation
  • You can jump to specific page numbers directly
Best practice: Always follow the X-Pagination-Next header as-is and stop when it’s no longer present: you reached the last page!

​
Pagination Example

1

1. Make the initial request

Use the page parameter to start fetching the first page of results (this is the default).
curl -i --request POST \
  --url 'https://api.captaindata.com/v1/find-company-employees' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "parameters": {}
  }'
2

2. Check the response headers

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

3. Fetch the next page

Use the URL from X-Pagination-Next or manually increment the page:
curl -i --request POST \
  --url 'https://api.captaindata.com/v1/find-company-employees?page=2' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "parameters": {}
  }'
4

4. Continue until done

Repeat until the X-Pagination-Next header is no longer present, meaning you’ve reached the last page.