Handle Pagination

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.

Quick Decision Guide

Not sure which approach fits your use case? Here’s how to decide:

⚡️ Live mode is ideal when you have a single input and expect few results. It’s the simplest and fastest way to get your data immediately.
📦 Async/Schedule modes are better suited when you expect a lot of results and want to avoid manual pagination. Results are streamed progressively via callbacks, as soon as they’re processed.

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.

Execution Modes & Pagination

Edges handles pagination differently based on your execution mode:

Execution Mode	Who Handles Pagination	How You Control It
`live`	You (manually)	Use `cursor` param and follow response headers
`async`/`schedule`	Edges	Use `max_results` parameter only

live mode: You handle pagination manually using the cursor from response 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 - Edges 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).

How Async Pagination Works

You specify max_results: 100 in your request
Edges automatically paginates with optimal page_size
You receive multiple callbacks, each with a batch of results
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:

In live mode, you won’t receive the total number of pages in advance.
In any case, you should keep following the X-Pagination-Next header until it’s no longer present — this means you’ve reached the end.As you have full ownership over fetching the results, live mode does not support max_results parameter.

Pagination Parameters

number

Maximum number of items per page (read-only, varies by action)

string

Cursor value obtained from the X-Pagination-Next response header of a previous request. Cursors expire after 24 hours.

Pagination Headers

Each response includes headers to help you navigate:

string

URL for the next page containing the cursor parameter — follow this exactly

string

Not always present — some actions do not support previous page navigation

Cursor-Based Pagination

Live mode uses cursor-based pagination for reliable, consistent results:

The X-Pagination-Next header contains a URL with a cursor parameter
This cursor is required to access the next page
Cursors expire after 24 hours — if expired, restart pagination from the beginning
You cannot jump to a specific page — always follow the cursor sequence

Do not try to construct cursor values manually — always use the exact cursor from the X-Pagination-Next header. If a cursor has expired or is invalid, restart pagination from the beginning (omit the cursor parameter).

Best practice: Always follow the X-Pagination-Next header as-is and stop when it’s no longer present — you’ve reached the last page!

Live Pagination Example

1. Make the initial request

Start by fetching the first page of results (no cursor needed for the first request).

curl -i --request POST \
  --url 'https://api.edges.run/v1/actions/linkedin-search-people/run/live' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "parameters": {},
    "identity_mode": "auto"
  }'

2. Check the response headers

Examine the response headers to find pagination info:

X-Pagination-Next: URL with cursor for next page, or null if last page
X-Pagination-Previous: URL for previous page (not always present)

3. Fetch the next page

Use the exact URL from X-Pagination-Next header (includes the cursor):

curl -i --request POST \
  --url 'https://api.edges.run/v1/actions/linkedin-search-people/run/live?cursor=eyJwYWdlIjoyLCJ0b2tlbiI6ImFiYzEyMyJ9' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <your-api-key>' \
  --data '{
    "parameters": {},
    "identity_mode": "auto"
  }'

4. Continue until done

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

Critical: Always use the exact URL from X-Pagination-Next. Cursors expire after 24 hours — if expired, restart from the beginning.

Don’t want to handle pagination manually?
Use async or schedule modes — Edges will handle pagination and stream results via callbacks.

Paginating Run Outputs & Inputs

The GET /runs/{run_uid}/outputs and GET /runs/{run_uid}/inputs endpoints use cursor-based pagination by default.

Use limit to control page size (default: 100, max: 500).
Follow the X-Pagination-Next response header to fetch the next page — it contains the full URL with limit and cursor.
Stop when the X-Pagination-Next header is absent — there are no more pages.

# First page
curl -X GET "https://api.edges.run/v1/runs/{run_uid}/outputs?limit=200" \
  -H "X-API-Key: <YOUR_API_KEY>"

# Next page — use the exact URL from X-Pagination-Next
curl -X GET "https://api.edges.run/v1/runs/{run_uid}/outputs?limit=200&cursor=<cursor_value>" \
  -H "X-API-Key: <YOUR_API_KEY>"

The offset parameter is deprecated on these endpoints. If provided, the system falls back to offset-based pagination and cursor pagination is not used.

Best Practices Summary

For Live Mode

Follow the X-Pagination-Next header iteratively until it is no longer present
Always use the exact URL from X-Pagination-Next — never construct cursor values manually
Handle cursor expiration gracefully — restart from the beginning if you receive an error (cursors expire after 24 hours)

For Async/Schedule Modes

Set max_results parameter to control how many total results you want
Results are delivered progressively via callbacks as soon as they’re processed
No manual pagination handling required

For Run Outputs & Inputs

Follow the X-Pagination-Next header — same pattern as live mode
Use limit to control page size (default: 100, max: 500)
Do not use offset — it is deprecated and disables cursor pagination

Getting Started

Essentials

Build with Edges

Handle Pagination

Quick Decision Guide

Paginating Run Outputs & Inputs

Best Practices Summary

For Live Mode

For Async/Schedule Modes

For Run Outputs & Inputs

​Quick Decision Guide

​Execution Modes & Pagination

​Async Pagination (Automatic)

​How Async Pagination Works

​Live Pagination (Manual)

​Pagination Parameters

​Pagination Headers

​Cursor-Based Pagination

​Live Pagination Example

​Paginating Run Outputs & Inputs

​Best Practices Summary

​For Live Mode

​For Async/Schedule Modes

​For Run Outputs & Inputs

Quick Decision Guide

Execution Modes & Pagination

Async Pagination (Automatic)

How Async Pagination Works

Live Pagination (Manual)

Pagination Parameters

Pagination Headers

Cursor-Based Pagination

Live Pagination Example

Paginating Run Outputs & Inputs

Best Practices Summary

For Live Mode

For Async/Schedule Modes

For Run Outputs & Inputs