Validations

List validations

List the account's validation runs, newest first.

GETapi.leadity.io/v1/validations

Scope readMCP tool list_validations

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.

Example request

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

Example response

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

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 runs. Leave it out for the first page.

1 to 200 characters.

limitintegerdefault 50

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

1 to 50.

Response

validationsobject[]required

Show child attributes

idstringrequired

The run's id.

titlestringrequired

The run's name.

kindstringrequired

phone to classify line types, email to check deliverability.

One ofphoneemail

regionstringrequired

The region a phone list was read under. US on an email run.

One ofUSGBAU

statusstringrequired

queued and running are live; completed, failed and canceled are final. A failed run bills only what was answered.

One ofqueuedrunningcompletedfailedcanceled

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

submittedintegerrequired

Lines or items submitted.

rejectedintegerrequired

Items the parser refused as not a phone number or address.

duplicatesintegerrequired

Repeats collapsed to one.

totalintegerrequired

Items checked: submitted minus rejected and duplicates.

processedintegerrequired

Items answered so far.

billableintegerrequired

Answers that cost credits so far. An answer that tells nothing costs nothing.

reservedCreditsintegerrequired

Credits held when the run was created.

creditsUsedinteger | nullrequired

Credits kept, set when the run settles; the rest was refunded. Null before.

creditsPerItemnumberrequired

The price of one billable answer.

createdAtstringrequired

When the run was created. An ISO 8601 timestamp in UTC.

startedAtstring | nullrequired

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

settledAtstring | nullrequired

When the run settled. 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.