# 查询模型消耗排行

`GET` `/api/usage/modelRanking`

按模型维度聚合当前应用的 Token 消耗，按总消耗降序分页返回，每项包含总量、输入、缓存命中、输出 Token、请求次数、缓存命中率和消耗占比。时间区间为左闭右开（包含开始时间，不包含结束时间），单次查询跨度不超过90天。可通过 principalId 筛选指定身份主体的消耗，通过 agentId 筛选指定智能体的消耗，两者均可选且可组合使用。页面登录用户只能查询自身用量：不传 principalId 时自动按本人筛选，传入他人 principalId 返回 403。消耗占比的分母为当前筛选范围内全部模型的总消耗，因此逐页累加后占比之和为100%。数据范围自动限定为当前应用，无法查询其他应用的数据。

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| startTime | string | 是 | 开始时间（包含），ISO格式，如 2026-08-01T00:00:00 |
| endTime | string | 是 | 结束时间（不包含），ISO格式，如 2026-09-01T00:00:00 |
| principalId | integer | 否 | 身份主体ID筛选条件（可选），应用模式不传时统计应用下全部主体；页面登录用户固定为本人 |
| agentId | integer | 否 | 智能体ID筛选条件（可选），不传时统计应用下全部智能体 |
| page | integer | 否 | 页码，从1开始 |
| pageSize | integer | 否 | 每页记录数，取值范围1~100 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | PageResultModelRankingVO | 响应数据 |
|     items | array | 数据列表 |
|         model | string | 模型名称 |
|         totalTokens | integer | 区间内总Token消耗 |
|         promptTokens | integer | 区间内输入Token消耗 |
|         cachedTokens | integer | 区间内缓存命中Token消耗 |
|         completionTokens | integer | 区间内输出Token消耗 |
|         requestCount | integer | 区间内请求次数（成功+失败） |
|         cacheHitRate | number | 缓存命中率，即缓存命中Token占输入Token的比例，百分比保留1位小数；输入Token为0时返回0 |
|         percentage | number | 消耗占比，即该模型消耗占当前筛选范围内全部模型消耗的比例，百分比保留1位小数 |
|     total | integer | 总记录数 |
|     page | integer | 当前页码，从1开始 |
|     pageSize | integer | 每页大小 |
|     totalPages | integer | - |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |