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

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:

{
  "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 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 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, 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.

#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

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.

#Next steps

• Test with test keys to build without spending credits.
• Safety & spend control for agents.
• Production checklist.