---
title: "Cursor Pagination for Search | Leadsets Docs"
description: "Page through Leadsets people and company search with next_cursor: page size 1 to 100, stable order, what each page costs, and loops in three languages."
canonical: https://www.leadsets.ai/docs/pagination
updated: 2026-11-11
---

Guides / Pagination

# Pagination.

Searches return results a page at a time. Pass `next_cursor` from one page as `cursor` on the next call, until it comes back null.

## How it works

- [POST /v1/people/search](https://www.leadsets.ai/docs/api/people-search) and [POST /v1/companies/search](https://www.leadsets.ai/docs/api/companies-search) page with a cursor. Enrich, verify and scrape calls answer in one response.
- `limit` sets the page size: 1–100, default 25. On the Free plan a call returns at most 10.
- Every search response has `next_cursor`: a string when there is more, `null` on the last page.
- Send the cursor back unchanged, with the same filters. Only `cursor` changes between pages.
- A cursor belongs to the endpoint that issued it. Sending it to another endpoint answers 400 `invalid_request` with `param: "cursor"`.
- Cursors don't expire, and results come in a stable order, so a later page never repeats an earlier one.

## Walk every page

```bash
# First page
curl https://api.leadsets.ai/v1/companies/search \
 -H "Authorization: Bearer $LEADSETS_KEY" \
 -H "Content-Type: application/json" \
 -d '{"industry": "saas", "country": "US", "limit": 100}'

# Next page: the same body plus next_cursor from the last response
curl https://api.leadsets.ai/v1/companies/search \
 -H "Authorization: Bearer $LEADSETS_KEY" \
 -H "Content-Type: application/json" \
 -d '{"industry": "saas", "country": "US", "limit": 100, "cursor": "c_eyJ0Ijoi…"}'
```

```ts
import { Leadsets } from "@leadsetsai/sdk";

const ls = new Leadsets(process.env.LEADSETS_KEY);
const query = { industry: "saas", country: "US", limit: 100 };

let cursor: string | undefined;
do {
 const page = await ls.companies.search({ ...query, cursor });
 for (const company of page.items) save(company);
 cursor = page.next_cursor ?? undefined;
} while (cursor);
```

```python
import os
from leadsets import Leadsets

ls = Leadsets(os.environ["LEADSETS_KEY"])
params = {"industry": "saas", "country": "US", "limit": 100}

while True:
   page = ls.companies.search(**params)
   for company in page.items:
       save(company)
   if not page.next_cursor:
       break
   params["cursor"] = page.next_cursor
```

## With the SDKs

The SDKs page for you. `searchAll` / `search_all` yields records across pages and stops at `maxItems` / `max_items` (the last page asks only for what is left, so you never pay for more than you take). `searchPages` / `search_pages` yields pages, so you can read `usage` between them; `maxPages` / `max_pages` caps the calls.

```ts
import { Leadsets } from "@leadsetsai/sdk";

const ls = new Leadsets(process.env.LEADSETS_KEY);
for await (const person of ls.people.searchAll({ title: ["VP Sales"], country: "US", limit: 100 }, { maxItems: 500 })) {
 save(person);
}

for await (const page of ls.people.searchPages({ country: "US", limit: 100 }, { maxPages: 5 })) {
 console.log(page.items.length, page.usage.search_records_left_5h);
}
```

```python
import os
from leadsets import Leadsets

ls = Leadsets(os.environ["LEADSETS_KEY"])
for person in ls.people.search_all(title=["VP Sales"], country="US", limit=100, max_items=500):
   save(person)

for page in ls.people.search_pages(country="US", limit=100, max_pages=5):
   print(len(page.items), page.usage.search_records_left_5h)
```

Breaking out of the loop stops fetching.

## What a page costs

Each page is one request and counts one search record per record it returns. An empty page counts no records. Pages use the same five-hour and weekly meters as any search, and each page takes one of your plan's concurrent-search slots while it runs. Details are in [Limits and costs](https://www.leadsets.ai/docs/limits).

On the Free plan, search has 100 records in total, so a full walk stops after 10 pages of 10.

## Long runs

Read `usage` on every page: it says what the page counted and what is left in the window. Stop or slow down before a meter runs out, or handle 429 `window_full` by waiting for `Retry-After`. A cursor stays valid while you wait, so a run can resume where it stopped. See [Errors and retries](https://www.leadsets.ai/docs/errors).

[Previous
**← SDKs**](https://www.leadsets.ai/docs/sdks) [Next
**Idempotency →**](https://www.leadsets.ai/docs/idempotency)

Was this page useful? [Tell us](mailto:support@leadsets.ai?subject=Docs%20feedback%3A%20%2Fdocs%2Fpagination)

---

Leadsets by Mobylogix LLC, 10160 hwy 242, Conroe, TX, 77385, US. Facts for AI assistants: https://www.leadsets.ai/llm · Site index: https://www.leadsets.ai/llms.txt · Every page: https://www.leadsets.ai/llms-full.txt