> ## 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.

# List leads

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

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.

`GET https://api.leadity.io/v1/scrapes/{id}/leads`

- Scope: `read`
- Spends credits: no
- MCP tool: `list_leads`

## Headers

- `Authorization`, string, required. Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

## Path parameters

- `id`, string, required. 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

- `cursor`, string, optional. The nextCursor of the previous page of leads. Leave it out for the first page. 1 to 200 characters.
- `limit`, integer, optional. How many leads one page holds, 1 to 1000. Default 100. 1 to 1,000. Default `100`.

## Example request

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

```javascript Node.js
const response = await fetch("https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/leads?limit=100", {
  headers: {
    Authorization: `Bearer ${process.env.LEADITY_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
```

```python Python
import os

import requests

response = requests.get(
    "https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/leads",
    params={"limit": 100},
    headers={
        "Authorization": f"Bearer {os.environ['LEADITY_API_KEY']}",
    },
)

print(response.json())
```

## Response

- `leads`, object[], required.
  - `name`, string, required. The business's name.
  - `phone`, string | null, required. The published phone number in E.164 form, e.g. +15125550123. Null when the business publishes none.
  - `phoneType`, string | null, required. The line type: mobile, landline, voip, toll_free, invalid or unknown. Null unless the order bought a phone filter or the phone reveal.
  - `website`, string | null, required.
  - `email`, string | null, required. An address found on the business's own site, when the order or an upgrade bought the email finder.
  - `emailStatus`, string | null, required. What the verifier made of email, when it was verified.
  - `ownerName`, string | null, required. The confirmed owner's name, when the order or an upgrade bought the owner lookup.
  - `address`, string | null, required.
  - `city`, string | null, required.
  - `state`, string | null, required.
  - `zip`, string | null, required.
  - `country`, string | null, required. The country code, e.g. US.
  - `niche`, string, required. The niche the lead was delivered under.
  - `rating`, number | null, required. The Google rating, 1 to 5. Null when the listing shows none.
  - `reviewCount`, integer | null, required. How many Google reviews the listing shows.
  - `timezone`, string | null, required. The business's IANA time zone, e.g. America/Chicago.
  - `placeId`, string | null, required. The Google Maps place id.
  - `mapsUrl`, string | null, required. The listing on Google Maps.
  - `scrapedAt`, string, required. When the business was found. An ISO 8601 timestamp in UTC.
- `nextCursor`, string | null, required. Pass it as cursor to read the next page. Null on the last page.
- `complete`, boolean, required. True once the scrape has settled and no lead can join the delivered set.

## Example response

```json 200
{
  "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
}
```

## Errors

Every refusal answers `{ error, message }` with the status below. The full list is on the [Errors](https://docs.leadity.io/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. |