用量 API 返回一个项目在某个自然月内的用量。你可以用它在自己的应用中展示用量、检查项目离某个额度还有多远，或核对你向自己客户收取的费用。
它与 /v1/ai 使用同一个项目 API 密钥（Authorization: Bearer mr_live_…），并且只会返回该密钥所属项目的数据。
获取某个月的用量
HTTP
1GET /v1/usage?month=2026-10| 参数 | 默认值 | 说明 |
|---|---|---|
month | 当前月份 | YYYY-MM，按 UTC 计算。可查询当前月份及之前的 24 个月 |
JSON
1{2 "project_id": "7c2e5a0b-3f41-4f7e-9d0a-6a1b2c3d4e5f",3 "month": "2026-10",4 "period_start": "2026-10-01T00:00:00Z",5 "period_end": "2026-11-01T00:00:00Z",6 "billable_requests": 3240,7 "requests": 3301,8 "failed_requests": 12,9 "prompt_tokens": 4120000,10 "completion_tokens": 610000,11 "total_tokens": 4730000,12 "price": 12.48,13 "active_sessions": 980,14 "by_day": [15 { "date": "2026-10-01", "billable_requests": 112, "requests": 115 },16 { "date": "2026-10-02", "billable_requests": 98, "requests": 98 }17 ],18 "updated_at": "2026-10-27T09:14:00Z"19}| 字段 | 说明 |
|---|---|
billable_requests | 计入套餐的请求数，计算方式与计费完全一致 |
requests | 全部请求，包括 Playground 和测试模式运行 |
failed_requests | 以错误结束的请求 |
prompt_tokens、completion_tokens、total_tokens | 所有请求的令牌数 |
price | 根据 ModelRiver 的模型定价估算的服务商费用（美元） |
active_sessions | 当月至少有一次请求的不同会话数 |
by_day | 当月截至今天（UTC）的每一天，包括没有请求的日期 |
updated_at | 这些数字的统计时间 |
哪些请求计费
- 每个
/v1/ai请求只计一次，即使故障转移在另一个服务商上重试过。 - Playground 和测试模式运行不计费。
- 通过
POST /v1/sessions/:id/messages追加的消息不计费：它们不会调用模型。
数据有多新
当前月份包含一分钟前发出的请求。结果会按项目和月份缓存约一分钟，因此更频繁地轮询会得到相同的数字；请查看 updated_at。
请求日志在套餐的数据保留期结束后被删除，但之前月份的用量仍然可以查询。较晚完成的请求（例如异步回调）在一周内仍可能改变某个月最后几天的数字。
错误
month 不是 YYYY-MM 格式、是未来月份，或早于 24 个月之前时，返回 422：
JSON
1{ "error": "invalid_month", "message": "month must be YYYY-MM, from 2024-10 to 2026-10" }缺少 API 密钥或密钥无效时返回 401。