获取 API 密钥用量

返回单个 API 密钥的逐条用量记录。

本页提供 OpenAPI 结构说明和可复制的请求示例。请在终端或客户端使用 Management Token 发送管理请求；本页不提供直接发送功能。

查询参数

参数	类型	默认值 / 限制	说明
`page`	integer	默认 `1`，最小 `1`	从 1 开始的页码
`limit`	integer	默认 `50`，最小 `1`，最大 `100`	每页条数
`model`	string	最大长度 `100`	请求时使用的模型名
`modelVendor`	string	最大长度 `100`	公开模型厂商
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	起始时间，接受带时区的 RFC3339 或 `YYYY-MM-DD`
`endDate`	string	-	结束时间，接受带时区的 RFC3339 或 `YYYY-MM-DD`

如果同时提供 startDate 和 endDate，则 startDate 必须早于或等于 endDate。

说明

金额字段仅支持 USD。
响应是分页的。
完成结算的记录会带有 billing_transaction_id，可与 request_id 一起保存。

示例

请求

cURL

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=chat&startDate=2026-07-01&endDate=2026-07-31" \
  -H "Authorization: Bearer mt-your-management-token"

响应示例

响应

200 OK

{
  "api_key": {
    "id": "key_abc123def456",
    "name": "Backend Worker",
    "key_prefix": "sk-live...",
    "status": "active",
    "limit_amount": 500,
    "limit_amount_decimal": "500",
    "used_amount": 148.25,
    "used_amount_decimal": "148.25",
    "models": [
      "gpt-5.6-luna",
      "claude-3-7-sonnet"
    ],
    "expires_at": "2026-12-31T23:59:59.000Z",
    "last_used_at": "2026-07-08T03:12:45.000Z",
    "created_at": "2026-07-01T10:00:00.000Z",
    "delivery_policy": null
  },
  "items": [
    {
      "request_id": "req_abc123",
      "billing_transaction_id": "billtxn_abc123",
      "model": "gpt-5.6-luna",
      "logical_model": "gpt-5.6-luna",
      "model_vendor": "OpenAI",
      "scene": "chat",
      "usage_unit": "per_token",
      "usage_quantity": 1500,
      "usage_quantity_decimal": "1500",
      "prompt_tokens": 1000,
      "completion_tokens": 500,
      "total_tokens": 1500,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cache_write_tokens_5m": 0,
      "cache_write_tokens_1h": 0,
      "cost": 0.0012,
      "cost_decimal": "0.0012",
      "created_at": "2026-07-08T03:15:00.000Z",
      "requested_policy": null,
      "resolved_tier": null,
      "charged_price_basis": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  },
  "summary": {
    "total_requests": 1,
    "total_cost": 0.0012,
    "total_cost_decimal": "0.0012",
    "total_prompt_tokens": 1000,
    "total_completion_tokens": 500,
    "total_tokens": 1500,
    "usage_unit_breakdown": [
      {
        "usage_unit": "per_token",
        "usage_quantity": 1500
      }
    ]
  },
  "breakdowns": {
    "by_model": [
      {
        "model": "gpt-5.6-luna",
        "logical_model": "gpt-5.6-luna",
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500"
      }
    ],
    "by_logical_model": [
      {
        "model": "gpt-5.6-luna",
        "logical_model": "gpt-5.6-luna",
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500"
      }
    ],
    "by_model_vendor": [
      {
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012
      }
    ],
    "by_scene": [
      {
        "scene": "chat",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

重要字段

api_keyobject

API 密钥摘要。

itemsarray

分页后的用量明细。

paginationobject

分页元数据，包含 page、limit、total 和 totalPages。

summaryobject

按所选筛选条件汇总的总计。

breakdownsobject

按不同维度汇总的费用和用量。

items[].request_idstring | null

请求 ID。

items[].billing_transaction_idstring | null

完成结算后可用的账单交易 ID。

items[].modelstring

请求时使用的公开模型名称。

items[].logical_modelstring

用于汇总的公开模型。

items[].model_vendorstring | null

公开模型厂商。

items[].scenestring | null

公开请求场景。

items[].usage_unitstring

账单计量单位，例如 per_token。

items[].usage_quantitynumber

以 JSON 数字返回的用量，用于展示。

items[].usage_quantity_decimalstring

以十进制字符串返回的精确用量。

items[].prompt_tokensnumber

提示 token 数。

items[].completion_tokensnumber

补全 token 数。

items[].total_tokensnumber

token 总数。

items[].cache_read_tokensnumber

缓存读取 token 数。

items[].cache_write_tokensnumber

缓存写入 token 总数。

items[].cache_write_tokens_5mnumber

5 分钟缓存写入 token 数。

items[].cache_write_tokens_1hnumber

1 小时缓存写入 token 数。

items[].costnumber

以 JSON 数字返回的 USD 费用，用于展示。

items[].cost_decimalstring

以十进制字符串返回的 USD 精确费用。

items[].requested_policystring | null

auto, verified, official, null. 请求的交付策略；未记录时为 null。

items[].resolved_tierstring | null

verified, official, null. 实际使用的交付档位；未记录时为 null。

items[].charged_price_basisobject | null

实际采用的价格和计费用量；未记录时为 null。

items[].created_atstring

用量明细的 ISO 时间戳。

summary.total_requestsnumber

请求总数。

summary.total_costnumber

以 JSON 数字返回的 USD 总费用，用于展示。

summary.total_cost_decimalstring

以十进制字符串返回的 USD 精确总费用。

summary.total_prompt_tokensnumber

提示 token 总数。

summary.total_completion_tokensnumber

补全 token 总数。

summary.total_tokensnumber

token 总数。

summary.usage_unit_breakdownarray

按计量单位分组的用量。

breakdowns.by_modelarray

按请求时使用的公开模型拆分。

breakdowns.by_logical_modelarray

按逻辑公开模型拆分。

breakdowns.by_model_vendorarray

按公开模型厂商拆分。

breakdowns.by_scenearray

按公开请求场景拆分。

breakdowns.daily_costarray

每日费用趋势。

授权

ManagementTokenAuth

AuthorizationBearer <token>

管理令牌身份验证。在 Dashboard > API > Management Tokens 中创建或管理管理令牌。

位置: header

路径参数

keyId*string

查询参数

page?integer

基于 1 的页码。默认为 1。

范围1 <= value

默认值1

limit?integer

每页大小。默认为 50，最大为 100。

范围1 <= value <= 100

默认值50

model?string

按请求的模型名称过滤。最大长度 100。

长度length <= 100

modelVendor?string

按公共模型供应商过滤。最大长度 100。

长度length <= 100

scene?string

按公共请求场景过滤。

可选值

"chat"
"image"
"audio"
"video"
"embedding"
"rerank"
"translation"
"music"
"3d"
"realtime"
"systemone"

startDate?string

包含日期范围的过滤器。接受带时区的 RFC3339（例如 2026-03-28T00:00:00+08:00）或 YYYY-MM-DD 格式。

endDate?string

包含日期范围的过滤器。接受带时区的 RFC3339（例如 2026-03-28T00:00:00+08:00）或 YYYY-MM-DD 格式。

获取 API 密钥用量

查询参数

说明

示例

响应示例

重要字段

授权

路径参数

查询参数

响应

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

获取 API 密钥用量

查询参数Copy Anchor Link

说明Copy Anchor Link

示例Copy Anchor Link

响应示例Copy Anchor Link

重要字段Copy Anchor Link

授权Copy Anchor Link

路径参数Copy Anchor Link

查询参数Copy Anchor Link

响应Copy Anchor Link

200application/json

400application/json

401application/json

403application/json

404application/json

查询参数

说明

示例

响应示例

重要字段

授权

路径参数

查询参数

响应

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`