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

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

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.

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

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

## 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/status" \
  -H "Authorization: Bearer $LEADITY_API_KEY"
```

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

print(response.json())
```

## Response

- `id`, 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`.
- `complete`, boolean, required. True once the scrape has settled: nothing more will be delivered or charged.
- `targetLeads`, integer, required.
- `leadsDelivered`, integer | null, required. Set when the scrape settles. Null before.
- `creditsUsed`, integer | null, required. Set when the scrape settles. Null before.
- `stoppedByUser`, boolean, required.
- `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. An ISO 8601 timestamp in UTC, or null.

## Example response

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