Scrapes

List scrapes

List the account's scrapes, newest first.

GETapi.leadity.io/v1/scrapes

Scope readMCP tool list_scrapes

Lists the account's scrapes, newest first, a page at a time, each with its status, its filters, how many leads it has delivered and what it cost. Page with cursor until nextCursor is null. Call get_scrape for one scrape's full detail.

Example request

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

Example response

{
  "scrapes": [
    {
      "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"
    }
  ],
  "nextCursor": "c2NyYXBlOjgyNDE"
}

Headers

Authorizationstringrequired

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

Query parameters

cursorstring

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

1 to 200 characters.

limitintegerdefault 50

How many scrapes one page holds, 1 to 50. Default 50.

1 to 50.

Response

scrapesobject[]required

Show child attributes

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.

nextCursorstring | nullrequired

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

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