> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agentic-id.icustomer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> What a credit pays for, when it is charged, and how to cap what a call can spend.

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:

```json theme={null}
"cost": { "quoted_credits": 10, "charged_credits": 4 }
```

**cost.quoted\_credits** `number`

The most the call could have charged.

**cost.charged\_credits** `number`

What it charged. Never more than quoted.

## What each call charges

| Call | Charged | Not charged |
| - | - | - |
| [Resolve](https://docs-agentic-id.icustomer.ai/products/resolve.md) | 1 credit per ID returned (`known` or `new`) | `review`, `conflict` and `unresolvable` outcomes. An ID your workspace already holds, while your workspace contributes |
| [Validate](https://docs-agentic-id.icustomer.ai/products/validate.md) | 1 credit per `valid`, `invalid` or `catch-all` verdict | `unknown` and `rejected` verdicts. A domain check |
| [Enrich](https://docs-agentic-id.icustomer.ai/products/enrich.md) | 2 credits per person, plus 5 when a phone is delivered; 1 credit per company | A record with nothing found |
| [Find](https://docs-agentic-id.icustomer.ai/products/find.md) | 2 credits per person delivered | People left out (see `excluded`) |
| [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md) | 1 credit per company, plus 2 credits per person when you ask for contacts | A `count_only` request. A company whose size came from one source only (`"charged": false`) |
| [Lookalike](https://docs-agentic-id.icustomer.ai/products/lookalike.md) | 1 credit per company | A company whose size came from one source only (`"charged": false`) |
| [Feedback](https://docs-agentic-id.icustomer.ai/products/feedback.md) | Nothing | |
| `GET /v1/workspace`, `GET /v1/credits` | Nothing | |
| `GET /v1/facts/{id}`, `GET /v1/ledger/{id}` | Nothing | |

"Your workspace contributes" is the `contributes` setting returned by `GET /v1/workspace`.

## Cap a call with max\_credits

**max\_credits** `integer`

The most this call may charge. A whole number from 0 to 100,000. The call never charges past it.

| Call | `max_credits` |
| - | - |
| Enrich, Find | Required |
| Resolve, Validate, Discover, Lookalike | Optional |

When a call reaches its cap it stops and returns what it delivered. It does not fail:

| Call | What you see at the cap |
| - | - |
| Validate | Addresses not reached come back with `"verdict": "unknown"` and `"reason": "credit_cap"` |
| Resolve | The ID is withheld and `reason` says the cap was reached. Nothing is charged for it |
| Discover, Lookalike | Fewer companies than asked. The summary says the call stopped at the cap. Discover also sets `fewer_than_asked` |

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

```bash Workspace theme={null}
curl -s "https://YOUR_AGENTIC_ID_HOST/v1/workspace" \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY"
```

```bash Credits theme={null}
curl -s "https://YOUR_AGENTIC_ID_HOST/v1/credits?limit=20" \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY"
```

### GET /v1/workspace

Who the caller is and what it can spend.

```json theme={null}
{
  "workspace_id": "ws_acme",
  "signed_in_as": "api_key",
  "scopes": [],
  "credits": { "balance": 480, "held": 10, "available": 470 },
  "contributes": true,
  "allowed_purposes": ["b2b_outbound", "ad_audience", "own_customer_enrichment", "fraud_check"],
  "region": "us",
  "ids_held": 126
}
```

**credits.balance** `number`

Credits in the wallet, including any held by calls still running.

**credits.held** `number`

Credits reserved by calls still running.

**credits.available** `number`

What a new call can spend: balance minus held.

**ids\_held** `number`

Agentic IDs this workspace has resolved or been delivered.

### GET /v1/credits

The balance, what was spent, and the latest movements.

**limit** `integer` (default: 20)

How many recent movements and recent IDs to return. From 0 to 200.

```json theme={null}
{
  "workspace_id": "ws_acme",
  "credits": { "balance": 480, "held": 0, "available": 480 },
  "spent": {
    "today": 6,
    "last_30_days": 20,
    "by_tool": [
      { "tool": "find", "credits": 12, "calls": 3 },
      { "tool": "resolve", "credits": 8, "calls": 8 }
    ]
  },
  "recent": [
    { "at": "2026-11-13T10:42:07.000Z", "kind": "charge", "credits": 4, "tool": "find" },
    { "at": "2026-11-01T09:00:00.000Z", "kind": "grant", "credits": 500, "note": "starting balance" }
  ],
  "recent_ids": [
    { "at": "2026-11-13T10:41:55.000Z", "id": "ic-4kQ9xT2mB7nLp0Zr8VwYc3", "kind": "company", "company": "acme.example", "tool": "resolve", "credits": 1 }
  ]
}
```

* `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.

```json theme={null}
{
  "type": "https://docs.agentic-id.icustomer.ai/errors/credits.insufficient",
  "title": "Not enough credits",
  "status": 402,
  "code": "credits.insufficient",
  "detail": "Not enough credits for this request: 0 available. Nothing was charged. Add credits, or ask for less.",
  "available": 0,
  "request_id": "0d1c7a0e-52f3-4b0a-8f7e-3b6a1c9d2e44"
}
```

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`:

| `stopped_early` | Meaning | What to do |
| - | - | - |
| `source_budget` | Agentic ID's daily budget for paid sources is used up | Try again after midnight UTC |
| `request_source_budget` | This one request reached the limit on paid-source spend per request | Ask again for the rest. A new request starts with a fresh limit |
| `source_call_limit` | The remaining paid source costs more for one lookup than Agentic ID allows | Asking again will not change it. Tell your Agentic ID contact |

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:

| `reason` | Meaning |
| - | - |
| `paid_source_budget_used_up_today` | The daily budget for paid sources is used up |
| `paid_source_limit_for_this_request` | This request reached its paid-source limit |
| `source_price_above_call_limit` | The check costs more than Agentic ID allows for one lookup |
| `credit_cap` | Your own `max_credits` was reached before this address |

## 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](https://docs-agentic-id.icustomer.ai/idempotency.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.