按网关请求头快照（x-trace-id / x-user-id / x-agent-name）查询历史调用用量。Base URL：https://www.51kik.com，鉴权见 访问令牌。

关联头说明见 请求关联。

筛选规则

trace_id、user_id、agent_name 三选一必填，不能同时传多个，也不能都不传。值为调用时在对应请求头中传入的原文字符串。

聚合统计

GET /openapi/trace-usage/aggregate

curl -sS "https://www.51kik.com/openapi/trace-usage/aggregate?trace_id=order-2024-0001" \
  -H "X-Access-Token: $ACCESS_TOKEN"

Query（三选一）：

参数说明
trace_idx-trace-id 原值
user_idx-user-id 原值
agent_namex-agent-name 原值

响应 data 示例：

{
  "totalTokens": 123456,
  "promptTokens": 80000,
  "completionTokens": 40000,
  "reasoningTokens": 3456,
  "cachedInputTokens": 12000,
  "totalRequests": 500,
  "okRequests": 480,
  "errorRequests": 20,
  "successRate": 96.00,
  "revenueCredit": 1234,
  "giftCostCredit": 200,
  "paidCostCredit": 1034,
  "avgLatencyMs": 850,
  "avgStreamFirstTokenMs": 120,
  "distinctModels": 5,
  "distinctApiKeys": 3
}

data 字段说明：

字段类型说明
totalTokensnumber总 tokens 数（prompt + completion）
promptTokensnumber输入 tokens 总数
completionTokensnumber输出 tokens 总数
reasoningTokensnumber推理 tokens 总数
cachedInputTokensnumber缓存命中的输入 tokens 总数
totalRequestsnumber总请求数
okRequestsnumber成功请求数（status = ok）
errorRequestsnumber失败请求数（status = error）
successRatenumber成功率（0–100，保留两位小数）
revenueCreditnumber总扣费 credits（收入侧）
giftCostCreditnumber赠送额度扣费 credits
paidCostCreditnumber付费额度扣费 credits
avgLatencyMsnumber | null平均端到端延迟（毫秒），无数据时为 null
avgStreamFirstTokenMsnumber | null流式请求首 token 平均延迟（毫秒），非流式请求不计入
distinctModelsnumber涉及的不同模型数
distinctApiKeysnumber涉及的不同 API Key 数

分页列表

GET /openapi/trace-usage/list

curl -sS "https://www.51kik.com/openapi/trace-usage/list?user_id=user-123&page=1&page_size=20" \
  -H "X-Access-Token: $ACCESS_TOKEN"

除上述三选一筛选外，还支持：

参数说明
page页码，默认 1
page_size每页条数，默认 20，最大 100

列表按 createdAt 倒序。响应 data 示例：

{
  "items": [
    {
      "requestId": "chatcmpl-abc123",
      "createdAt": "2026-06-10T08:30:00.000Z",
      "modelCode": "gpt-4o",
      "protocolSource": "openai",
      "status": "ok",
      "errorCode": null,
      "errorMessage": null,
      "finishReason": "stop",
      "promptTokens": 500,
      "completionTokens": 200,
      "totalTokens": 700,
      "reasoningTokens": 0,
      "cachedInputTokens": 0,
      "revenueCredit": 7,
      "giftCostCredit": 5,
      "paidCostCredit": 2,
      "latencyMs": 850,
      "streamLlmFirstTokenMs": null,
      "userId": "user-123",
      "agentName": "my-agent",
      "traceId": "trace-abc",
      "referer": "https://example.com",
      "clientIp": "1.2.3.4",
      "userAgent": "curl/8.0"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

data.items[] 单条记录字段：

字段类型说明
requestIdstring | null上游请求 ID，对应 OpenAI 兼容响应中的 id
createdAtstring记录创建时间（UTC ISO 8601 字符串）
modelCodestring请求模型 code
protocolSourcestring协议来源：openai / anthropic
statusstring调用状态：ok / error
errorCodestring | null错误码，成功时为 null
errorMessagestring | null错误信息，成功时为 null
finishReasonstring | null上游返回的 finish_reason（stop、length 等）
promptTokensnumber输入 tokens
completionTokensnumber输出 tokens
totalTokensnumber总 tokens
reasoningTokensnumber推理 tokens
cachedInputTokensnumber缓存命中输入 tokens
revenueCreditnumber总扣费 credits（收入侧）
giftCostCreditnumber赠送额度扣费 credits
paidCostCreditnumber付费额度扣费 credits
latencyMsnumber | null端到端延迟（毫秒）
streamLlmFirstTokenMsnumber | null流式请求首 token 延迟（毫秒），非流式为 null
userIdstring | null请求头 x-user-id 原值
agentNamestring | null请求头 x-agent-name 原值
traceIdstring | null请求头 x-trace-id 原值
refererstring | null请求头 Referer
clientIpstring | null客户端 IP
userAgentstring | null请求头 User-Agent

分页字段：

字段类型说明
itemsarray当前页记录列表
totalnumber符合条件的总记录数
pagenumber当前页码
pageSizenumber每页条数

错误

HTTPcode场景
401401未携带 X-Access-Token，或令牌无效 / 已禁用 / 已过期
40040001筛选参数不合法（未满足三选一）

筛选参数不合法时响应体：

{
  "code": 40001,
  "message": "必须且只能提供 trace_id、user_id、agent_name 中的一个",
  "data": null
}

相关