用量查询
查询你名下账号的调用记录、按模型/应用/时间筛选，以及导出。
本页描述的是你自己账号能看到的用量数据。为了保护交易各方的信息边界，用量数据的可见范围因角色而异（例如平台不会向你展示其它客户的调用记录，也不会向模型供应商展示某个客户具体付了多少钱）——本页只讲你作为调用方能看到什么。
一、查询调用记录
GET https://intertoken.ai/v1/api/v1/usage/records
排序：固定按发生时间倒序（最新在前），不可配置。
分页：
limit（可选）：返回条数，默认 20；服务端静默封顶 100（传更大的值不会报错，按 100 处理）offset（可选）：跳过的条数，默认 0- 过滤后的总条数在响应头
X-Total-Count中返回，响应体本身不含总数字段
过滤参数（均可选）：
| 参数 | 说明 |
|---|---|
spu_id | 按模型（SPU）过滤 |
sku_id | 按具体的模型规格（SKU，即实际计费/转发所命中的规格）过滤 |
from_date / to_date | 按发生时间过滤，格式 YYYY-MM-DD（UTC），to_date 含当日全天 |
app_id | 按应用过滤 |
client_key_id | 按 Client Key（ck-… 形式）过滤；非本人名下的 Client Key 一律返回空数组 |
plan_instance_id | 按套餐实例过滤；未使用套餐（直接扣余额）的记录此参数筛不到 |
取数范围：包含你名下 API Key 产生的记录，以及你拥有的应用名下 Client Key（SDK/客户端接入）产生的记录。不包含他人应用的记录。
尚不支持：按终端用户筛选——平台目前没有为终端用户维护持久化的标识。
响应字段（数组每项）
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 用量记录 ID |
trace_id | string | 该次调用的链路追踪 ID，反馈问题时提供给平台可用于定位 |
sku_id | string | 本次调用命中的模型规格 ID |
model_spu_name | string | 模型展示名 |
model_sku_name | string | 具体规格展示名（实际计费/转发使用的规格） |
prompt_tokens | integer | 输入 token 数（不含缓存命中部分） |
completion_tokens | integer | 输出 token 数 |
total_tokens | integer | 本次调用总 token 数（上游原始用量值；不保证等于输入+输出之和） |
cache_read_tokens | integer | 命中缓存被读取的 token 数（按缓存读价计费，通常低于原价） |
cache_write_tokens | integer | 写入缓存的 token 数（按缓存写价计费，通常高于原价——输入 token 很少但费用偏高的常见原因） |
cache_write_cost | number | 缓存写入部分的费用（USD），已包含在 total_cost 内 |
total_cost | number | 本次调用向你收取的总费用（USD），已含全部分项 |
video_tokens / video_input_count / video_resolution / video_cost | — | 视频生成相关的计费信息；非视频调用均为 0/null |
currency | string | 币种，固定 USD |
status | string | confirmed（已确认，可用于对账）/ pending（异步计费尚未落定）/ served_unbilled（已服务但未计费——本次调用真实发生、token 计入用量，但结算时账户余额不足以覆盖这笔费用，因此这笔不计入费用汇总、也不会扣款）。三态之外未来可能新增取值，请做好未知值兜底 |
charges | array | 本次调用的扣款分段，说明这笔费用从哪个钱包、以什么形态扣的；空数组代表平台本次未收费 |
price_source | string | 计费依据：plan（套餐额度）/ list（按平台指导价走余额）/ cache_storage（缓存存储时长费） |
plan_instance_id / plan_name | string / null | 命中的套餐实例与套餐名；未走套餐扣费时为 null |
created_at | string | 调用发生时间（ISO 8601） |
金额相关字段单位统一为美元（USD）。
status与price_source是开放枚举（status目前有confirmed/pending/served_unbilled三个已知取值），未来可能新增取值，请确保你的解析逻辑对未知值做降级展示而不是报错。
二、获取筛选项
GET https://intertoken.ai/v1/api/v1/usage/records/filters
返回你历史用量中出现过的模型列表，可直接用于构造上面接口的 spu_id/sku_id 参数（按调用次数降序，主力模型排在前面）。
三、用量趋势
GET https://intertoken.ai/v1/api/v1/usage/trends
按天/周/月等粒度对用量做聚合统计，用于绘制趋势图。聚合在服务端完成，不受 /records 接口 100 条的分页上限影响——如果你的调用量较大，趋势图请优先使用本接口而不是自行拉取明细做客户端聚合。
四、导出
GET https://intertoken.ai/v1/api/v1/usage/records/export
支持与 /records 相同的过滤参数（spu_id/sku_id/from_date/to_date/app_id/client_key_id），另加 fmt 参数选择格式：
fmt | 返回 |
|---|---|
json（默认） | application/json，文件名 usage_records.json |
csv | text/csv，文件名 usage_records.csv；金额列为定点小数文本（如 0.00000118，不会出现科学计数法） |
xlsx | Excel 文件，文件名 usage_records.xlsx；表头与部分取值为中文，金额为数值单元格 |
行数上限：单次导出固定上限，撞到上限时响应头会带 X-Export-Truncated: true——出现该响应头时说明还有更多数据未导出，请缩小时间范围分批导出。
列范围：导出的字段集合与查询接口略有差异（例如导出内容不含 price_source），但同样不会包含你账号可见范围之外的数据。每次导出平台会留存一条审计记录。