Venice Billing

Venice Billing

Read-only endpoints for account-level billing and analytics. usage-analytics is tagged Beta in the spec — its schema/behavior may change.

All three live endpoints require Bearer auth with an ADMIN key — an INFERENCE key gets 401 ("Admin API key required"). They do not accept x402 wallet auth; for wallet balances use venice-x402. A request with no Authorization header at all gets a 402 x402 discovery body rather than a 401 — ignore its payment options and send an ADMIN Bearer key; a bad key gets 401.

GET /billing/usage is gone. Since 2026-09-16 it returns 410 Gone to every request, authenticated or not, with no usage data. The body's error string names the replacement and the parameter renames, and the response carries Deprecation: @1783555200, Sunset: Wed, 16 Sep 2026 00:00:00 GMT, and Link: </api/v1/billing/usage-history>; rel="successor-version", <https://docs.venice.ai/api-reference/endpoint/billing/usage-history>; rel="deprecation"; type="text/html". The route is rate limited to 60 requests/minute per IP (then 429, whose message repeats the migration pointer). Migrate to GET /billing/usage-history: page + limit → pageSize + nextCursor, startDate / endDate → startTimestamp / endTimestamp.

Currency / priority

Each request is charged to a single currency, picked in this order:

1. DIEM — from staked DIEM; the allocation resets every epoch (UTC day).
2. EARNED_CREDITS — USD-denominated earned credits.
3. BUNDLED_CREDITS — USD-denominated credits included with paid Venice subscription plans.
4. USD — prepaid fiat balance.

Prepaid (quoted) charges such as queued jobs and images use the first currency that covers the whole cost. Token-priced requests are billed after they run, to the first currency with a positive balance, which can leave it slightly negative.

Legacy VCU (the old name for DIEM) is no longer a consumable currency; it is rejected by /billing/usage-history's currency filter.

A per-key USD consumption limit covers USD, BUNDLED_CREDITS and EARNED_CREDITS together; a DIEM limit covers DIEM (see venice-api-keys).

GET /billing/balance

curl https://api.venice.ai/api/v1/billing/balance \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

{
  "canConsume": true,
  "consumptionCurrency": "DIEM",
  "balances": { "diem": 90.5, "usd": 25, "bundledCredits": 10, "earnedCredits": null },
  "diemEpochAllocation": 100
}

• canConsume is true when the account's spendable DIEM, earned credits, bundled credits and USD total at least $0.10. It does not account for per-key limits or the account's API tier — the real admission check runs on each inference request. Use GET /api_keys/rate_limits → accessPermitted for a check that includes those.
• consumptionCurrency is the first currency with a positive balance, in the order DIEM, EARNED_CREDITS, BUNDLED_CREDITS, USD, or null. The spec enum also lists VCU, but it is never returned.
• balances.diem is null when the account isn't staking DIEM; otherwise the remaining DIEM this epoch.
• balances.usd, balances.bundledCredits and balances.earnedCredits are null when not positive.
• diemEpochAllocation is the total DIEM for the current epoch — balances.diem / diemEpochAllocation = remaining fraction.

GET /billing/usage-history

Per-request ledger with keyset (cursor) pagination, in ascending timestamp order.

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.

A cursor that is expired, tampered with, or was issued to another user returns 400 ("Invalid or expired cursor; restart from the first page"). Page contents stay stable while new usage is recorded; no result totals are reported.

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"
}

nextCursor is null on the last page.

Fields

• sku — billing line item (model + unit type + format).
• units — for LLMs, millions of tokens (e.g. 0.000227 = 227 tokens).
• pricePerUnitUsd — rate per unit in USD.
• amount — negative for a debit.
• currency — USD, DIEM, BUNDLED_CREDITS, or EARNED_CREDITS.
• inferenceDetails — null for non-inference entries. When present, requestId is the id returned on the original response; promptTokens, completionTokens, and inferenceExecutionTime (ms) are each nullable when not recorded (tokens are null for non-LLM usage).

CSV

Send Accept: text/csv. Columns: timestamp, sku, pricePerUnitUsd, units, amount, currency, notes, inferenceDetails.requestId, inferenceDetails.inferenceExecutionTime, inferenceDetails.promptTokens, inferenceDetails.completionTokens. Content-Disposition is attachment; filename=billing-usage-history-<UTC export stamp>.csv, so each page of a walk downloads under a unique, sort-ordered name. Because CSV has no envelope, the continuation token moves to the x-next-cursor response header, which is absent on the last page.

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-analytics

Aggregated summary for dashboards. Cached 10 minutes per user + period.

curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=7d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

Query parameters (choose one approach)

• lookback=Nd — must match ^[1-9]\d*d$. Default 7d. Values above 90d are clamped to 90 days (the response lookback then reads "90d").
• OR startDate=YYYY-MM-DD and endDate=YYYY-MM-DD (inclusive, UTC days). The range may span at most 90 days and endDate must not be before startDate. Send both: if only one is given it is ignored and lookback applies.