# 查询用量汇总

`GET` `/api/usage/summary`

按时间范围汇总当前应用的 Token 用量数据，包含总量、输入/输出/缓存/推理 Token 拆分、请求次数、失败次数和总耗时。时间区间为左闭右开（包含开始时间，不包含结束时间），单次查询跨度不超过90天。可通过 principalId 筛选指定身份主体的用量，通过 agentId 筛选指定智能体的用量，两者均可选且可组合使用。页面登录用户只能查询自身用量：不传 principalId 时自动按本人筛选，传入他人 principalId 返回 403。数据范围自动限定为当前应用，无法查询其他应用的数据。

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| startTime | string | 是 | 开始时间（包含），ISO格式，如 2026-08-01T00:00:00 |
| endTime | string | 是 | 结束时间（不包含），ISO格式，如 2026-08-08T00:00:00 |
| principalId | integer | 否 | 身份主体ID筛选条件（可选），应用模式不传时汇总应用下全部主体；页面登录用户固定为本人 |
| agentId | integer | 否 | 智能体ID筛选条件（可选），不传时汇总应用下全部智能体 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | UsageSummaryVO | 响应数据 |
|     totalTokens | integer | 区间内总Token消耗 |
|     promptTokens | integer | 输入Token消耗 |
|     completionTokens | integer | 输出Token消耗 |
|     cachedTokens | integer | 缓存命中Token消耗 |
|     reasoningTokens | integer | 推理Token消耗 |
|     requestCount | integer | 请求次数（成功+失败） |
|     errorCount | integer | 失败请求次数 |
|     totalDurationMs | 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处理 |