Scrapes

Get scrape status

Poll a scrape cheaply: its status, and whether it is complete.

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

Scope readMCP tool get_scrape_status

Answers a scrape's status from its own record and nothing else, so it is the cheap way to watch a running scrape. Poll it every 30 to 60 seconds, never faster: a scrape takes minutes to hours, and nothing is pushed when it ends. complete turns true once the scrape has settled; leadsDelivered and creditsUsed are set then. For the live count while it runs, call get_scrape.

Example request

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

Example response

{
  "id": "Vb7nW3xQ9k",
  "status": "running",
  "complete": false,
  "targetLeads": 1000,
  "leadsDelivered": null,
  "creditsUsed": null,
  "stoppedByUser": false,
  "startedAt": "2026-10-03T16:40:05.000Z",
  "settledAt": 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

statusstringrequired

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

One ofreservingqueuedrunningstoppingsettlingcompleted

completebooleanrequired

True once the scrape has settled: nothing more will be delivered or charged.

targetLeadsintegerrequired

leadsDeliveredinteger | nullrequired

Set when the scrape settles. Null before.

creditsUsedinteger | nullrequired

Set when the scrape settles. Null before.

stoppedByUserbooleanrequired

startedAtstring | nullrequired

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

settledAtstring | nullrequired

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

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.