Venice billing and usage analytics - GET /billing/balance, GET /billing/usage-history (keyset-paginated per-request ledger, JSON or CSV), GET /billing/usage (deprecated predecessor), and GET /billing/usage-analytics (aggregated by date/model/key). Covers the DIEM/USD/BUNDLED_CREDITS consumption priority and building dashboards. (Beta)
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Venice billing and usage analytics - GET /billing/balance, GET /billing/usage-history (keyset-paginated per-request ledger, JSON or CSV), GET /billing/usage (deprecated predecessor), and GET /billing/usage-analytics (aggregated by date/model/key). Covers the DIEM/USD/BUNDLED_CREDITS consumption priority and building dashboards. (Beta)
Venice Billing
Four read-only endpoints for account-level billing and analytics. All are under a Beta tag — schema/behavior may change.
Endpoint
Purpose
GET /billing/balance
Current canConsume flag, remaining DIEM & USD, epoch allocation.
GET /billing/usage-history
Per-request ledger with keyset pagination. JSON or CSV. Use this one.
GET /billing/usage
Deprecated offset-paginated ledger. See the warning below.
GET /billing/usage-analytics
Aggregated breakdowns: by date, model, API key.
All require Bearer auth (not x402 — for wallet balances, use venice-x402). GET /billing/balance, GET /billing/usage-history, and GET /billing/usage require an ADMIN key — an INFERENCE key gets 401. GET /billing/usage-analytics works on any authenticated key (scoped to the account behind the key).
GET /billing/usage is deprecated and mostly closed. It is rate limited to
, and accounts created on or after
are rejected outright with . Every response carries
and
. Write new
integrations against , which returns the same data
with keyset pagination.
canConsume: false means both DIEM and USD buckets are empty on this endpoint — canConsume here is hasPositiveDiemBalance || usdBalance > 0 and does not factor in bundled credits (which are consulted during the actual request in getConsumableBalanceForRequest).
consumptionCurrency is "DIEM", "USD", or null (when neither applies).
balances.diem is null if not staking.
diemEpochAllocation is the ceiling for the current epoch — balances.diem / diemEpochAllocation = remaining fraction.
GET /billing/usage-history
Per-request ledger with keyset (cursor) pagination. This is the supported way to
walk billing history.
A request is either a filtered first page or a bare continuation. Sending
cursor alongside any filter is a 400, and so is any unknown parameter — the
validator is strict rather than lenient.
Param
Notes
startTimestamp
Inclusive lower bound, ISO 8601 UTC with a Z suffix. First page only.
endTimestamp
Exclusive upper bound, ISO 8601 UTC. Must be later than startTimestamp. Consecutive windows that share a boundary walk the history with no gaps and no overlaps.
currency
USD / DIEM / BUNDLED_CREDITS.
pageSize
10–1000. Default 1000.
cursor
Opaque continuation token from a previous nextCursor. Carries the filters of the walk it continues, so send it alone.
Entries come back in ascending timestamp order. nextCursor is null on the
last page. Set Accept: text/csv for CSV, in which case Content-Disposition
stamps the export time into the filename (each page of a walk downloads under a
unique, sort-ordered name) and nextCursor moves to the x-next-cursor
response header.
Entry fields match /billing/usage (see below), with inferenceDetails
sub-fields nullable when a count or timing was not recorded.
{"warningMessage":"DIEM (formerly VCU) has been renamed...","data":[{"timestamp":"2026-04-20T12:34:56Z","sku":"zai-org-glm-5-1-llm-output-mtoken","units":0.000227,"pricePerUnitUsd":2.8,"amount":-0.06356,"currency":"DIEM","notes":"API Inference","inferenceDetails":{"requestId":"chatcmpl-...","promptTokens":339,"completionTokens":227,"inferenceExecutionTime":2964}}],"pagination":{"limit":200,"page":1,"total":1000,"totalPages":5}}
Bad params (startDate without endDate, calendar range > 90 days). On /billing/usage-history: a cursor sent with any filter, an unknown parameter, or endTimestamp not later than startTimestamp. lookback=100d is silently clamped to 90 days rather than rejected.
401
Auth failed, or INFERENCE key used on /billing/balance, /billing/usage-history, or /billing/usage (ADMIN required).
410
/billing/usage only — the account was created on or after 2026-07-07 and must use /billing/usage-history.
429
/billing/usage only — the deprecated 1 request/minute cap.
500
Internal error.
504
Analytics query timed out — shorten lookback or date range.
Gotchas
This is Beta — field names may shift. Validate against swagger.yaml periodically.
Don't build anything new on /billing/usage. One request per minute is not a pagination budget, and new accounts can't call it at all.
/billing/usage-history takes startTimestamp / endTimestamp / pageSize; /billing/usage takes startDate / endDate / limit / page. The parameter names do not carry over when you migrate.
/billing/usage-history accepts USD, DIEM, and BUNDLED_CREDITS for currency. Legacy VCU is only on /billing/usage.
currency values on /billing/usage include legacy VCU — use DIEM instead in new code.
inferenceDetails is null for non-inference SKUs (e.g. subscription charges).
The analytics endpoint is cached 10 min — sudden spikes lag in the dashboard by that window.
byModelDaily.date is a Unix milliseconds integer; byDate.date is a YYYY-MM-DD string. Don't mix them.
Usage entries from the Venice web app have apiKeyId: null — don't drop them when reconciling.
For x402 (wallet) balance, don't use this endpoint — use GET /x402/balance/{walletAddress}.
