Docs

Docs

Usage API

Query token counts and cost for the API key making the request. One key, its own data — no cross-key access. Use this to drive your own billing dashboards, monthly reconciliation, or cost alerts.

GET /v1/usage returns aggregated token and cost figures for the API key in the Authorization header. Group by day or hour; optionally split by model. No scope to read another key's data — for that, log in to the dashboard.

To read the wallet balance, call GET /v1/balance: see Balance below.

Authentication

Pass your Kunavo API key as a Bearer token, the same key whose usage you want to read. The endpoint returns only the usage that was billed against this specific key — there is no parameter to request another key's data.

Treat one project per key. The recommended pattern is to mint a separate API key for each application you bill — Kunavo dashboards and this endpoint then naturally roll up "per project". Manage keys at /app/keys.

Several keys for each of your clients? Put each client's keys in a key group to read in the dashboard what every key and every client spent in a calendar month, and to export it as CSV.

Request

ParamRequiredDefaultNotes
start_dateyes—YYYY-MM-DD, UTC. Inclusive. Must be ≤ today (UTC).
end_dateyes—YYYY-MM-DD, UTC. Inclusive. A date after today is read as today; the response echoes the end_date used.
bucketnodayOne of day, hour.
group_byno(none)Comma-separated. Supported: model. Omit to get one row per bucket.
Window limits. bucket=day accepts up to 90 days; bucket=hour accepts up to 7 days. Beyond that the request returns 400 invalid_request_error — split into multiple calls.
Time zone. Buckets are aligned to UTC days/hours. If you need wall-clock days in another tz, query daily and fold the edges on the client. A future tz= param will do this server-side without changing any existing field.

Examples

Daily totals across the last 30 days, all models rolled up:

usage_30d.sh
# Daily totals for the last 30 days
curl https://api.kunavo.com/v1/usage \
  -G \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  --data-urlencode "start_date=2026-04-28" \
  --data-urlencode "end_date=2026-05-27"

One row per (day, model):

usage_by_model.sh
# Per-model daily breakdown — one row per (day, model)
curl https://api.kunavo.com/v1/usage \
  -G \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  --data-urlencode "start_date=2026-05-01" \
  --data-urlencode "end_date=2026-05-27" \
  --data-urlencode "group_by=model"

Python — sum the window into a single number:

usage_query.py
import os, datetime as dt, requests

today = dt.date.today()
start = today - dt.timedelta(days=29)  # last 30 days inclusive

r = requests.get(
    "https://api.kunavo.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['KUNAVO_API_KEY']}"},
    params={
        "start_date": start.isoformat(),
        "end_date":   today.isoformat(),
        "group_by":   "model",
    },
    timeout=30,
)
r.raise_for_status()
body = r.json()

# body["data"] is one row per (day, model). Sum cost across the window:
total_usd = sum(float(row["cost_usd"]) for row in body["data"])
print(f"Spent ${total_usd:.4f} on key {body['api_key']['name']}")

Response

200 OK — application/json with a list of rows. Buckets with zero activity are omitted; the client fills gaps if it needs a contiguous series.

response.json
{
  "object": "list",
  "api_key": {
    "id": "k_abc123",
    "name": "production",
    "prefix": "sk-kn-aZ8x"
  },
  "start_date": "2026-05-01",
  "end_date":   "2026-05-27",
  "bucket": "day",
  "data": [
    {
      "bucket_start": "2026-05-01T00:00:00.000Z",
      "model": "claude-sonnet-4-6",
      "requests": 1284,
      "errors": 7,
      "input_tokens": 1532890,
      "output_tokens": 245100,
      "cached_input_tokens": 980000,
      "cache_write_tokens": 12000,
      "web_search_requests": 0,
      "cost_usd": "3.452100"
    },
    {
      "bucket_start": "2026-05-01T00:00:00.000Z",
      "model": "gpt-5",
      "requests": 88,
      "errors": 0,
      "input_tokens": 42000,
      "output_tokens": 12300,
      "cached_input_tokens": 0,
      "cache_write_tokens": 0,
      "web_search_requests": 0,
      "cost_usd": "0.210400"
    }
  ]
}
FieldTypeMeaning
bucket_startstring (ISO 8601, UTC)Start of the day or hour this row aggregates.
modelstringModel slug. Present only when group_by=model.
requestsnumberSuccessful calls in this bucket.
errorsnumberCalls that ended in error/timeout/cancelled. Not billed.
input_tokensnumberTotal input tokens (includes cached + cache-write subsets).
output_tokensnumberTotal output tokens.
cached_input_tokensnumberSubset of input_tokens served from the upstream prompt cache.
cache_write_tokensnumberTokens written to cache this bucket (Anthropic only; 0 elsewhere).
web_search_requestsnumberServer-side web searches, each billed on top of the tokens: Claude's through /v1/messages, and OpenAI's web_search tool on a GPT model through /v1/responses (0 elsewhere).
cost_usdstringWhat you were charged in USD for this bucket, 6-decimal precision. String to preserve precision; parseFloat() safely.
Why cost is a string. Tiny per-call costs (a few hundred-thousandths of a cent for cache-heavy traffic) round to zero in IEEE-754 if you stringify them naively. Keeping the wire format as a string with 6 decimals lets your accounting code parse it with arbitrary precision (e.g. Decimal()).

Client-side caching

