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 and POST /v1/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

cURLTypeScriptPython

# 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…"}'

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);

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.

TypeScriptPython

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);
}

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.

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.

Previous
← SDKsNext
Idempotency →

Was this page useful? Tell us