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

# List validations

> List the account's validation runs, newest first.

Lists the account's validation runs, newest first, a page at a time, each with its status, its counts and what it cost. Page with cursor until nextCursor is null.

`GET https://api.leadity.io/v1/validations`

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

## Headers

- `Authorization`, string, required. Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

## Query parameters

- `cursor`, string, optional. The nextCursor of the previous page of runs. Leave it out for the first page. 1 to 200 characters.
- `limit`, integer, optional. How many runs one page holds, 1 to 50. Default 50. 1 to 50. Default `50`.

## Example request

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

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

print(response.json())
```

## Response

- `validations`, object[], required.
  - `id`, string, required. The run's id.
  - `title`, string, required. The run's name.
  - `kind`, string, required. phone to classify line types, email to check deliverability. One of: `phone`, `email`.
  - `region`, string, required. The region a phone list was read under. US on an email run. One of: `US`, `GB`, `AU`.
  - `status`, string, required. queued and running are live; completed, failed and canceled are final. A failed run bills only what was answered. One of: `queued`, `running`, `completed`, `failed`, `canceled`.
  - `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`.
  - `submitted`, integer, required. Lines or items submitted.
  - `rejected`, integer, required. Items the parser refused as not a phone number or address.
  - `duplicates`, integer, required. Repeats collapsed to one.
  - `total`, integer, required. Items checked: submitted minus rejected and duplicates.
  - `processed`, integer, required. Items answered so far.
  - `billable`, integer, required. Answers that cost credits so far. An answer that tells nothing costs nothing.
  - `reservedCredits`, integer, required. Credits held when the run was created.
  - `creditsUsed`, integer | null, required. Credits kept, set when the run settles; the rest was refunded. Null before.
  - `creditsPerItem`, number, required. The price of one billable answer.
  - `createdAt`, string, required. When the run was created. An ISO 8601 timestamp in UTC.
  - `startedAt`, string | null, required. When the run started. An ISO 8601 timestamp in UTC, or null.
  - `settledAt`, string | null, required. When the run settled. An ISO 8601 timestamp in UTC, or null.
- `nextCursor`, string | null, required. Pass it as cursor to read the next page. Null on the last page.

## Example response

```json 200
{
  "validations": [
    {
      "id": "Wq5nB8kT3m",
      "title": "Phone validation | Oct 4, 2:12 PM",
      "kind": "phone",
      "region": "US",
      "status": "completed",
      "source": "api",
      "submitted": 1204,
      "rejected": 12,
      "duplicates": 40,
      "total": 1152,
      "processed": 1152,
      "billable": 1081,
      "reservedCredits": 231,
      "creditsUsed": 217,
      "creditsPerItem": 0.2,
      "createdAt": "2026-10-04T14:12:09.000Z",
      "startedAt": "2026-10-04T14:12:10.000Z",
      "settledAt": "2026-10-04T14:13:02.000Z"
    }
  ],
  "nextCursor": 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). |
| `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. |