Billing

List credit history

Read the credit ledger: every purchase, spend, refund and expiry.

GETapi.leadity.io/v1/billing/history

Scope readMCP tool list_credit_history

Answers one page of every movement of the account's balance, newest first, 25 to a page: purchases, scrapes and validations with their refunds, expiries and bonuses. delta is signed: negative left the balance, positive came back to it. A new entry shifts older ones to later pages.

Example request

curl "https://api.leadity.io/v1/billing/history?page=1" \
  -H "Authorization: Bearer $LEADITY_API_KEY"

Example response

{
  "balance": 4820,
  "entries": [
    {
      "id": "Zp4Kq8rT2m",
      "date": "2026-10-03T16:40:02.000Z",
      "kind": "scrape",
      "title": "TX roofers, mobiles",
      "note": "reserve",
      "delta": -1000,
      "scrapeId": "Vb7nW3xQ9k",
      "validationId": null
    }
  ],
  "page": 1,
  "pageCount": 3,
  "total": 61
}

Headers

Authorizationstringrequired

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

Query parameters

pageintegerdefault 1

The page to read, from 1. Default 1.

1 to 10,000.

Response

balanceintegerrequired

The balance now, in credits.

entriesobject[]required

Show child attributes

idstringrequired

The entry's id.

datestringrequired

When the balance moved. An ISO 8601 timestamp in UTC.

kindstringrequired

What moved it: purchase, scrape, validation, refund, dispute, bonus, adjustment or expired. New kinds may appear.

titlestringrequired

The line as the app prints it: the scrape's name, the pack, or what happened.

notestring | nullrequired

A second line when there is one, e.g. what a purchase cost.

deltaintegerrequired

Credits, signed: negative left the balance, positive came back to it.

scrapeIdstring | nullrequired

The scrape this entry belongs to, when it belongs to one.

validationIdstring | nullrequired

The validation run this entry belongs to, when it belongs to one.

pageintegerrequired

pageCountintegerrequired

totalintegerrequired

Entries across every 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.