Skip to main content
A credit is the unit Agentic ID charges in. Each workspace has one wallet. Every credential that acts as the workspace, key or sign-in, draws on that wallet.

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.
Every paid answer reports both numbers:
number
The most the call could have charged.
number
What it charged. Never more than quoted.

What each call charges

“Your workspace contributes” is the contributes setting returned by GET /v1/workspace.

Cap a call with max_credits

integer
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.
number
Credits in the wallet, including any held by calls still running.
number
Credits reserved by calls still running.
number
What a new call can spend: balance minus held.
number
Agentic IDs this workspace has resolved or been delivered.

GET /v1/credits

The balance, what was spent, and the latest movements.
integer
default:"20"
How many recent movements and recent IDs to return. From 0 to 200.
  • spent.today covers the current UTC day.
  • recent lists grants and charges. Holds and releases are not listed.
  • recent_ids lists the latest IDs delivered and what each cost. company is 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, with 402 and the code credits.insufficient. Nothing is charged.
When the wallet holds some credits but fewer than the call could use, the call is not refused. It holds what is available, delivers what that pays for, and stops there. Do not retry a 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 set stopped_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 an Idempotency-Key header on paid calls. The same key and body returns the first answer and is charged once. See Idempotency.