> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 按 Identity 查询 Usage

> 按 Forward Identity 维度查询当前账号下的 session 数、使用时长、Credit 消耗和 session 明细。

`GET /api/v1/forward/usage/identities`

该接口用于租户级用量查询，仅支持 Qoder PAT 鉴权。Identity AccessToken 面向单个 identity，不允许访问租户级用量数据。

## 请求头

| Header          | 是否必填 | 说明             |
| --------------- | ---- | -------------- |
| `Authorization` | 是    | `Bearer <PAT>` |

## 查询参数

| 参数             | 类型      | 是否必填 | 默认值 | 说明                                                                     |
| -------------- | ------- | ---- | --- | ---------------------------------------------------------------------- |
| `start_time`   | integer | 是    | -   | Unix millisecond timestamp，时间窗口开始，包含。                                  |
| `end_time`     | integer | 是    | -   | Unix millisecond timestamp，时间窗口结束，不包含；必须大于 `start_time`，且时间跨度不超过 31 天。 |
| `identity_id`  | string  | 否    | -   | 按单个 Forward Identity ID 过滤。                                            |
| `identity_ids` | string  | 否    | -   | 按多个 Forward Identity ID 过滤；支持逗号分隔或重复 query 参数。                         |
| `template_id`  | string  | 否    | -   | 按单个 Forward Template ID 过滤。                                            |
| `template_ids` | string  | 否    | -   | 按多个 Forward Template ID 过滤；支持逗号分隔或重复 query 参数。                         |

## 示例请求

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/usage/identities?start_time=1783267200000&end_time=1784476800000&identity_id=idn_123' \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "type": "identity_usage.list",
  "start_time": 1783267200000,
  "end_time": 1784476800000,
  "data": [
    {
      "type": "identity_usage",
      "identity_id": "idn_123",
      "session_count": 5,
      "duration_seconds": 420,
      "credits": 1.23,
      "session_ids": ["sess_1", "sess_2"]
    }
  ]
}
```

## 响应字段

| 字段                        | 类型           | 说明                                                           |
| ------------------------- | ------------ | ------------------------------------------------------------ |
| `type`                    | string       | 固定值 `identity_usage.list`。                                   |
| `start_time`              | integer      | 请求时间窗口开始。                                                    |
| `end_time`                | integer      | 请求时间窗口结束。                                                    |
| `data`                    | array        | Identity 维度用量列表。                                             |
| `data[].type`             | string       | 固定值 `identity_usage`。                                        |
| `data[].identity_id`      | string       | Forward Identity ID。                                         |
| `data[].session_count`    | integer      | Forward session 个数。                                          |
| `data[].duration_seconds` | integer      | CAS turn 明细 `duration_ms` 求和后换算为秒。                           |
| `data[].credits`          | number\|null | CAS credit 按 session 汇总后的消耗，返回值保留两位小数；credit 查询不可用时为 `null`。 |
| `data[].session_ids`      | string\[]    | 当前 Identity 维度下的 Forward session ID 列表。                      |

## 错误码

| HTTP | Type                    | 触发条件                                                                       |
| ---- | ----------------------- | -------------------------------------------------------------------------- |
| 400  | `invalid_request_error` | 缺少 `start_time` / `end_time`，时间格式非法，`end_time <= start_time`，或时间跨度超过 31 天。 |
| 401  | `authentication_error`  | PAT 无效或已过期，或使用 Identity AccessToken 访问租户级用量接口。                             |
| 500  | `api_error`             | Forward session 查询或 CAS session metrics 查询失败。                              |

## 备注

* 时间窗口使用半开区间：`created_at >= start_time` 且 `created_at < end_time`。
* 当 CAS credit 查询不可用时，接口仍返回 session 和时长统计，`credits` 字段为 `null`。
* `session_ids` 去重后按字典序返回。

## 相关

<CardGroup cols={2}>
  <Card title="按 Template 查询 Usage" icon="chart-bar" href="/zh/cloud-agents/api/forward/usage/list-template-usage" />

  <Card title="列出 Sessions" icon="message" href="/zh/cloud-agents/api/forward/sessions/list" />
</CardGroup>