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

# Pagination

> Lists page with a cursor. A live scrape's leads are complete only once the scrape has settled.

Operations that answer a list, such as [`list_leads`](https://docs.leadity.io/api-reference/scrapes/list-leads), [`list_scrapes`](https://docs.leadity.io/api-reference/scrapes/list-scrapes) and [`list_validation_items`](https://docs.leadity.io/api-reference/validations/list-validation-items), answer one page at a time.

| Field | Where | Meaning |
| --- | --- | --- |
| `limit` | query | How many items one page holds. Each operation documents its range and default. |
| `cursor` | query | The `nextCursor` of the previous page. Leave it out for the first page. |
| `nextCursor` | response | Pass it as `cursor` to read the next page. `null` on the last page. |

A cursor is opaque: pass it back as you got it and never build one yourself.

```javascript Node.js
const headers = { Authorization: `Bearer ${process.env.LEADITY_API_KEY}` };
const leads = [];
let cursor = null;

do {
  const url = new URL("https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/leads");
  url.searchParams.set("limit", "1000");
  if (cursor) url.searchParams.set("cursor", cursor);
  const page = await (await fetch(url, { headers })).json();
  leads.push(...page.leads);
  cursor = page.nextCursor;
} while (cursor);
```

## Paging a scrape that is still running

A lead list also answers `complete`. While it is `false` the scrape is still running and new leads are still arriving, and a lead can become delivered behind a cursor you have already passed.

- To follow a scrape as it runs, page freely, but treat what you hold as partial.
- To hold **every** lead, wait until `complete` is `true` (poll [`get_scrape_status`](https://docs.leadity.io/api-reference/scrapes/get-scrape-status)), then page from the start once more.
- For the whole list in one file, use [`download_leads`](https://docs.leadity.io/api-reference/scrapes/download-leads) once the scrape is complete.

[`list_validation_items`](https://docs.leadity.io/api-reference/validations/list-validation-items) answers `complete` the same way: while the run is live an item you have paged past can still be answered, so page again from the start once `complete` is `true`, or take the whole run as one file with [`download_validation`](https://docs.leadity.io/api-reference/validations/download-validation).

A cursor the API did not issue, or one built by hand, is refused with `invalid_body`, its `issues` naming `query.cursor`.