Credits and usage

Usage is paid for out of a credit balance held per account. This page covers how a single call moves that balance and which endpoints report on it.

Reserve, then settle

A generation is charged in two steps, not one.

Reserve. Before the request goes to a provider, the gateway works out an upper bound on what the call could cost and places a hold for that amount. The hold is not a charge — nothing is spent yet — but the money is no longer available to anything else. If the hold cannot be placed, the request is refused with a 402 and no provider is ever contacted.

Settle. When the generation finishes, the actual cost is computed from the tokens the call really used, written to the ledger as a charge, and the hold is released. The charge is almost always smaller than the hold, because the hold has to assume a completion that runs to its limit and most do not.

Two consequences follow, and both are visible to you:

• In-flight work reduces what you can spend. The figure a new reservation is checked against is available − held, not available. An account with credit fully committed to running generations will refuse a new one.
• The ledger is append-only. A correction is a new, opposite entry, never an edit. Nothing rewrites the history of what an account was charged.

Both steps are idempotent at the database level. A retried reservation for the same generation returns the existing hold instead of doubling it, and a second settlement of the same generation fails rather than charging twice.

The account balance

GET /credits reports the account's lifetime totals. It needs a management key — an inference key gets a 403 here.

curl -s "https://api.impossiblecarrot.cc/api/v1/credits" -H "Authorization: Bearer $CP_MGMT_KEY"

{"data":{"total_credits":20,"total_usage":0.0775431}}

Exactly two members, and both are lifetime figures in US dollars:

• total_credits — everything ever added to the account.
• total_usage — everything ever spent.

The remaining balance is the difference — $19.92 on the account above. This response deliberately does not carry the held amount or the spendable figure; it is a stable, minimal shape, and the numbers on it are cumulative rather than current.

What one key has spent

GET /credits is account-wide. To see one credential's own spend and its cap, use GET /key, which works with either key class and reports on whichever one authenticated. The usage, usage_daily, usage_weekly, usage_monthly, limit, limit_reset and limit_remaining fields are documented on Authentication.

A key can carry its own spend cap, enforced in a named window. That cap is checked at reservation time alongside the account balance, so a key can be refused with a 402 while the account itself still has credit.

What one generation cost

Every completion returns a generation id, and GET /generation reports the billing and telemetry record for it. This is the record for the request on the Quickstart page:

curl -s "https://api.impossiblecarrot.cc/api/v1/generation?id=gen-1786757875-5np6jh6ix9nh6n0h" \
  -H "Authorization: Bearer $CP_API_KEY"

{
  "data": {
    "id": "gen-1786757875-5np6jh6ix9nh6n0h",
    "request_id": "req-3p",
    "created_at": "2026-08-15T01:37:55.786Z",
    "model": "impCC/DeepSeek-V4-Flash-0731",
    "total_cost": 0.0000032,
    "usage": 0.0000032,
    "is_byok": false,
    "provider_name": "Stealth",
    "router": "direct",
    "api_type": "completions",
    "streamed": false,
    "cancelled": false,
    "finish_reason": "stop",
    "native_finish_reason": "stop",
    "latency": 267,
    "tokens_prompt": 12,
    "tokens_completion": 5,
    "native_tokens_prompt": 12,
    "native_tokens_completion": 5,
    "cache_discount": null,
    "upstream_inference_cost": null,
    "provider_responses": null
  }
}

The response carries more fields than are shown here; the ones above are the billing-relevant set. usage and total_cost are the same figure under two names.

That number is checkable, which is the point of publishing per-token prices as exact strings. The model bills $0.0000001 per prompt token and $0.0000004 per completion token:

12 prompt     × 0.0000001 = 0.0000012
 5 completion × 0.0000004 = 0.0000020
                            ---------
                            0.0000032

latency is in milliseconds. Fields that report on something this deployment does not do — cache discounts, per-attempt provider payloads — are null rather than zero, because "there was none" and "we hold no record" are different claims and only one of them is true here.

A generation id belonging to another account is reported as absent, not forbidden. A 404 here does not confirm that the id exists somewhere else.

Running out

A reservation that cannot be covered fails with 402 and the request stops before it reaches a provider. Two distinct situations produce it: the account's spendable balance cannot cover the hold, or the calling key's own spend cap is exhausted for its window. The 402 body distinguishes them in its metadata.

A balance of exactly zero is not the same as a negative one. Zero is a normal state for an account that has never funded itself, and it does not by itself block a request that costs nothing.

Adding credit

Not documented here. Whether an account can be funded through the API, and how, is not something these pages should tell you before the surface is settled — so this section will describe the funding flow when there is one to describe, and says nothing in the meantime. To add credit to an account today, talk to whoever operates the deployment.