按网关请求头快照(x-trace-id / x-user-id / x-agent-name)查询历史调用用量。Base URL:http://127.0.0.1:9001,鉴权见 访问令牌。

关联头说明见 请求关联。

筛选规则

以下聚合统计与分页明细接口要求 trace_id、user_id、agent_name 三选一必填,不能同时传多个,也不能都不传。值为调用时在对应请求头中传入的原文字符串。每日模型金额及按 request-id 查询接口不受此规则限制。

聚合统计

GET /openapi/trace-usage/aggregate

curl -sS "http://127.0.0.1:9001/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 "http://127.0.0.1:9001/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每页条数

按 request-id 查询输入、输出与原始 usage

GET /openapi/request-logs?request_id=...

curl -sS --get "http://127.0.0.1:9001/openapi/request-logs" \
  -H "X-Access-Token: $ACCESS_TOKEN" \
  --data-urlencode "request_id=$REQUEST_ID"

request_id 必填,取网关响应头中的 x-request-id,不是上游请求 ID(Anthropic 响应头中的 request-id 可能是上游 ID);只接受一个非空值,最长 128 字符。无需传时间范围或 trace / user / agent 筛选参数。仅查询访问令牌所属租户,支持文本、图像、视频、音频和决策请求。

响应示例:

{
  "code": 0,
  "data": {
    "requestId": "req_example",
    "usageSource": "text",
    "userInputText": { "messages": [{ "role": "user", "content": "你好" }] },
    "responseText": { "choices": [{ "message": { "role": "assistant", "content": "你好!" } }] },
    "usage": { "prompt_tokens": 10, "completion_tokens": 2, "total_tokens": 12 }
  },
  "message": "success"
}

userInputText、responseText 为 Elasticsearch 中保存的请求、响应 JSON 快照;未保存、已过保留期或暂不可读取时返回 null。usage 来自数据库记录的上游原始计量,保留上游字段名和值,不使用平台计费字段反推;流式或轮询中的互补字段会合并,同名字段取最后一次非空值,不累加 tokens,未记录时为 null。

该接口所有业务响应的 HTTP 状态均为 200:code = 180001 表示参数不合法,180002 表示当前租户下不存在该请求(包含其他租户的请求),401 表示访问令牌缺失或无效。

每日模型调用金额

GET /-/openapi/usage/daily-by-model

使用相同的 X-Access-Token 鉴权,查询令牌所属账户每天、每个模型的调用金额。

curl -sS --get "http://127.0.0.1:9001/-/openapi/usage/daily-by-model" \
  -H "X-Access-Token: $ACCESS_TOKEN" \
  --data-urlencode "from=2026-11-01" \
  --data-urlencode "to=2026-11-08"
参数必填说明
from是起始日期,YYYY-MM-DD,北京时间,包含当天
to是结束日期,YYYY-MM-DD,北京时间,包含当天,不得早于 from
model_code否精确匹配请求模型代码,最长 256 字符;不传查询全部模型

响应示例(示例汇率为 100 credits/CNY):

{
  "code": 0,
  "data": {
    "timezone": "Asia/Shanghai",
    "currency": "CNY",
    "items": [
      { "date": "2026-11-01", "usageSource": "text", "modelCode": "gpt-4o-mini", "requests": 100, "estCredits": 1234, "amount": 12.34 }
    ]
  },
  "message": "success"
}

requests 包含成功和失败调用;usageSource 为 text / image / video / audio / decision,不同模态的同名模型分别统计。estCredits 沿用用量页面的计费估算,包含 Token 套餐调用计价,不等于钱包实扣流水。amount 使用系统当前主币种及汇率换算,保留两位小数,不是历史汇率快照。

仅包含已完成小时汇总的数据,当前小时及尚未完成的统计会延后出现。结果按日期、模态、模型代码升序返回,不分页、不截取前 100 个模型;无记录的日期或模型不补零,无匹配数据时 items 为 []。

所有业务响应均为 HTTP 200;缺少或重复参数、无效日期、倒序范围、空白或超长筛选值返回 code = 190001,访问令牌缺失或无效返回 401。

错误

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

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

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

相关