Using the API

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, list_scrapes and 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.

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), then page from the start once more.
For the whole list in one file, use download_leads once the scrape is complete.

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.

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