文档

用量 API

查询发起请求的 API key 的 token 数和费用。每把 key 只能访问自己的数据，不能跨 key 访问。可用于构建自己的账单仪表板、月度对账或费用提醒。

GET /v1/usage 返回 Authorization 请求头中的 API key 对应的 token 和费用汇总数据。可按日或小时分组，也可按模型拆分。无法读取其他 key 的数据——如需查看，请登录控制面板。

认证

将 Kunavo API key 作为 Bearer token 传入，也就是你要查询用量的那个 key。端点仅返回记在此特定 key 下的用量；没有参数可以请求其他 key 的数据。

建议每个项目使用一把独立的 key。 推荐做法是为每个需要计费的应用创建单独的 API key；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	此时间桶内以 USD 计收的费用，精度为 6 位小数。使用字符串保留精度；可安全地通过 `parseFloat()` 解析。

为什么费用使用字符串表示。 单次调用的费用很低（缓存流量下，只有几万分之几美分），若直接将其转换为字符串，IEEE-754 浮点数会将其舍入为零。将传输格式保留为带 6 位小数的字符串，可让你的记账代码使用任意精度进行解析（例如 Decimal()）。

客户端缓存

此端点会设置 Cache-Control: private, max-age=60。大多数客户端（浏览器、带会话的请求，以及你一侧的任何 HTTP 缓存）在 60 秒窗口内对相同参数会返回相同响应——这适用于轮询的仪表板。如需强制读取最新数据，可更改查询字符串（例如附加一个 &_=ts 缓存破坏参数），或在你一侧传入 Cache-Control: no-cache。

错误

状态	代码	何时
`401`	`authentication_error`	Bearer key 缺失、格式错误或已撤销。
`400`	`invalid_request_error`	`start_date`/`end_date` 格式错误、结束日期早于开始日期、`start_date` 晚于今天、时间跨度超过时间桶限制，或 `group_by` 值不受支持。
`500`	`internal_error`	数据库不可用或发生意外故障。

注意事项

已删除的 key。 撤销 API key 时，其过往用量记录会失去对应的 api_key_id（设为 null），因此无法再通过此端点查询历史总量。这些数据仍保留在控制面板的账户汇总视图中。如果需要不可变的逐 key 审计记录，请在撤销前获取并保存数据。
近实时。 底层调用完成后的几秒内，用量记录就会写入。没有保证的数据延迟上限——如果需要与账单精确对齐，请每天查询一次前一天的数据，而不要按分钟轮询。
费用为实际计费金额。 此处的 cost_usd 与从钱包账本扣除的金额一致。该金额已计入计费中说明的 max(catalog, upstream × markup) 下限。此响应中没有单独的“批发”价格。

接下来

计费与账本 — 说明每次调用的 cost_usd 如何计算并记录在此处。
身份验证 — 创建新的 API key（每个项目一把）。
控制面板用量视图 — 相同的数据，并提供图表、逐次调用的详细信息，以及跨所有 key 的账户级汇总。