> ## 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.

# Template 別 Usage 照会

> Forward Template 単位で、セッション数・アクティブ Identity 数・利用時間・Credit 消費を照会します。

`GET /api/v1/forward/usage/templates`

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

## ヘッダー

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

## クエリパラメータ

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

## リクエスト例

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

## レスポンス例

**HTTP 200 OK**

```json theme={null}
{
  "type": "template_usage.list",
  "start_time": 1783267200000,
  "end_time": 1784476800000,
  "data": [
    {
      "type": "template_usage",
      "template_id": "tmpl_123",
      "active_identities": 8,
      "session_count": 42,
      "duration_seconds": 3600,
      "credits": 12.34
    }
  ]
}
```

## レスポンスフィールド

| フィールド                      | 型            | 説明                                                     |
| -------------------------- | ------------ | ------------------------------------------------------ |
| `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 セッション数。                                        |
| `data[].duration_seconds`  | integer      | CAS ターン明細の `duration_ms` を合算し秒に変換した値。                  |
| `data[].credits`           | number\|null | セッション単位で集計した Credit 消費。小数点以下 2 桁。Credit 照会不可時は `null`。 |

## エラーコード

| 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` になります。
* セッション候補は Forward `ca_forward_sessions` から取得され、独立した課金ファクトテーブルには依存しません。

## 関連

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

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