Scrapes

List leads

Read a scrape's delivered leads, a page at a time.

GETapi.leadity.io/v1/scrapes/{id}/leads

Scope readMCP tool list_leads

Answers a page of a scrape's delivered leads, oldest first. Page with cursor until nextCursor is null. complete is true once the scrape has settled. While it is false the scrape is live, and a lead can still become delivered below a cursor already passed, so for every lead of a live scrape, page again from the start once complete is true. For the whole list as a file, call download_leads.

Example request

curl "https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/leads?limit=100" \
  -H "Authorization: Bearer $LEADITY_API_KEY"

Example response

{
  "leads": [
    {
      "name": "Lone Star Roofing Co",
      "phone": "+15125550123",
      "phoneType": "mobile",
      "website": "https://lonestarroofing.example",
      "email": null,
      "emailStatus": null,
      "ownerName": null,
      "address": "1200 E 6th St",
      "city": "Austin",
      "state": "TX",
      "zip": "78702",
      "country": "US",
      "niche": "roofing contractor",
      "rating": 4.8,
      "reviewCount": 212,
      "timezone": "America/Chicago",
      "placeId": "0x8644b5a0e5d7a1c3:0x2f1e4b8d9c7a6e5f",
      "mapsUrl": "https://www.google.com/maps/place/?q=place_id:ChIJw6HX5aC1RIYRX256nI1LHi8",
      "scrapedAt": "2026-10-03T16:52:18.000Z"
    }
  ],
  "nextCursor": "bGVhZDo5MTI0NDE",
  "complete": true
}

Headers

Authorizationstringrequired

Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

Path parameters

idstringrequired

The scrape's id, as create_scrape and list_scrapes answer it.

1 to 64 characters, matches ^[A-Za-z0-9]{1,64}$.

Query parameters

cursorstring

The nextCursor of the previous page of leads. Leave it out for the first page.

1 to 200 characters.

limitintegerdefault 100

How many leads one page holds, 1 to 1000. Default 100.

1 to 1,000.

Response

leadsobject[]required

Show child attributes

namestringrequired

The business's name.

phonestring | nullrequired

The published phone number in E.164 form, e.g. +15125550123. Null when the business publishes none.

phoneTypestring | nullrequired

The line type: mobile, landline, voip, toll_free, invalid or unknown. Null unless the order bought a phone filter or the phone reveal.

websitestring | nullrequired

emailstring | nullrequired

An address found on the business's own site, when the order or an upgrade bought the email finder.

emailStatusstring | nullrequired

What the verifier made of email, when it was verified.

ownerNamestring | nullrequired

The confirmed owner's name, when the order or an upgrade bought the owner lookup.

addressstring | nullrequired

citystring | nullrequired

statestring | nullrequired

zipstring | nullrequired

countrystring | nullrequired

The country code, e.g. US.

nichestringrequired

The niche the lead was delivered under.

ratingnumber | nullrequired

The Google rating, 1 to 5. Null when the listing shows none.

reviewCountinteger | nullrequired

How many Google reviews the listing shows.

timezonestring | nullrequired

The business's IANA time zone, e.g. America/Chicago.

placeIdstring | nullrequired

The Google Maps place id.

mapsUrlstring | nullrequired

The listing on Google Maps.

scrapedAtstringrequired

When the business was found. An ISO 8601 timestamp in UTC.

nextCursorstring | nullrequired

Pass it as cursor to read the next page. Null on the last page.

completebooleanrequired

True once the scrape has settled and no lead can join the delivered set.

Errors

Every refusal answers { error, message } with the status below. The full list is on the Errors page.

Code	Status	Meaning	Extra fields
unauthorized	401	The API key is missing, malformed, revoked or expired.	-
wrong_key_kind	401	This key opens the other surface: an API key works on the HTTP API, an MCP key on the MCP server.	-
account_suspended	403	The account is suspended.	-
email_not_verified	403	The account's email address is not verified yet.	-
invalid_body	400	The request does not match the operation's schema.	`issues`: The problems found, each with path (the field as a dotted path, led by the part of the request it travels in: path, query or body, such as body.items.1) and message (what is wrong there).
not_found	404	No such resource on this account.	`id`: On export_scrapes: the first id that is not one of the account's scrapes.
rate_limited	429	Too many requests. Wait for the Retry-After seconds and try again.	`retryAfterSeconds`: The seconds to wait, the same number as the Retry-After header.
try_again	503	Leadity could not answer just now. Retry in a moment, with the same Idempotency-Key on a spending call.	`retryAfterSeconds`: When a request with this Idempotency-Key is still being processed: the seconds to wait before retrying with the same key, as the Retry-After header says.
internal_error	500	Something failed on our side. Nothing was charged twice.	`body`: On the MCP server, when Leadity answered in a shape the tool does not publish: that answer as it came.