> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edges.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle Pagination

> Learn how pagination works in live, async, and schedule execution modes.

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.

<Warning>
  **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.
</Warning>

## 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

<Note>
  `max_results` has a default value for each action (see [API Reference](/v1/api/introduction)).
  There's also a maximum limit you cannot exceed (`0 <= x <= max_value`).
</Note>

### How Async Pagination Works

1. You specify `max_results: 100` in your request
2. Edges 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](/v1/runs/callbacks).

## Live Pagination (Manual)

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

<Warning>
  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.
</Warning>

### Pagination Parameters

<ParamField body="page_size" type="number">
  Maximum number of items per page (read-only, varies by action)
</ParamField>

<ParamField body="cursor" type="string">
  Cursor value obtained from the `X-Pagination-Next` response header of a previous request. Cursors expire after 24 hours.
</ParamField>

### Pagination Headers

Each response includes headers to help you navigate:

<ParamField body="X-Pagination-Next" type="string">
  URL for the next page containing the `cursor` parameter — **follow this exactly**
</ParamField>

<ParamField body="X-Pagination-Previous" type="string">
  Not always present — some actions **do not support previous page navigation**
</ParamField>

### 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

<Warning>
  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).
</Warning>

<Tip>
  **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!
</Tip>

## Live Pagination Example

<Steps>
  <Step title="1. Make the initial request">
    Start by fetching the first page of results (no cursor needed for the first request).

    ```bash theme={null}
    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"
      }'
    ```
  </Step>

  <Step title="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)
  </Step>

  <Step title="3. Fetch the next page">
    Use the **exact URL** from `X-Pagination-Next` header (includes the cursor):

    ```bash theme={null}
    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"
      }'
    ```
  </Step>

  <Step title="4. Continue until done">
    Repeat until the `X-Pagination-Next` header is **no longer present** — you've reached the last page.

    <Warning>
      **Critical:** Always use the exact URL from `X-Pagination-Next`. Cursors expire after 24 hours — if expired, restart from the beginning.
    </Warning>
  </Step>
</Steps>

<Tip>
  Don't want to handle pagination manually?\
  Use **async** or **schedule** modes — Edges will handle pagination and stream results via callbacks.
</Tip>

## Paginating Run Outputs & Inputs

The [`GET /runs/{run_uid}/outputs`](/v1/api/runs/outputs) and [`GET /runs/{run_uid}/inputs`](/v1/api/runs/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.

```bash theme={null}
# 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>"
```

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

## 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