查询用于本次鉴权的 API Key 按 model 汇总的请求数、token 用量和费用。

API Key 用量统计

通过 API Key 用量统计接口，查询用于本次鉴权的 API Key 在指定 UTC+8 日期范围内按 model 汇总的请求数、token 用量和费用。接口只返回当前 API Key 自身的数据；不接受调用方指定其他 API Key、用户、工作区或游标。

本接口返回按 model 聚合的统计结果。如需逐条调用记录，应使用 API Key 用量查询接口。

接口说明

项目	值
方法	`GET`
路径	`/v1/api-key/usage-stats`
API 地址	`https://unigateway.ai/v1/api-key/usage-stats`
鉴权	`Authorization: Bearer <YOUR_API_KEY>`
响应格式	`application/json`

注意：/v1/api-key/usage-stats 是 API Key 管理专用接口，必须使用 https://unigateway.ai，不能使用常规的 https://api.unigateway.ai API 地址。

响应包含 Cache-Control: no-store，不应缓存响应内容。

准备工作与鉴权

请前往 UniGateway API Keys 创建或获取 API Key。

将 API Key 保存为服务端环境变量。不要将 API Key 写入浏览器前端代码、日志、公开仓库或导出文件：

export UNIGATEWAY_API_KEY="<YOUR_API_KEY>"

Windows PowerShell：

$env:UNIGATEWAY_API_KEY = "<YOUR_API_KEY>"

请求使用普通 UniGateway API Key。Bearer token 所代表的 API Key 同时决定查询范围，接口不会接受或覆盖为其他 API Key、用户、工作区或游标。

查询用量统计

GET /v1/api-key/usage-stats

日期范围

统计按 UTC+8 自然日计算，不支持时区参数。未传日期参数时，接口查询当前 UTC+8 日期。

传入方式	规则
`date=YYYY-MM-DD`	查询该 UTC+8 自然日。
`date=YYYY-MM-DDTHH:mm:ssZ`	查询该 UTC 时刻所在的 UTC+8 自然日。
`start_date` 与 `end_date`	必须同时使用 `YYYY-MM-DD` 提供；范围包含结束日，并自动扩展至 UTC+8 日首和日末。最长 366 天。

date 接受 YYYY-MM-DD 和 YYYY-MM-DDTHH:mm:ssZ 两种格式。秒级格式只接受大写 Z，不接受时区偏移和小数秒。start_date 与 end_date 使用 YYYY-MM-DD；秒级格式只在起止时刻恰好对齐 UTC+8 日首和日末时接受，否则返回 USAGE_STATS_RANGE_MUST_ALIGN_UTC8_DAY。不能将 date 与 start_date 或 end_date 同时使用。可查询最近 366 个 UTC+8 自然日，不能查询未来日期。

例如，start_date=2026-09-01 与 end_date=2026-09-04 实际统计 2026-08-31T16:00:00Z 至 2026-09-04T15:59:59Z。传入 date=2026-09-04T23:59:59Z 时，该时刻位于 2026-09-05 UTC+8 日，接口统计 2026-09-04T16:00:00Z 至 2026-09-05T15:59:59Z。

查询参数

参数	类型	必填	默认值	说明
`date`	string	否	当前 UTC+8 日期	查询一个 UTC+8 自然日。不能与 `start_date`、`end_date` 同用。
`start_date`	string	条件必填	-	使用 `YYYY-MM-DD`，必须与 `end_date` 同时提供。
`end_date`	string	条件必填	-	使用 `YYYY-MM-DD`，必须与 `start_date` 同时提供，范围包含结束日。
`sort_by`	string	否	`tokens`	model 排序方式：`tokens` 或 `cost`。
`limit`	integer	否	`50`	返回的 model 数，范围为 `1` 至 `100`。
`offset`	integer	否	`0`	分页偏移，范围为 `0` 至 `100000`。
`modelTypes`	array<string>	否	全部	按 model 类型筛选。
`modelNames`	array<string>	否	全部	按 model 名称精确筛选。

modelTypes 也接受 model_types、modelType、model_type 及其带 [] 的形式；modelNames 同样接受 model_names、modelName、model_name 及其带 [] 的形式。

