/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), and GET /billing/usage-analytics (aggregated by date/model/key). All require an ADMIN key. GET /billing/usage was sunset on 2026-09-16 and now always returns 410. Covers the DIEM/EARNED_CREDITS/BUNDLED_CREDITS/USD consumption priority and building dashboards. (Beta)

Venice Billing

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

| Endpoint | Purpose | |---|---| | `GET /billing/balance` | Current `canConsume` flag, remaining DIEM, earned credits, bundled credits and USD, epoch allocation. | | `GET /billing/usage-history` | Per-request ledger with keyset (cursor) pagination. JSON or CSV. | | `GET /billing/usage-analytics` | Aggregated breakdowns: by date, model, API key. | | `GET /billing/usage` | **Retired.** Sunset 2026-09-16; every request returns `410`. |

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`](../venice-x402/SKILL.md). 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`](../venice-api-keys/SKILL.md)).

`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.

| Param | Notes | |---|---| | `startTimestamp` | Optional. Inclusive lower bound, ISO 8601 UTC with a `Z` suffix (max 40 chars). First page only. | | `endTimestamp` | Optional. Exclusive upper bound, same format. Must be later than `startTimestamp`. Consecutive windows that share a boundary walk the history with no gaps and no overlaps. | | `currency` | Optional. `USD` / `DIEM` / `BUNDLED_CREDITS` / `EARNED_CREDITS`. | | `pageSize` | Integer 10–1000. Default **1000**. | | `cursor` | Opaque continuation token (`[A-Za-z0-9_-]`, ≤ 512 chars) from a previous `nextCursor`. Carries the filters and page size of the walk it continues, so send it **alone**. |

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