Spending credits

Spending credits safely

Price first, cap every purchase with maxCredits, and retry with the same Idempotency-Key.

Some operations take credits from the account's balance. Each one follows the same four rules, on the HTTP API and the MCP server alike, so code that handles one handles them all.

The four rules

Price it first, for free
Every spending operation has a free operation that prices it, named in the first sentences of its description. An order is priced by estimate_scrape, a validation list by preview_validation, and every upgrade to a finished scrape by list_scrape_offers.
Cap it with maxCredits
Every spending call requires maxCredits, the most it may take. It is a ceiling, never a price: at or under it you are charged Leadity's own number. If the price is above it, nothing is charged and the call answers quote_exceeded.
Make it retry-safe
Every spending call requires an Idempotency-Key, so a retry replays the first answer instead of buying twice, and the same key on a different request is refused with idempotency_conflict. See Idempotency.
Use a key with the spend scope
A key without spend can price everything and buy nothing. Give spend only to the integration that places orders. See API keys and scopes.

What takes credits

Spends credits	Price it first with	What it buys
create_scrape	estimate_scrape	Order a scrape: find businesses live on Google Maps and deliver them as leads.
purchase_residuals	list_scrape_offers	Buy one cell of a finished scrape's held-back businesses.
purchase_phone_reveal	list_scrape_offers	Buy the phone line types of a finished scrape's delivered leads.
purchase_email_find	list_scrape_offers	Buy email addresses for a finished scrape's delivered leads.
purchase_email_verify	list_scrape_offers	Buy deliverability verdicts for a finished scrape's email addresses.
purchase_owner_names	list_scrape_offers	Buy owner names for a finished scrape's delivered leads.
create_validation	preview_validation	Validate a list of phone numbers or email addresses you supply.

How an order is charged

create_scrape holds the price of the whole order when it is placed: targetLeads at the per-lead rate, ceil(targetLeads x leadRateMilli / 1000) credits, plus, when review scraping is ordered, the reviews ceiling, ceil(targetLeads x maxReviews x review) credits with review the per-review rate get_pricing names. Each part is rounded up to a whole credit on its own, so maxCredits must cover the two together. estimate_scrape answers the per-lead rate and never the reviews part. The scrape then charges each lead it delivers. When it settles, whatever was not delivered comes back to the balance, so a run that delivers 600 of the 1,000 leads ordered is charged for 600.

Two things are never charged: a business your account already holds, in any niche, and a lead the filters refused. Stopping a scrape with stop_scrape keeps what it delivered and refunds the rest.

The upgrades do not all charge alike. Two take their price outright, because what they buy is counted before the call: purchase_residuals buys a cell of held-back businesses and purchase_phone_reveal the line types of the numbers already delivered, and neither refunds anything. The other three, purchase_email_find, purchase_email_verify and purchase_owner_names, hold the price of the whole target up front and refund the part that found nothing when the run ends, and so does create_validation for its list. Credits are whole numbers, so a price per item in fractions of a credit is rounded up once over the whole quantity, never per item: 21 owner names at 2.5 credits each hold 53, and 1,152 phone numbers at 0.2 hold 231.

Pricing an order is free and safe to repeat. An agent should always show a person the price from estimate_scrape and pass a maxCredits no higher than what they agreed to.

When the balance is short

A purchase the balance cannot cover is refused with 402 insufficient_credits before anything is taken. To add credits, list_plans lists the plans and packs, and create_checkout answers a checkout link for a person to open and pay at. An account with a monthly plan can also top it up: create_top_up_checkout answers a link for any amount list_plans names under topUp, at the plan's own rate. No key can pay for anything itself: the credits land when the person pays.