文件

用量 API

查詢發出請求的 API 金鑰所累計的 token 數量和費用。每把金鑰只能查看自己的資料，無法跨金鑰存取。可用於建立自己的帳單儀表板、每月對帳或費用警示。

GET /v1/usage 會傳回 Authorization 標頭中 API 金鑰的 token 和費用彙總數據。可按日或小時分組，也可選擇按模型細分。無法讀取其他金鑰的資料；如需查閱，請登入儀表板。

驗證

以 Bearer token 傳入您的 Kunavo API 金鑰，也就是您想查詢用量的那把金鑰。端點只會傳回歸在這把特定金鑰名下的已計費用量——沒有任何參數可用來要求其他金鑰的資料。

建議每個專案使用一把金鑰。建議為每個計費應用程式建立獨立的 API 金鑰——Kunavo 儀表板和此端點便會自然地按「專案」彙總資料。請前往 /app/keys 管理金鑰。

請求

參數	必要	預設值	備註
`start_date`	yes	—	YYYY-MM-DD，UTC。包含起訖日。必須 ≤ 今天（UTC）。
`end_date`	yes	—	YYYY-MM-DD，UTC。包含起訖日。今天之後的日期會按今天讀取；回應會回傳所使用的 end_date。
`bucket`	no	`day`	可使用 `day` 或 `hour`。
`group_by`	no	(none)	以逗號分隔。支援：`model`。省略此參數時，每個時間區間傳回一筆資料。

時間區間限制。 bucket=day 最多接受 90 天；bucket=hour 最多接受 7 天。超出限制時，請求會傳回 400 invalid_request_error — 請分多次呼叫。

時區。 時間區間以 UTC 日／小時為界。若需要其他時區的當地日曆日，請查詢每日資料，並在用戶端合併邊界資料。未來將提供 tz= 參數，在伺服器端完成這項處理，且不會變更任何現有欄位。

範例

查詢最近 30 天的每日總計，彙總所有模型：

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"

每個（日期、模型）組合各傳回一筆資料：

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 — 將此時間區間加總為單一數值：

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']}")

回應

200 OK — application/json，包含資料列清單。沒有活動的時間區間會省略；若需要連續的序列，用戶端可自行補齊間隔。

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

欄位	類型	意義
`bucket_start`	字串（ISO 8601，UTC）	此資料列彙總的日期或小時起始時間。
`model`	string	模型代稱。只有在 `group_by=model` 時才會出現。
`requests`	number	此時間區間內成功的呼叫次數。
`errors`	number	以錯誤、逾時或取消結束的呼叫次數。不計費。
`input_tokens`	number	輸入 token 總數（包含快取與快取寫入子集）。
`output_tokens`	number	輸出 token 總數。
`cached_input_tokens`	number	`input_tokens` 中由上游提示快取提供的子集。
`cache_write_tokens`	number	此區間寫入快取的 token（僅 Anthropic；其他情況為 0）。
`web_search_requests`	number	伺服器端網頁搜尋次數；每次都會在 token 費用之外另行計費：Claude 的搜尋透過 `/v1/messages`，GPT 模型的 OpenAI `web_search` 工具則透過 `/v1/responses`（其他情況皆為 0）。
`cost_usd`	string	此時間區間向您收取的美元費用，精確至小數點後 6 位。使用字串保留精度；以 `parseFloat()` 安全解析。

費用為何使用字串表示。 極低的單次呼叫費用（快取流量有時僅為千分之一美分的幾百分之一），若直接轉成字串，會在 IEEE-754 浮點數中被四捨五入為零。以 6 位小數的字串格式保留線路傳輸資料，讓您的帳務程式碼能以任意精度解析（例如 Decimal()）。

用戶端快取

此端點會設定 Cache-Control: private, max-age=60。在 60 秒內，大多數用戶端（瀏覽器、使用工作階段的請求，以及您端的任何 HTTP 快取）都會針對相同參數傳回相同回應，適合輪詢儀表板。若要強制重新讀取，可變更查詢字串（例如加上 &_=ts 避免快取）或在您端傳入 Cache-Control: no-cache。

錯誤

狀態	程式碼	何時
`401`	`authentication_error`	Bearer 金鑰缺漏、格式錯誤或已撤銷。
`400`	`invalid_request_error`	`start_date`／`end_date` 格式錯誤、結束日期早於開始日期、`start_date` 晚於今天、時間區間超出分桶上限，或 `group_by` 值不受支援。
`500`	`internal_error`	資料庫無法連線或發生未預期的錯誤。

注意事項

已刪除的金鑰。 撤銷 API 金鑰時，其過往用量資料列會失去 api_key_id（設為 null），因此無法再透過此端點擷取歷史總計。儀表板的帳戶彙總檢視仍會保留這些資料。若需要不可變更的逐金鑰稽核軌跡，請在撤銷金鑰前擷取並儲存資料。
接近即時。 底層呼叫完成後幾秒內，資料列便會出現。我們不保證資料延遲上限；若要與發票精確對帳，請每天查詢一次前一天的資料，而非每分鐘查詢。
費用即為實際計費金額。 此處的 cost_usd 與從您的錢包帳本扣除的金額一致，且已反映 Billing 中說明的 max(catalog, upstream × markup) 最低計費門檻。此回應不會另外提供「批發價」數據。

接下來可以查看

計費與帳本 — 說明每次呼叫的 cost_usd 如何計算，並記錄於此。
驗證 — 建立新的 API 金鑰（每個專案一把）。
儀表板用量檢視 — 相同資料，並提供圖表、單次呼叫詳細資料，以及所有金鑰的帳戶彙總。