Scrapes

Get scrape

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

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

Scope readMCP tool get_scrape

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.

Example request

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

Example response

{
  "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
  }
}

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

Response

idstringrequired

The scrape's id.

titlestringrequired

The scrape's name as the app shows it: the customer's own, or one derived from its niches and areas.

customTitlestring | nullrequired

The name the customer gave it, or null when the title is derived.

statusstringrequired

reserving, queued and running are live; stopping and settling are finishing; completed is final.

One ofreservingqueuedrunningstoppingsettlingcompleted

sourcestringrequired

Where this was started: dashboard (the Leadity app), api (an API key), mcp (an MCP key), stress or import (Leadity's own tools).

One ofdashboardapimcpstressimport

nichesobject[]required

The niches ordered.

Show child attributes

idstringrequired

The niche id, Google's own category slug.

namestringrequired

The niche's name.

areaSummaryobjectrequired

Where the scrape searched, in brief. get_scrape carries the full selection.

Show child attributes

regionsstring[]required

Every region the selection touches, as COUNTRY:REGION, e.g. US:TX.

zipCountintegerrequired

How many single ZIP or postal codes the selection names.

filtersobjectrequired

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.

targetLeadsintegerrequired

The most leads the order delivers.

leadsDeliveredinteger | nullrequired

Leads delivered, set when the scrape settles. Null before.

leadsSoFarinteger | nullrequired

Leads delivered so far while the scrape is live. Null once it has settled, when leadsDelivered holds the count.

reservedCreditsintegerrequired

Credits held when the order was placed.

creditsUsedinteger | nullrequired

Credits the scrape kept, set when it settles; the rest of the hold was refunded. Null before.

reviewsReservedCreditsintegerrequired

The part of the hold set aside for review scraping. 0 when none was ordered.

reviewsScrapedinteger | nullrequired

Google reviews walked, set when the scrape settles. Null when none were ordered.

emailsFoundinteger | nullrequired

Email addresses found by the email filter, set when the scrape settles.

duplicatesSkippedinteger | nullrequired

Businesses the account already held, in any niche, that this scrape skipped and never charged. Null before it settles.

stoppedByUserbooleanrequired

True when the customer stopped the scrape before it filled.

parentIdstring | nullrequired

For a scrape bought out of another one (held-back leads, an owner-name run), the scrape it came from. Null otherwise.

createdAtstringrequired

When the order was placed. An ISO 8601 timestamp in UTC.

startedAtstring | nullrequired

When the scrape started running. An ISO 8601 timestamp in UTC, or null.

settledAtstring | nullrequired

When the scrape settled and refunded what it did not use. An ISO 8601 timestamp in UTC, or null.

selectionobjectrequired

The areas ordered, in the shape create_scrape takes, so the scrape can be ordered again.

Show child attributes

statesobject[]required

Whole regions.

Show child attributes

countrystringrequired

statestringrequired

zipsobject[]required

Single ZIP or postal codes.

Show child attributes

countrystringrequired

statestring

codestringrequired

originstring | nullrequired

For a scrape bought out of another: residual for held-back leads, enrichment for an owner-name run. Null for an order.

One ofresidualenrichment

childrenobject[]required

The scrapes bought out of this one, oldest first.

Show child attributes

idstringrequired

titlestringrequired

statusstringrequired

reserving, queued and running are live; stopping and settling are finishing; completed is final.

One ofreservingqueuedrunningstoppingsettlingcompleted

leadsDeliveredinteger | nullrequired

creditsUsedinteger | nullrequired

createdAtstringrequired

When it was bought. An ISO 8601 timestamp in UTC.

reviewsAvailableintegerrequired

Google reviews held so far. download_reviews serves them.

upgradesobjectrequired

Upgrades bought on this scrape.

Show child attributes

emailFindobject | nullrequired

The email-find upgrade's latest run, or null.

Show child attributes

statusstringrequired

One ofrunningcompleted

poolintegerrequired

What the run could draw from when it was bought.

targetintegerrequired

The results ordered.

resultsintegerrequired

Results so far: addresses found, or billable verdicts.

reservedCreditsintegerrequired

Credits held when it was bought.

creditsUsedinteger | nullrequired

Credits it kept, once completed. Null while running.

emailVerifyobject | nullrequired

The email-verify upgrade's latest run, or null.

Show child attributes

statusstringrequired

One ofrunningcompleted

poolintegerrequired

What the run could draw from when it was bought.

targetintegerrequired

The results ordered.

resultsintegerrequired

Results so far: addresses found, or billable verdicts.

reservedCreditsintegerrequired

Credits held when it was bought.

creditsUsedinteger | nullrequired

Credits it kept, once completed. Null while running.

ownerNamesobject | nullrequired

The owner-name run's latest state, or null.

Show child attributes

statusstringrequired

running or completed.

scrapeIdstring | nullrequired

The scrape that delivers the named leads.

targetNamesintegerrequired

namesFoundintegerrequired

reservedCreditsintegerrequired

creditsUsedinteger | nullrequired

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.