> ## 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 単位で、セッション数・利用時間・Credit 消費・セッション明細を照会します。

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

テナントレベルの使用量照会用エンドポイントで、Qoder PAT 認証のみサポートします。Identity AccessToken は単一 Identity 向けであり、テナントレベルの使用量データへのアクセスは許可されません。

## ヘッダー

| Header          | 必須 | 説明             |
| --------------- | -- | -------------- |
| `Authorization` | はい | `Bearer <PAT>` |

## クエリパラメータ

| パラメータ          | 型       | 必須  | デフォルト | 説明                                                              |
| -------------- | ------- | --- | ----- | --------------------------------------------------------------- |
| `start_time`   | integer | はい  | -     | Unix ミリ秒タイムスタンプ。時間ウィンドウの開始（含む）。                                 |
| `end_time`     | integer | はい  | -     | Unix ミリ秒タイムスタンプ。時間ウィンドウの終了（含まない）。`start_time` より大きく、期間は 31 日以内。 |
| `identity_id`  | string  | いいえ | -     | 単一の Forward Identity ID でフィルタリング。                               |
| `identity_ids` | string  | いいえ | -     | 複数の Forward Identity ID でフィルタリング。カンマ区切りまたは繰り返しクエリパラメータをサポート。    |
| `template_id`  | string  | いいえ | -     | 単一の Forward Template ID でフィルタリング。                               |
| `template_ids` | string  | いいえ | -     | 複数の Forward Template ID でフィルタリング。カンマ区切りまたは繰り返しクエリパラメータをサポート。    |

## リクエスト例

```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 セッション数。                                        |
| `data[].duration_seconds` | integer      | CAS ターン明細の `duration_ms` を合算し秒に変換した値。                  |
| `data[].credits`          | number\|null | セッション単位で集計した Credit 消費。小数点以下 2 桁。Credit 照会不可時は `null`。 |
| `data[].session_ids`      | string\[]    | この Identity 下の Forward セッション 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 セッション照会または CAS セッションメトリクス照会に失敗。                                    |

## 備考

* 時間ウィンドウは半開区間：`created_at >= start_time` かつ `created_at < end_time`。
* CAS Credit 照会が不可能な場合でも、セッションと時間の統計は返却され、`credits` フィールドは `null` になります。
* `session_ids` は重複除去後、辞書順で返却されます。

## 関連

<CardGroup cols={2}>
  <Card title="Template 別 Usage 照会" icon="chart-bar" href="/ja/cloud-agents/api/forward/usage/list-template-usage" />

  <Card title="セッション一覧" icon="message" href="/ja/cloud-agents/api/forward/sessions/list" />
</CardGroup>