# Credits & billing

Live valuations are paid for with prepaid credits. This page explains what uses a credit, how a credit is reserved and released, where credits come from, and how to cap spending per key.

## What uses a credit

| Request | Credits |
| --- | --- |
| Live valuation with `status: "valued"` | **1**, including any VIN or plate lookup it made |
| [Comparable listings](/docs/valuations#comparable-listings) (`options.include: ["comparables"]`) returned with a `valued` live valuation (`comparables.status` `included`) | **+1** |
| Comparables requested but `none_found` or `unavailable` (Denmark, a timeout) | +0 |
| Live [normalization](/docs/reference/vehicles) (`POST /v1/vehicles/normalize`) with `status: "normalized"` | **1**, plus 1 when photos are used (below) |
| [Trade-in price](/docs/valuations#trade-in-price) (`options.include: ["trade_in_price"]`) returned with a `valued` live valuation (`trade_in_price.status` `included`) | **+1** |
| Trade-in price requested but `unavailable` (outside its twelve markets, or a failure) | +0 |
| [Link to similar cars](/docs/valuations#link-to-similar-cars) (`options.include: ["similar_cars_link"]`) | 0 |
| Photos (`images`) on a `valued` live valuation or a `normalized` live normalization, when a value in `identification.fields` was read from them | **+1** per request, however many photos |
| Photos that were skipped or added nothing (`image_skipped` for every photo, or an `images_not_used` warning) | +0 |
| Live [selling-time forecast](/docs/selling-time) with `status: "valued"` | **2**: the valuation (`base`) and the forecast (`selling_time`), plus 1 when requested comparables are returned |
| Live [market & demand](/docs/reference/market) request (`POST /v1/market`) with `status: "measured"` | **1** |
| Market & demand request that is `partial` or `insufficient_data` | 0 |
| Live valuation, normalization or selling-time forecast that is `refused` or `failed` | 0 |
| Any test-key valuation, selling-time forecast, market & demand request or normalization | 0 |
| Idempotent replay of an earlier valuation, forecast or normalization | 0 (the original is charged once) |
| Requests rejected before they start (validation, limits, authentication) | 0 |
| Live [vehicle lookup](/docs/reference/vehicles) (VIN, HSN/TSN or registration plate) that returns vehicle data (`resolved`, `suggested` or `ambiguous`) | **1** |
| Live vehicle lookup with `no_match`, or one that fails | 0 |
| Any test-key vehicle lookup | 0 |
| Catalogue, account and `GET /v1/valuations/{id}` | 0 |

The same rules apply over REST, MCP (API key or OAuth) and the console playground. OAuth-connected agents always run live valuations, so they use credits on success.

Every POST response tells you what happened in `usage`:

```json
{
  "usage": {
    "billable": true,
    "credits_used": 2,
    "original_credits_used": 2,
    "charges": { "base": 1, "comparables": 1 },
    "credits_remaining": 28,
    "cache_hit": false,
    "idempotent_replay": false,
    "mode": "live"
  }
}
```

`credits_used` is what this call cost; `original_credits_used` is what the original valuation cost, which matters on a replay (where `credits_used` is always `0`). `charges` says what the original credits paid for: `base` for the request itself and one entry per add-on: `comparables`, `trade_in_price`, `images` or `selling_time`. It is empty when nothing was charged.

## How a live valuation is charged

1. **Reserve.** When a live valuation starts, its credits are reserved from your workspace's balance: one for the valuation, plus one for each add-on requested: comparables, a trade-in price, and photos when `images` are sent. If the balance cannot cover all of them, the request is rejected with `402` [`insufficient_credits`](/docs/errors#insufficient_credits) before anything runs; it is never run without the add-on. The whole reservation comes from a single credit grant.
2. **Capture or release.** A `valued` result captures the valuation's credit, and an add-on's credit only when the result delivers it (comparables or a trade-in price with `status: "included"`, photos that a value in `identification.fields` was read from); an add-on that delivered nothing is released. A refusal or failure releases everything back to your balance.
3. **Recover.** If a process dies mid-request, a background job reconciles the reservation with the recorded outcome, so a credit is never captured for a result you did not get.

Requests rejected for rate or concurrency limits never reach step 1, so they never touch your balance.

Credits are taken from the grant that expires first, then from grants without an expiry date.

## Where credits come from

- **Signup credits.** Each person receives **30 credits once**, after verifying their email address. They go to the workspace they create or belong to at that moment, and are not granted again for further workspaces.
- **Packages.** For more credits, [contact sales](/contact-sales) or choose **Request a package** under **Billing**. Packages are added to your workspace by AutoUncle; there are no automatic card charges and no payment details are stored in the console.
- **Adjustments.** AutoUncle can add manual grants, for example for a pilot.

The **Billing** page lists every credit grant with its source, amount, remaining credits, expiry and date added, plus your available credits and the credits used this month. `GET /v1/account` returns the current balance as `credits_remaining`, so your systems can check it before a large run.

## Cap spending per key

Give each live key a **monthly credit limit** when you create it under **API keys**. Once a key has used that many credits in the current calendar month, its live valuations are refused with `402` [`key_spend_limit_reached`](/docs/errors#key_spend_limit_reached), while other keys keep working. The count restarts at the beginning of each month.

A key limit only caps spending; it does not grant credits. The workspace balance still has to cover every valuation.

Use limits to:

- keep a staging or experimental live key from spending your whole balance;
- give an agent or an automation a hard budget;
- split a package between teams or systems.

## Who can see billing

All workspace roles can see **Billing** and **Usage**. Owners and admins manage keys, limits and members; developers manage their own keys; viewers have read-only access. See [authentication & keys](/docs/authentication#team-roles).

## Track usage

- **Usage** in the console shows requests and credits per day, week or month, per key, and exports up to 10,000 requests as CSV.
- **Request logs** list individual requests with their status and request ID.
- Each `valued` live result has `usage.billable: true`. Summing that over your own records should match the console.

## Handling credit errors in code

| Code | HTTP | What to do |
| --- | --- | --- |
| [`insufficient_credits`](/docs/errors#insufficient_credits) | 402 | Stop sending live valuations. Alert a workspace owner to request a package. Test keys keep working. |
| [`key_spend_limit_reached`](/docs/errors#key_spend_limit_reached) | 402 | Stop using this key until next month, or ask an owner or admin to raise its limit. |

Neither is retryable: retrying the same request will fail the same way until the balance or limit changes. In a batch, stop on the first one rather than letting every remaining row fail. See [batch & bulk valuations](/docs/guides/batch-valuations#credits-in-a-batch).

## Next steps

- [Test with test keys](/docs/guides/testing) to build without spending credits.
- [Safety & spend control](/docs/mcp/safety) for agents.
- [Production checklist](/docs/production-checklist).