When credits are charged
A paid call moves credits in three steps.1
Hold
Before any work starts, the call reserves the most it could charge: what you asked for at the rates below, capped by
max_credits. Held credits cannot be spent by another call.2
Charge on delivery
Each result is charged as it is delivered. A result that is not delivered is not charged.
3
Release
When the call ends, the part of the hold that was not charged goes back to the wallet.
What each call charges
“Your workspace contributes” is the
contributes setting returned by GET /v1/workspace.
Cap a call with max_credits
The most this call may charge. A whole number from 0 to 100,000. The call never charges past it.
When a call reaches its cap it stops and returns what it delivered. It does not fail:
To learn the size of a search before paying for it, send Discover with
"count_only": true. It delivers nothing and charges nothing.
Check your balance
GET /v1/workspace
Who the caller is and what it can spend.GET /v1/credits
The balance, what was spent, and the latest movements.spent.todaycovers the current UTC day.recentlists grants and charges. Holds and releases are not listed.recent_idslists the latest IDs delivered and what each cost.companyis set for a company and never for a person.
When the wallet is empty
A paid call with nothing available is refused before any work, with402 and the code credits.insufficient. Nothing is charged.
credits.insufficient error. To add credits, ask your Agentic ID contact.
When a search stops early
Agentic ID keeps its own budget for paid sources. When a search stops at one of those limits, you are charged only for what was delivered, and the answer says which limit it was. Find and Discover setstopped_early, and repeat the reason in summary:
Discover also sets
fewer_than_asked with the reason in words. Lookalike gives the reason in summary.
Validate reports the same limits per address, as an unknown verdict that is not charged:
Retry without paying twice
Send anIdempotency-Key header on paid calls. The same key and body returns the first answer and is charged once. See Idempotency.
