用量与费用

用量

http

GET https://modelgo-web-api.modelgo.ai/api/openapi/v1/usage?from=2026-10-01&to=2026-10-23&granularity=day&group_by=model
Authorization: Bearer mgpat_xxxxxxxx

参数	说明
`from` / `to`	RFC3339 或 `YYYY-MM-DD`；默认当前 UTC 月
`granularity`	`hour` / `day` / `month`
`group_by`	`none` / `model` / `workspace` / `member` / `api_key`
`model` / `api_key_id` / `workspace_id`	过滤
`timezone`	仅支持 `UTC`

summary：请求数、成功数、错误数、输入/输出/缓存/推理 token、charged_amount、currency。

媒体用量用字典表达，例如 "media_units": {"image_count": 2, "video_seconds": 5}；文本调用不返回该字段。 series：按桶返回 request_count、success_count、error_count、tokens、input_tokens、output_tokens、cached_tokens、cache_write_tokens、reasoning_tokens、charged_amount；无数据的窗口返回完整零值桶。

data_as_of 为全局日志水位（最新事件时间，非请求时刻）；billing_as_of 为结算封口时间——该时间之前创建的会话都已终结，无在途会话时为当前时间；is_final=true 表示窗口结束至少 5 分钟后早于两侧水位，晚到的日志/结算不会再改变该窗口。

费用

http

GET https://modelgo-web-api.modelgo.ai/api/openapi/v1/cost?from=2026-10-01&to=2026-10-23
Authorization: Bearer mgpat_xxxxxxxx

默认返回 total_amount（权威值）与 input_amount / output_amount / cache_amount / other_amount。

另返回 media_amount / request_amount / discount_amount 三个预留分项；当前计价链路没有对应数据源，字段以 null 返回，且不参与 total_amount 对账。

结算状态

传 status=estimated|settled|pending|reversed 时改从 billing 账本读取对应状态的金额：

status	含义
`estimated`	窗口内全部调用的预授权报价之和
`settled`	已结算调用的实际扣费
`pending`	仍在途的预授权冻结
`reversed`	已冲正/释放的预授权金额

状态读取只返回 total_amount，不返回组件拆分。model / api_key_id / workspace_id 过滤对状态读取同样生效。

不传 X-Tenant-Id 时，用量与费用同样返回多租户列表；传了则返回单对象。