The endpoint sets Cache-Control: private, max-age=60. Most clients (browsers, requests with a session, any HTTP cache on your side) will return the same response for the same parameters within a 60-second window — fine for dashboards that poll. To force a fresh read, vary the query string (e.g. append a &_=tsbuster) or pass Cache-Control: no-cache on your side.

Errors

StatusCodeWhen
401authentication_errorMissing, malformed, or revoked Bearer key.
400invalid_request_errorBad start_date/end_date format, end before start, a start_date after today, span over the bucket limit, or an unsupported group_by value.
500internal_errorDB unreachable or unexpected failure.

Caveats

  • Revoked keys. This endpoint answers only for the key that calls it, and a revoked key is refused with 401, so once you revoke a key you can no longer read its history here. Revoking deletes nothing: the key's past calls stay recorded under it, and the Usage page in the dashboard still shows them by key and in its CSV export, as totals for the range you pick. If you need the key's figures day by day, fetch them here before you revoke it.
  • Near-real-time. Rows land within a few seconds of the underlying call completing. There is no guaranteed staleness bound — if you need exact alignment with your invoice, query for yesterday once a day rather than minute-by-minute.
  • Cost is billed cost. The cost_usd here matches what was debited from your wallet ledger. It already reflects the max(catalog, upstream × markup) floor described in Billing. There is no separate "wholesale" figure in this response.

Balance

GET /v1/balance returns what the key that makes the request can spend right now: the wallet of the account, the amount held for tasks that are still running, and what is left under a monthly limit. The call only reads. It costs nothing, reserves nothing and takes no parameters.

balance.sh
curl https://api.kunavo.com/v1/balance \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

An example response:

balance.json
{
  "object": "balance",
  "balance_usd": 12.5,
  "reserved_usd": 3.06,
  "available_usd": 9.44,
  "api_key": {
    "id": "k_abc123",
    "name": "production",
    "prefix": "sk-kn-aZ8x",
    "monthly_limit": {
      "limit_usd": 50,
      "spent_usd": 12.25,
      "remaining_usd": 37.75,
      "resets_at": "2026-11-01T00:00:00.000Z"
    },
    "group_monthly_limit": null
  },
  "account": {
    "monthly_cap": null
  },
  "auto_recharge": {
    "status": "off"
  }
}
FieldTypeMeaning
balance_usdnumberThe wallet of the account. Every key of the account reads the same figure. When a request is refused because the balance is too low, the 402 reports this figure as error.balance_usd.
reserved_usdnumberThe amount held for the account's image, video and music tasks that are still running. A task holds its reservation from the moment it is submitted until it ends.
available_usdnumberbalance_usd minus reserved_usd, never below zero.
api_key.monthly_limitobject|nullThe monthly spend limit set on this key at /app/keys, or null when the key has none. The object has four fields: limit_usd, spent_usd (what the key has spent in the current calendar month in UTC, successful calls only), remaining_usd and resets_at.
api_key.group_monthly_limitobject|nullThe same four fields for a monthly spend limit set at /app/keys on the key group this key is in, counted over all of the group's keys (the calls each made while in the group). It is null when the key is in no group or its group has no limit. The response never names the group.
account.monthly_capobject|nullThe same four fields for a cap on the whole account. It is null unless Kunavo has set a cap on your account.
auto_recharge.statusstringWhether auto-recharge refills the wallet: on, paused (switched on, but stopped until you act at /app/billing) or off.

Before a request runs, Kunavo reserves an estimate of its cost. The request is refused with a 402 when that estimate is more than available_usd, or more than the remaining_usd of a monthly limit. When it is more than available_usd and auto-recharge is on, Kunavo refills the wallet from the saved payment method if balance_usd, not available_usd, is under your auto-recharge threshold and the limits on refills allow it, then tries the request once more; with no refill, or one that is not enough, the request is refused. A request over a monthly limit is refused whether or not auto-recharge is on. Near a limit, Kunavo judges a request on a count that can be up to a minute old and that leaves out what running requests hold, so a request under remaining_usd can still be refused, one over it admitted by as much as was charged in the last minute, and requests that run at the same time can together pass the limit. For an image or a video, the estimate is the listed price of the tier the request runs at, multiplied by the number of seconds on a model billed per second, and by the number of images when an image request asks for more than one (n); GET /v1/models lists the price of each tier in the field kunavo.tiers. For a text request, the estimate is the cost of the input plus the cost of as many output tokens as the request's output limit allows (max_tokens; max_completion_tokens first on /v1/chat/completions; max_output_tokens alone on /v1/responses), or of 32,000 output tokens when the request sets none. What the request is finally charged can differ from this estimate.

The reserved amount itself is never charged: when the request ends (for an image, video or music task, only when the task ends), Kunavo releases the reservation and charges the wallet what the request actually cost, or nothing if the request or its task failed.

Requests in flight. A request that is being answered also keeps its reservation until it finishes, and reserved_usd does not include that reservation. Several requests sent at the same time can therefore be refused even when each of them alone fits within available_usd.

Amounts are US dollars as JSON numbers with at most six decimals, the same form as balance_usd and needed_usd in a 402. The response carries Cache-Control: private, no-store, and the wallet and the reservations are read on every call. spent_usd can be up to a minute out of date.

A key whose monthly limit is used up can still call this endpoint, which never answers 402.

Where to go next