GET /api/v1/forward/usage/templates
查询指定时间窗口内当前账号的 Template 维度 Usage 汇总。
请求头
| Header | 是否必填 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer <PAT 或 SAT> |
查询参数
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| start_time | integer | 是 | - | Unix millisecond timestamp，时间窗口开始，包含。 |
| end_time | integer | 是 | - | Unix millisecond timestamp，时间窗口结束，不包含；必须大于 start_time，且时间跨度不超过 31 天。 |
| template_id | string | 否 | - | 按单个 Forward Template ID 过滤。 |
| template_ids | string/string[] | 否 | - | 按多个 Forward Template ID 过滤；支持逗号分隔或重复 query 参数。 |
| identity_id | string | 否 | - | 按单个 Forward Identity ID 过滤。 |
| identity_ids | string/string[] | 否 | - | 按多个 Forward Identity ID 过滤；支持逗号分隔或重复 query 参数。 |
示例请求
示例响应
HTTP 200 OK
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| type | string | 固定值 template_usage.list。 |
| start_time | integer | 请求时间窗口开始。 |
| end_time | integer | 请求时间窗口结束。 |
| data | array | Template 维度用量列表。 |
| data[].type | string | 固定值 template_usage。 |
| data[].template_id | string | Forward Template ID。 |
| data[].active_identities | integer | 当前 Template 下去重后的 Forward Identity 数量。 |
| data[].session_count | integer | Forward session 个数。 |
| data[].duration_seconds | integer | Forward session 运行时长汇总后换算为秒。 |
| data[].credits | number | Credit 按 session 汇总后的消耗，返回值保留两位小数；Credit 查询不可用时为 null。 |
错误
| HTTP | Type | Code | 触发条件 |
|---|---|---|---|
| 400 | invalid_request_error | - | 缺少 start_time / end_time，时间格式非法，end_time <= start_time，或时间跨度超过 31 天。 |
| 401 | authentication_error | authentication_required | PAT 或 SAT 无效或已过期。 |
| 500 | api_error | - | Forward session 查询或用量指标查询失败。 |