model 类型为 claude、gemini、gpt、qwen、deepseek 或 other，大小写不敏感。每个筛选参数最多可传入 100 个值，每个值最多 256 个字符。省略筛选参数或传入空数组，均表示不按该维度筛选。

筛选参数支持重复参数、逗号分隔或 JSON 字符串数组：

modelTypes=gpt,claude
modelTypes=gpt&modelTypes=claude
modelTypes=["gpt","claude"]

不支持 token_id、user_id、organizationId、cursor 等其他参数，传入时返回参数错误。

cURL 请求示例

以下请求查询 2026 年 9 月 1 日至 4 日的统计，按 token 用量排序，返回前 50 个 model：

curl -G 'https://unigateway.ai/v1/api-key/usage-stats' \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  --data-urlencode 'start_date=2026-09-01' \
  --data-urlencode 'end_date=2026-09-04' \
  --data-urlencode 'sort_by=tokens' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'offset=0'

以下请求仅统计 gpt 与 claude 类型的 model，并按费用排序：

curl -G 'https://unigateway.ai/v1/api-key/usage-stats' \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  --data-urlencode 'date=2026-09-04' \
  --data-urlencode 'modelTypes=gpt,claude' \
  --data-urlencode 'sort_by=cost'

成功响应

{
  "date_range": {
    "start_date": "2026-08-31T16:00:00Z",
    "end_date": "2026-09-04T15:59:59Z",
    "time_zone": "UTC+8"
  },
  "sort_by": "tokens",
  "currency": "USD",
  "api_key": {
    "name": "Production",
    "key_prefix": "sk-prod",
    "status": "ACTIVE",
    "request_count": "42",
    "total_tokens": "125000",
    "text_input_tokens": "90000",
    "text_output_tokens": "35000",
    "cache_tokens": "0",
    "cache_creation_tokens_5m": null,
    "cache_creation_tokens_1h": null,
    "total_cost": "3.750000000000"
  },
  "models": [
    {
      "rank": 1,
      "model_id": "gpt-5",
      "model_type": "gpt",
      "model_name": "gpt-5",
      "request_count": "42",
      "total_tokens": "125000",
      "text_input_tokens": "90000",
      "text_output_tokens": "35000",
      "cache_tokens": "0",
      "cache_creation_tokens_5m": null,
      "cache_creation_tokens_1h": null,
      "total_cost": "3.750000000000"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

响应字段

字段	类型	说明
`date_range.start_date` / `date_range.end_date`	string	实际统计范围，以 UTC 时间戳返回。
`date_range.time_zone`	string	统计时区，固定为 `UTC+8`。
`sort_by`	string	当前排序依据：`tokens` 或 `cost`。
`currency`	string	聚合金额币种，当前为 `USD`。
`api_key.name`	string / null	当前鉴权 API Key 的名称。
`api_key.key_prefix`	string / null	当前鉴权 API Key 的非敏感前缀。
`api_key.status`	string	当前鉴权 API Key 的状态。
`api_key.request_count` / `api_key.total_tokens`	string	按当前 model 筛选条件汇总的请求数和总 token 数。
`api_key.text_input_tokens` / `api_key.text_output_tokens`	string	按当前 model 筛选条件汇总的文本输入和文本输出 token 数。
`api_key.cache_tokens`	string	按当前 model 筛选条件汇总的缓存 token 数。
`api_key.cache_creation_tokens_5m` / `api_key.cache_creation_tokens_1h`	string / null	按当前 model 筛选条件汇总的 5 分钟和 1 小时缓存创建 token 数；不适用或数据不可用时为 `null`。
`api_key.total_cost`	string	按当前 model 筛选条件汇总的费用。
`models`	array<object>	当前页的 model 分组。
`models[].rank`	integer	筛选后的全局排名，不受 `offset` 影响。
`models[].model_id`	string / null	model ID；数据不可用时为 `null`，不保证在不同分组中唯一。
`models[].model_type` / `models[].model_name`	string	model 类型和名称。
`models[].request_count` / `models[].total_tokens`	string	该 model 分组的请求数和总 token 数。
`models[].text_input_tokens` / `models[].text_output_tokens`	string	该 model 分组的文本输入和文本输出 token 数。
`models[].cache_tokens`	string	该 model 分组的缓存 token 数。
`models[].cache_creation_tokens_5m` / `models[].cache_creation_tokens_1h`	string / null	该 model 分组的 5 分钟和 1 小时缓存创建 token 数；不适用或数据不可用时为 `null`。
`models[].total_cost`	string	该 model 分组的费用。
`total`	integer	筛选后 model 分组的总数。
`limit` / `offset`	integer	当前页大小与分页偏移。
`has_more`	boolean	是否还有下一页。

models 按 sort_by 选定指标降序排列；选定指标相同时，以另一项指标降序排列。api_key 总计会应用 model 筛选，但不受分页影响。request_count、所有 token 字段和 total_cost 均以字符串返回；金额单位为 USD。total_tokens、输入、输出和缓存 token 字段均应直接使用服务端返回值，不要在客户端相加或推导。处理金额时应使用高精度十进制类型，避免二进制浮点精度误差。

错误处理与频率限制

错误响应示例：

{
  "error": {
    "code": "INVALID_USAGE_STATS_QUERY",
    "message": "limit must be between 1 and 100",
    "param": null,
    "type": "BadRequest"
  }
}

HTTP 状态码	说明	处理方式
`400`	查询参数无效。	检查日期格式、日期范围、筛选值与分页范围，移除不支持的参数。
`401`	API Key 缺失、无效、已归档，或不满足接口鉴权条件。	在服务端加载当前有效的普通 API Key 后重试。
`403`	API Key、工作区或子账号已被禁用。	在 UniGateway 控制台检查状态和访问控制，修正后重新验证。
`429`	超出限流。	降低并发，等待后重试。
`500`	服务内部错误。	使用有限次数的指数退避重试；持续失败时保留错误时间和请求参数以便排查。

400 响应的 code 可用于区分原因：

`error.code`	常见原因
`INVALID_USAGE_STATS_QUERY`	日期格式或参数组合无效、筛选值不支持、分页值越界、传入了不支持的参数。
`USAGE_STATS_RANGE_MUST_ALIGN_UTC8_DAY`	`start_date` 或 `end_date` 使用秒级时间但未对齐 UTC+8 日首或日末。

每个 API Key 每分钟最多可请求 120 次。轮询或批量查询应控制并发；收到 429 时避免立即重复请求。

常见问题

Q: 为什么不能查询同一账户下其他 API Key 的统计？

该接口始终以 Authorization 中的普通 API Key 作为查询对象，不接受 token_id、用户、工作区或其他 API Key 参数。请在服务端切换为需要查询的 API Key，重新发起相同请求；不要将 API Key 放入 URL 或客户端代码。

Q: 日期查询为什么返回 `400 Bad Request`？

检查 date、start_date 和 end_date 是否使用 YYYY-MM-DD，或 date 是否使用 YYYY-MM-DDTHH:mm:ssZ，并确认秒级格式使用大写 Z、不含时区偏移和小数秒。同时确认没有将 date 与范围参数同时传入。范围查询必须同时提供 start_date 与 end_date，结束日期不能早于开始日期，且不能查询未来日期或超过 366 天的范围。修正后重新执行请求。

Q: `USAGE_STATS_RANGE_MUST_ALIGN_UTC8_DAY` 怎么处理？

start_date 和 end_date 的秒级取值必须正好落在 UTC+8 日首和日末，即 16:00:00Z 与 15:59:59Z。推荐改用 YYYY-MM-DD，接口会自动扩展到 UTC+8 日首和日末。

Q: Key 总计为什么与当前页 `models` 的合计不同？

api_key 总计应用当前 model 筛选条件，但不受 limit 和 offset 分页影响；models 只包含当前页。请继续按 has_more 与 offset 获取后续页，或根据需求调整分页参数。

API Key 用量统计#

接口说明#

准备工作与鉴权#

查询用量统计#

日期范围#

查询参数#

cURL 请求示例#

成功响应#

响应字段#

错误处理与频率限制#

常见问题#

Q: 为什么不能查询同一账户下其他 API Key 的统计？#

Q: 日期查询为什么返回 400 Bad Request？#

Q: USAGE_STATS_RANGE_MUST_ALIGN_UTC8_DAY 怎么处理？#

Q: Key 总计为什么与当前页 models 的合计不同？#