Some actions return multiple pages of results, especially search actions and extractions that return lists of data. How pagination works depends on your execution mode.

​
Execution Modes & Pagination

Captain Data handles pagination differently based on your execution mode:
  • live mode: You handle pagination manually using page parameters and headers
  • async/schedule modes: Pagination is automatic - you just specify how many results you want

​
Async Pagination (Automatic)

In async and schedule modes, pagination is completely automated:
  • No manual handling required - Captain Data handles all pagination internally
  • Use max_results parameter - Specify how many total results you want
  • Results delivered via callbacks - Each page generates a separate callback
  • Progressive delivery - Start receiving data immediately
max_results has a default value for each action (see API Reference). There’s also a maximum limit you cannot exceed (0 <= x <= max_value).
Result count may vary: LinkedIn and other platforms may insert sponsored content or dynamic results that don’t match your exact request. We filter these out, which may result in fewer results than expected.

​
How Async Pagination Works

  1. You specify max_results: 100 in your request
  2. Captain Data automatically paginates with optimal page_size
  3. You receive multiple callbacks, each with a batch of results
  4. Each callback has status: RUNNING until the final SUCCEEDED callback
For detailed callback handling, see Managing Callbacks.

​
Live Pagination (Manual)

In live mode, you control pagination manually for real-time responses:

​
Pagination Parameters

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

​
Pagination Headers

Each response includes headers to help you navigate:
​
X-Pagination-Previous
string
URL for the previous page, or null if you’re on the first page
​
X-Pagination-Next
string
URL for the next page, or null if you’re on the last page
Best practice: Use the X-Pagination-Next header to navigate pages. While you could manually construct URLs with page numbers, using the provided headers ensures compatibility with future pagination systems.

​
Example: Live Pagination with cURL

​
Step 1: Make the initial request

curl -i --request POST \
  --url 'https://api.captaindata.com/v4/actions/salesnavigator-search-company-employees/run/live?page=1' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "parameters": {},
    "identity_mode": "auto"
  }'

​
Step 2: Check the response headers

You’ll receive pagination headers:
  • X-Pagination-Previous: null (first page)
  • X-Pagination-Next: https://api.captaindata.com/v4/actions/salesnavigator-search-company-employees/run/live?page=2

​
Step 3: Fetch the next page

Use the URL from X-Pagination-Next: 
curl -i --request POST \
  --url 'https://api.captaindata.com/v4/actions/salesnavigator-search-company-employees/run/live?page=2' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "parameters": {},
    "identity_mode": "auto"
  }'

​
Step 4: Continue until complete

Repeat this process until X-Pagination-Next returns null, indicating you’ve reached the last page.
Complete data access: This approach ensures you can retrieve all available data, regardless of the number of pages!