venice-billing

name venice-billing description 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 1 request per minute per user , and accounts created on or after 2026-07-07 are rejected outright with 410 Gone . Every response carries Deprecation: @1783555200 and Link: </api/v1/billing/usage-history>; rel="successor-version" . Write new integrations against GET /billing/usage-history , which returns the same data with keyset pagination. Currency / priority Venice debits from, in order: DIEM — staked credits (reset per epoch). BUNDLED_CREDITS — included in some Pro plans. USD — prepaid fiat balance. ( VCU ) — deprecated legacy DIEM. consumptionCurrency on /billing/balance reports the current currency being consumed. GET /billing/balance curl https://api.venice.ai/api/v1/billing/balance \ -H "Authorization: Bearer $VENICE_API_KEY " { "canConsume" : true , "consumptionCurrency" : "DIEM" , "balances" : { "diem" : 90.5 , "usd" : 25 } , "diemEpochAllocation" : 100 } 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. curl "https://api.venice.ai/api/v1/billing/usage-history?startTimestamp=2026-06-01T00:00:00Z&endTimestamp=2026-07-01T00:00:00Z&pageSize=1000&currency=USD" \ -H "Authorization: Bearer $VENICE_ADMIN_KEY " \ -H "Accept: application/json" Query parameters 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 . Response (JSON) { "data" : [ { "timestamp" : "2026-06-15T19:05:10.504Z" , "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-4007fd29f42b7d3c4107f4345e8d174a" , "promptTokens" : 339 , "completionTokens" : 227 , "inferenceExecutionTime" : 2964 } } ] , "nextCursor" : "AZq3fK9tXhIVDm2j4vN8cQwYt1sB6uEoLxRgPzKaJdHfM5nC7yW0K3w" } 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. Walking the full history let url = ` ${base} /billing/usage-history?startTimestamp= ${start} &endTimestamp= ${end} ` for (;;) { const page = await fetch (url, { headers }). then ( r => r. json ()) handle (page. data ) if (page. nextCursor === null ) break url = ` ${base} /billing/usage-history?cursor= ${ encodeURIComponent (page.nextCursor)} ` } GET /billing/usage (deprecated) Offset-paginated per-request ledger. Kept alive for grandfathered accounts only; see the deprecation warning at the top of this skill before using it. curl "https://api.venice.ai/api/v1/billing/usage?limit=200&page=1&sortOrder=desc&currency=USD&startDate=2026-04-01T00:00:00Z&endDate=2026-04-21T23:59:59Z" \ -H "Authorization: Bearer $VENICE_API_KEY " \ -H "Accept: application/json" Query parameters Param Notes currency USD / VCU / DIEM / BUNDLED_CREDITS . startDate / endDate ISO 8601 datetime. limit 1–500. Default 200. page Default 1. sortOrder asc / desc on createdAt . Default desc . Accept header application/json (default) — paginated JSON. text/csv — downloads billing-usage.csv (sets Content-Disposition ). Response (JSON) { "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 } } Response headers: x-pagination-{limit,page,total,total-pages} . Fields sku — billing line item (model + unit type + format). units — for LLMs, millions of tokens (e.g. 0.000227 = 227 tokens). pricePerUnitUsd — rate; for DIEM, DIEM ≈ USD so this doubles as reference. amount — negative for debit. inferenceDetails — present for inference SKUs; requestId is the id returned on the original /chat/completions response. GET /billing/usage-analytics Aggregated summary for dashboards. Cached 10 minutes. curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=7d" \ -H "Authorization: Bearer $VENICE_API_KEY " Query parameters (choose one approach) lookback=Nd — 7d , 30d , up to 90d . Default 7d . OR startDate=YYYY-MM-DD + endDate=YYYY-MM-DD — both required if either is given. Response (selected keys) { "lookback" : "7d" , "byDate" : [ { "date" : "2026-04-20" , "USD" : 0.5 , "DIEM" : 10.25 } , ... ] , "byModel" : [ { "modelName" : "GLM 5.1" , "unitType" : "tokens" , "modelType" : "LLM" , "totalUsd" : 0.4 , "totalDiem" : 12.5 , "totalUnits" : 50000 , "breakdown" : [ { "type" : "Output" , "usd" : 0.3 , "diem" : 10 , "units" : 35000 } , { "type" : "Input" , "usd" : 0.1 , "diem" : 2.5 , "units" : 15000 } ] } ] , "byModelDaily" : [ { "date" : 1705276800000 , "GLM 5.1" : 5.5 , "Claude Opus 4.7" : 3.2 } ] , "byModelDailyUsd" : [ ... ] , "topModels" : [ "GLM 5.1" , "Claude Opus 4.7" ] , "byKey" : [ { "apiKeyId" : "key_abc123" , "description" : "Production Key" , "totalUsd" : 0.8 , "totalDiem" : 15 , "totalUnits" : 75000 } , { "apiKeyId" : null , "description" : "Web App" , "totalUsd" : 0 , "totalDiem" : 4 , "totalUnits" : 25000 } ] , "byKeyDaily" : [ ... ] , "byKeyDailyUsd" : [ ... ] , "topKeyNames" : [ ... ] } byDate / byModelDaily / byKeyDaily are pre-shaped for time-series charts. topModels / topKeyNames give top-8 names for legend rendering. apiKeyId: null in byKey means the usage originated from Venice's web app. Recipes Abort before calling inference if balance is empty const { canConsume } = await fetch ( ` ${base} /billing/balance` , { headers }). then ( r => r. json ()) if (!canConsume) throw new Error ( 'Venice balance exhausted — top up before continuing' ) Monthly CSV export curl "https://api.venice.ai/api/v1/billing/usage-history?startTimestamp=2026-04-01T00:00:00Z&endTimestamp=2026-05-01T00:00:00Z&pageSize=1000" \ -H "Authorization: Bearer $VENICE_ADMIN_KEY " \ -H "Accept: text/csv" \ -o billing-april.csv Read x-next-cursor off the response and re-request with ?cursor=<token> (and no other parameters) until the header is absent. Top-models chart const a = await fetch ( ` ${base} /billing/usage-analytics?lookback=30d` , { headers }). then ( r => r. json ()) // chart(a.byModelDaily, { series: a.topModels, xField: 'date' }) Errors Code Meaning 400 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