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

# Get scrape

> Read one scrape in full: its selection, its progress and its upgrades.

Answers one scrape in full: everything list_scrapes carries plus its exact selection, the scrapes bought out of it, how many reviews it holds, and the progress of any upgrade bought on it. To poll a live scrape, call get_scrape_status instead, which is cheaper. To see what a finished scrape can still sell, call list_scrape_offers.

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

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

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

## Example request

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

```javascript Node.js
const response = await fetch("https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k", {
  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",
    headers={
        "Authorization": f"Bearer {os.environ['LEADITY_API_KEY']}",
    },
)

print(response.json())
```

## Response

- `id`, string, required. The scrape's id.
- `title`, string, required. The scrape's name as the app shows it: the customer's own, or one derived from its niches and areas.
- `customTitle`, string | null, required. The name the customer gave it, or null when the title is derived.
- `status`, string, required. reserving, queued and running are live; stopping and settling are finishing; completed is final. One of: `reserving`, `queued`, `running`, `stopping`, `settling`, `completed`.
- `source`, string, required. Where this was started: dashboard (the Leadity app), api (an API key), mcp (an MCP key), stress or import (Leadity's own tools). One of: `dashboard`, `api`, `mcp`, `stress`, `import`.
- `niches`, object[], required. The niches ordered.
  - `id`, string, required. The niche id, Google's own category slug.
  - `name`, string, required. The niche's name.
- `areaSummary`, object, required. Where the scrape searched, in brief. get_scrape carries the full selection.
  - `regions`, string[], required. Every region the selection touches, as COUNTRY:REGION, e.g. US:TX.
  - `zipCount`, integer, required. How many single ZIP or postal codes the selection names.
- `filters`, object, required. The filters the scrape runs, as resolved when it was ordered: the same vocabulary create_scrape takes, with every filter present (phoneTypeFilter, websitePresence, findOwner, nicheMatch, minGoogleReviews) and the add-ons (emailFinder, reviews) present only when ordered. Fields can be added as the product grows, so read the ones you know and ignore the rest.
- `targetLeads`, integer, required. The most leads the order delivers.
- `leadsDelivered`, integer | null, required. Leads delivered, set when the scrape settles. Null before.
- `leadsSoFar`, integer | null, required. Leads delivered so far while the scrape is live. Null once it has settled, when leadsDelivered holds the count.
- `reservedCredits`, integer, required. Credits held when the order was placed.
- `creditsUsed`, integer | null, required. Credits the scrape kept, set when it settles; the rest of the hold was refunded. Null before.
- `reviewsReservedCredits`, integer, required. The part of the hold set aside for review scraping. 0 when none was ordered.
- `reviewsScraped`, integer | null, required. Google reviews walked, set when the scrape settles. Null when none were ordered.
- `emailsFound`, integer | null, required. Email addresses found by the email filter, set when the scrape settles.
- `duplicatesSkipped`, integer | null, required. Businesses the account already held, in any niche, that this scrape skipped and never charged. Null before it settles.
- `stoppedByUser`, boolean, required. True when the customer stopped the scrape before it filled.
- `parentId`, string | null, required. For a scrape bought out of another one (held-back leads, an owner-name run), the scrape it came from. Null otherwise.
- `createdAt`, string, required. When the order was placed. An ISO 8601 timestamp in UTC.
- `startedAt`, string | null, required. When the scrape started running. An ISO 8601 timestamp in UTC, or null.
- `settledAt`, string | null, required. When the scrape settled and refunded what it did not use. An ISO 8601 timestamp in UTC, or null.
- `selection`, object, required. The areas ordered, in the shape create_scrape takes, so the scrape can be ordered again.
  - `states`, object[], required. Whole regions.
    - `country`, string, required.
    - `state`, string, required.
  - `zips`, object[], required. Single ZIP or postal codes.
    - `country`, string, required.
    - `state`, string, optional.
    - `code`, string, required.
- `origin`, string | null, required. For a scrape bought out of another: residual for held-back leads, enrichment for an owner-name run. Null for an order. One of: `residual`, `enrichment`.
- `children`, object[], required. The scrapes bought out of this one, oldest first.
  - `id`, string, required.
  - `title`, string, required.
  - `status`, string, required. reserving, queued and running are live; stopping and settling are finishing; completed is final. One of: `reserving`, `queued`, `running`, `stopping`, `settling`, `completed`.
  - `leadsDelivered`, integer | null, required.
  - `creditsUsed`, integer | null, required.
  - `createdAt`, string, required. When it was bought. An ISO 8601 timestamp in UTC.
- `reviewsAvailable`, integer, required. Google reviews held so far. download_reviews serves them.
- `upgrades`, object, required. Upgrades bought on this scrape.
  - `emailFind`, object | null, required. The email-find upgrade's latest run, or null.
    - `status`, string, required. One of: `running`, `completed`.
    - `pool`, integer, required. What the run could draw from when it was bought.
    - `target`, integer, required. The results ordered.
    - `results`, integer, required. Results so far: addresses found, or billable verdicts.
    - `reservedCredits`, integer, required. Credits held when it was bought.
    - `creditsUsed`, integer | null, required. Credits it kept, once completed. Null while running.
  - `emailVerify`, object | null, required. The email-verify upgrade's latest run, or null.
    - `status`, string, required. One of: `running`, `completed`.
    - `pool`, integer, required. What the run could draw from when it was bought.
    - `target`, integer, required. The results ordered.
    - `results`, integer, required. Results so far: addresses found, or billable verdicts.
    - `reservedCredits`, integer, required. Credits held when it was bought.
    - `creditsUsed`, integer | null, required. Credits it kept, once completed. Null while running.
  - `ownerNames`, object | null, required. The owner-name run's latest state, or null.
    - `status`, string, required. running or completed.
    - `scrapeId`, string | null, required. The scrape that delivers the named leads.
    - `targetNames`, integer, required.
    - `namesFound`, integer, required.
    - `reservedCredits`, integer, required.
    - `creditsUsed`, integer | null, required.

## Example response

```json 200
{
  "id": "Vb7nW3xQ9k",
  "title": "TX roofers, mobiles",
  "customTitle": "TX roofers, mobiles",
  "status": "completed",
  "source": "mcp",
  "niches": [
    {
      "id": "roofing_contractor",
      "name": "Roofing Contractor"
    }
  ],
  "areaSummary": {
    "regions": [
      "US:TX"
    ],
    "zipCount": 0
  },
  "filters": {
    "phoneTypeFilter": "mobile",
    "websitePresence": "any",
    "findOwner": false,
    "nicheMatch": false,
    "minGoogleReviews": 0,
    "dedupMode": "cross_niche"
  },
  "targetLeads": 1000,
  "leadsDelivered": 1000,
  "leadsSoFar": null,
  "reservedCredits": 1000,
  "creditsUsed": 1000,
  "reviewsReservedCredits": 0,
  "reviewsScraped": null,
  "emailsFound": null,
  "duplicatesSkipped": 37,
  "stoppedByUser": false,
  "parentId": null,
  "createdAt": "2026-10-03T16:40:02.000Z",
  "startedAt": "2026-10-03T16:40:05.000Z",
  "settledAt": "2026-10-03T17:52:41.000Z",
  "selection": {
    "states": [
      {
        "country": "US",
        "state": "TX"
      }
    ],
    "zips": []
  },
  "origin": null,
  "children": [],
  "reviewsAvailable": 0,
  "upgrades": {
    "emailFind": null,
    "emailVerify": null,
    "ownerNames": null
  }
}
```

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