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

# 使用量 API

> メンバーおよび組織レベルの Credits 使用イベント、集計、および Shared Add-on Credits・シート·月残高バッチ・指定期間シート·月消費の照会。

## このドキュメントについて

**Credits** の利用イベントとサマリーをメンバーまたは組織単位で取得し、組織の Shared Add-on Credits、シート·月残高バッチ明細および指定期間シート·月消費を照会します（シート·月バッチと消費はサードパーティチャネルで購入した組織のみ適用）。事前に **[API キーの取得](/ja/account/teams/openapi/get-api-key)** を完了し、**[共通仕様](/ja/account/teams/openapi/conventions)** を参照してください。

### 前提条件

* 対象組織に紐づく有効な API キー。

## API 一覧

### 1. 使用量イベント一覧

`GET /v1/organizations/{organization_id}/members/{member_id}/usage-events`

指定メンバーの集計済み Credits 使用量レコードをページネーションで取得します。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明      |
| ----------------- | ------ | -- | ------- |
| `organization_id` | string | はい | 組織 ID   |
| `member_id`       | string | はい | メンバー ID |

#### クエリパラメータ

| パラメータ        | 型       | 必須  | 説明                                                                                                                                                                                                          |
| ------------ | ------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startDate`  | string  | いいえ | 開始時間；RFC 3339 形式または Unix ミリ秒タイムスタンプ                                                                                                                                                                         |
| `endDate`    | string  | いいえ | 終了時間；RFC 3339 形式または Unix ミリ秒タイムスタンプ                                                                                                                                                                         |
| `sources`    | string  | いいえ | ソースでフィルタ、カンマ区切り。値：`IDE`、`CLI`、`JetBrains Plugin`、`Web`、`QoderWork`                                                                                                                                          |
| `operations` | string  | いいえ | 操作でフィルタ、カンマ区切り。値：`Inline Chat`、`Ask`、`Agent`、`Repo Wiki`、`Quest`、`Plan Mode`、`Code Review`、`Optimize Input`、`Voice Input`、`Experts`、`Image`                                                                 |
| `modelTiers` | string  | いいえ | モデルティアでフィルタ、カンマ区切り。値：`Auto`、`Performance`、`Efficient`、`Lite`、`Ultimate`、`Vision`、`Qwen-Coder-Qoder-1.0`、`Kimi-K2.5`、`GLM-5`、`MiniMax-M2.5`、`DeepSeek-V4.0`、`Qwen3.5-Plus`、`Standard`、`Premium`、`Enterprise` |
| `maxResults` | integer | いいえ | ページサイズ（デフォルト 20、最大 100）                                                                                                                                                                                     |
| `nextToken`  | string  | いいえ | ページネーションカーソル                                                                                                                                                                                                |

#### 成功レスポンス（200 OK）

**使用量レコードあり、次ページあり：**

```json theme={null}
{
  "usages": [
    {
      "timestamp": 1719849600000,
      "userId": "user_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "timestamp": 1719849500000,
      "userId": "user_abc123",
      "source": "CLI",
      "operation": "Completion",
      "credits": 0.02,
      "cost": 0.02
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}
```

> 一部のレコードでは `userEmail` や `modelTier` が**返されない**場合があります。インテグレーション時はオプションフィールドとして処理してください。

**使用量レコードなし / 最終ページ：**

```json theme={null}
{

  "usages": [],

  "maxResults": 20
}
```

> `nextToken` が空または存在しない場合は最終ページです。

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

| フィールド                | 型       | 説明                                                                                                                                                                                                    |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `usages`             | array   | 使用量レコードリスト                                                                                                                                                                                            |
| `usages[].timestamp` | int64   | 開始時間（Unix ミリ秒タイムスタンプ）                                                                                                                                                                                 |
| `usages[].userId`    | string  | ユーザー ID                                                                                                                                                                                               |
| `usages[].userEmail` | string  | ユーザーメール（空の場合あり）                                                                                                                                                                                       |
| `usages[].source`    | string  | ソース：`IDE`、`CLI`、`JetBrains Plugin`、`Web`、`QoderWork`                                                                                                                                                  |
| `usages[].operation` | string  | 操作：`Inline Chat`、`Ask`、`Agent`、`Repo Wiki`、`Quest`、`Plan Mode`、`Code Review`、`Optimize Input`、`Voice Input`、`Experts`、`Image`                                                                         |
| `usages[].modelTier` | string  | モデルティア（空の場合あり）：`Auto`、`Performance`、`Efficient`、`Lite`、`Ultimate`、`Vision`、`Qwen-Coder-Qoder-1.0`、`Kimi-K2.5`、`GLM-5`、`MiniMax-M2.5`、`DeepSeek-V4.0`、`Qwen3.5-Plus`、`Standard`、`Premium`、`Enterprise` |
| `usages[].credits`   | float64 | 消費 Credits（小数点以下2桁）                                                                                                                                                                                   |
| `usages[].cost`      | float64 | 課金換算後のコスト（小数点以下2桁）；通常 `credits` と同額または固定換算比率                                                                                                                                                          |
| `maxResults`         | int32   | このリクエストのページサイズ                                                                                                                                                                                        |
| `nextToken`          | string  | 次ページカーソル；空は最終ページ                                                                                                                                                                                      |

***

### 2. 使用量サマリー取得

`GET /v1/organizations/{organization_id}/members/{member_id}/usage-summary`

指定された期間内のメンバーの Credits 消費を指定ディメンションで集計します。期間は 7 日以内でなければなりません。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明      |
| ----------------- | ------ | -- | ------- |
| `organization_id` | string | はい | 組織 ID   |
| `member_id`       | string | はい | メンバー ID |

#### クエリパラメータ

| パラメータ       | 型      | 必須 | 説明                                              |
| ----------- | ------ | -- | ----------------------------------------------- |
| `startDate` | string | はい | 開始時間；RFC 3339 形式または Unix ミリ秒タイムスタンプ             |
| `endDate`   | string | はい | 終了時間；RFC 3339 形式または Unix ミリ秒タイムスタンプ             |
| `groupBy`   | string | はい | グループ化ディメンション：`source`（ソース別）または `operation`（操作別） |

#### 成功レスポンス（200 OK）

**ソース別集計（**`**groupBy=source**`**）：**

```json theme={null}
{
  "summary": {
    "IDE": 12.50,
    "CLI": 3.25
  }
}
```

**操作別集計（**`**groupBy=operation**`**）：**

```json theme={null}
{
  "summary": {
    "Agent": 8.40,
    "Completion": 5.10,
    "Inline Chat": 2.25
  }
}
```

**使用量データなし：**

```json theme={null}
{
  "summary": {}
}
```

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

| フィールド           | 型       | 説明                                   |
| --------------- | ------- | ------------------------------------ |
| `summary`       | object  | 集計結果；キーはグループ名（ソースまたは操作）、値は合計 Credits |
| `summary.{key}` | float64 | そのグループの合計 Credits 消費（小数点以下2桁）        |

#### エラーレスポンス

**必須パラメータ欠落（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "startDate is required"
}
```

**期間超過（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "date range must not exceed 7 days"
}
```

**無効な groupBy（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "groupBy is required and must be 'source' or 'operation'"
}
```

### 3. 組織使用量イベント一覧

`GET /v1/organizations/{organization_id}/usage-events`

指定組織の全メンバーの集計済みトークン使用量レコードをページネーションで取得します。レスポンス構造はメンバー使用量イベント API と同一です。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明    |
| ----------------- | ------ | -- | ----- |
| `organization_id` | string | はい | 組織 ID |

#### クエリパラメータ

| パラメータ        | 型       | 必須  | 説明                                                                                                                                                                                                          |
| ------------ | ------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startDate`  | string  | いいえ | 開始時間；RFC 3339 形式または Unix ミリ秒タイムスタンプ                                                                                                                                                                         |
| `endDate`    | string  | いいえ | 終了時間；RFC 3339 形式または Unix ミリ秒タイムスタンプ                                                                                                                                                                         |
| `sources`    | string  | いいえ | ソースでフィルタ、カンマ区切り。値：`IDE`、`CLI`、`JetBrains Plugin`、`Web`、`QoderWork`                                                                                                                                          |
| `operations` | string  | いいえ | 操作でフィルタ、カンマ区切り。値：`Inline Chat`、`Ask`、`Agent`、`Repo Wiki`、`Quest`、`Plan Mode`、`Code Review`、`Optimize Input`、`Voice Input`、`Experts`                                                                         |
| `modelTiers` | string  | いいえ | モデルティアでフィルタ、カンマ区切り。値：`Auto`、`Performance`、`Efficient`、`Lite`、`Ultimate`、`Vision`、`Qwen-Coder-Qoder-1.0`、`Kimi-K2.5`、`GLM-5`、`MiniMax-M2.5`、`DeepSeek-V4.0`、`Qwen3.5-Plus`、`Standard`、`Premium`、`Enterprise` |
| `maxResults` | integer | いいえ | ページサイズ（デフォルト 20、最大 100）                                                                                                                                                                                     |
| `nextToken`  | string  | いいえ | ページネーションカーソル                                                                                                                                                                                                |

#### 成功レスポンス（200 OK）

```json theme={null}
{
  "usages": [
    {
      "timestamp": 1719849600000,
      "userId": "user_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "timestamp": 1719849500000,
      "userId": "user_def456",
      "source": "CLI",
      "operation": "Ask",
      "credits": -0.02,
      "cost": -0.02
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}
```

> 一部のレコードでは `userEmail` や `modelTier` が**返されない**場合があります。デフォルトではメンバー使用量イベント API と同じ動作をし、正の Credits レコードのみをフィルタしません。返金や修正などの負の値のレコードも返される場合があります。

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

レスポンスフィールドの定義は「1. 使用量イベント一覧」と同一です。

### 4. 組織共有 Shared Add-on Credits 一覧

`GET /v1/organizations/{organization_id}/resource-packages`

組織単位ですべての Shared Add-on Credits 明細をページネーションで返します。レスポンスには各パッケージのバッチ情報のみが含まれ、集計は含まれません（必要な場合はクライアント側で `limitValue` / `usedValue` / `remainingValue` を合計してください）。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明    |
| ----------------- | ------ | -- | ----- |
| `organization_id` | string | はい | 組織 ID |

#### クエリパラメータ

| パラメータ        | 型       | 必須  | 説明                                                                                 |
| ------------ | ------- | --- | ---------------------------------------------------------------------------------- |
| `status`     | string  | いいえ | ステータスでフィルタ。値：`active`、`exhausted`、`expired`、`suspended`。未指定時は組織下の削除されていない全パッケージを返却 |
| `orderBy`    | string  | いいえ | ソートフィールド。値：`expiresAt`（デフォルト）、`activatedAt`、`remainingValue`                       |
| `order`      | string  | いいえ | ソート方向。値：`asc`（デフォルト）、`desc`                                                        |
| `maxResults` | integer | いいえ | ページサイズ（デフォルト 20、最大 100）                                                            |
| `nextToken`  | string  | いいえ | 前回レスポンスの `nextToken` フィールドからのページネーションカーソル                                          |

#### 成功レスポンス（200 OK）

**Shared Add-on Credits あり、次ページあり：**

```json theme={null}
{
  "resourcePackages": [
    {
      "id": "pkg-001",
      "name": "Enterprise Annual Pack",
      "source": "purchased",
      "status": "active",
      "activatedAt": "2025-01-01T00:00:00Z",
      "expiresAt": "2026-01-01T00:00:00Z",
      "limitValue": 3000.0,
      "usedValue": 800.0,
      "remainingValue": 2200.0,
      "unit": "credits"
    },
    {
      "id": "pkg-002",
      "name": "Trial Pack",
      "source": "trial",
      "status": "exhausted",
      "activatedAt": "2025-03-15T00:00:00Z",
      "expiresAt": "2025-09-15T00:00:00Z",
      "limitValue": 500.0,
      "usedValue": 500.0,
      "remainingValue": 0.0,
      "unit": "credits"
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}
```

> 一部のパッケージでは `activatedAt` が**返されない**場合があります（例：未アクティベートのバッチ）。インテグレーション時はオプションフィールドとして処理してください。

**Shared Add-on Credits なし / 最終ページ：**

```json theme={null}
{

  "resourcePackages": [],

  "maxResults": 20
}
```

> `nextToken` が空または存在しない場合は最終ページです。

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

| フィールド                               | 型       | 説明                                                                                                              |
| ----------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `resourcePackages`                  | array   | Shared Add-on Credits リスト                                                                                       |
| `resourcePackages[].id`             | string  | Shared Add-on Credits の一意 ID                                                                                    |
| `resourcePackages[].name`           | string  | Shared Add-on Credits 名                                                                                         |
| `resourcePackages[].source`         | string  | クレジットのソース：`purchased`（購入）、`bonus`（贈呈）、`trial`（トライアル）、`carryOver`（繰り越し）、`refund`（返金）、`dev`（開発/テスト）、`sales`（営業設定） |
| `resourcePackages[].status`         | string  | クレジットステータス：`active`（有効）、`exhausted`（使い切り）、`expired`（期限切れ）、`suspended`（一時停止）                                     |
| `resourcePackages[].activatedAt`    | string  | アクティベーション時刻（RFC 3339 / ISO 8601 形式、UTC、空の場合あり）                                                                  |
| `resourcePackages[].expiresAt`      | string  | 有効期限（RFC 3339 / ISO 8601 形式、UTC）                                                                                |
| `resourcePackages[].limitValue`     | float64 | 初期総額度                                                                                                           |
| `resourcePackages[].usedValue`      | float64 | 消費済み額度                                                                                                          |
| `resourcePackages[].remainingValue` | float64 | 残り額度（= `limitValue - usedValue`）                                                                                |
| `resourcePackages[].unit`           | string  | 額度単位、通常は `credits`                                                                                              |
| `maxResults`                        | int32   | このリクエストのページサイズ                                                                                                  |
| `nextToken`                         | string  | 次ページカーソル。最終ページの場合は返されません                                                                                        |

#### エラーレスポンス

**status パラメータ無効（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "invalid status, must be one of: active, exhausted, expired, suspended"
}
```

**orderBy パラメータ無効（400）**

```json theme={null}
{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "invalid orderBy field, must be one of: expiresAt, activatedAt, remainingValue"
}
```

**組織が存在しないまたはアクセス権なし（404）**

```json theme={null}
{
  "requestId": "req_jkl012",
  "code": "NotFound",
  "message": "organization not found or not accessible"
}
```

#### ステータス説明

Shared Add-on Credits のステータスマシン：

| ステータス       | 説明      | 遷移条件                                                                          |
| ----------- | ------- | ----------------------------------------------------------------------------- |
| `active`    | 有効、消費可能 | アクティベーション後のデフォルトステータス                                                         |
| `exhausted` | 使い切り    | 残り額度がゼロ（注意：**使い切ったパッケージは期限切れでも自動的に** `expired` **にはなりません**。`exhausted` のまま維持） |
| `expired`   | 期限切れ    | 毎時のスケジュールタスクが期限切れの `active` パッケージを `expired` に変更                              |
| `suspended` | 一時停止    | 管理者による手動操作、停止中は消費不可                                                           |

`expired` ステータスは毎時の非同期タスクにより更新されるため、**実際の期限切れからステータス変更まで**最大約 1 時間のウィンドウ期間があります。この期間中、パッケージの `status` は `active` のままですが `expiresAt < now` となります。正確な「真の利用可能」判定には、**クライアント側で** `status` **と** `expiresAt` **を組み合わせて判断**してください：

```text theme={null}
真の利用可能 = status == "active" AND expiresAt > now
```

### 5. 組織シート·月残高バッチ一覧

<Note>
  この API はサードパーティチャネル（例：マーケットプレイス引き換えコード）で購入した組織のみに適用されます。
</Note>

`GET /v1/organizations/{organization_id}/seat-month-batches`

組織単位でシート·月残高バッチ明細をページネーションで取得します。レスポンスには各バッチの詳細情報のみが含まれ、合計は返されません。

シート·月残高はメンバー統計の `remainingSeats` とは異なります。`remainingSeats` は非サードパーティチャネルで購入した組織にのみ適用され、購入済みシートの残り利用可能数を示します。シート·月残高は組織に残る消費可能なシート·月バッチ数を示します。組織はシート·月残高を複数回チャージでき、各バッチには独立した残量と有効期限があります。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明    |
| ----------------- | ------ | -- | ----- |
| `organization_id` | string | はい | 組織 ID |

#### クエリパラメータ

| パラメータ       | 型       | 必須  | 説明                                                                 |
| ----------- | ------- | --- | ------------------------------------------------------------------ |
| `status`    | string  | いいえ | ステータスでフィルタ。値：`active`、`exhausted`、`expired`、`refunded`。省略時は全バッチを返却 |
| `pageSize`  | integer | いいえ | ページサイズ（デフォルト 100、最大 500）                                           |
| `pageToken` | string  | いいえ | ページネーションカーソル。前回レスポンスの `nextToken` を渡す                              |

#### 成功レスポンス（200 OK）

**バッチあり、次ページあり：**

```json theme={null}
{
  "seatMonthBatches": [
    {
      "id": "batch-001",
      "redemptionCodeId": "rc-001",
      "status": "active",
      "sourceChannel": "REDEMPTION_CODE",
      "thirdPartyInstanceId": "inst_xxx",
      "productCode": "qoder_team_seat_month",
      "reportRequired": true,
      "totalSeatMonths": 120.0,
      "usedSeatMonths": 30.0,
      "remainingSeatMonths": 90.0,
      "effectiveAt": "2026-06-01T00:00:00Z",
      "expiresAt": "2026-09-01T00:00:00Z",
      "createdAt": "2026-06-01T00:00:00Z",
      "updatedAt": "2026-06-10T00:00:00Z"
    },
    {
      "id": "batch-002",
      "redemptionCodeId": "rc-002",
      "status": "exhausted",
      "sourceChannel": "ANNUAL_RETURN",
      "totalSeatMonths": 30.0,
      "usedSeatMonths": 30.0,
      "remainingSeatMonths": 0.0,
      "effectiveAt": "2026-05-01T00:00:00Z",
      "expiresAt": "2026-08-01T00:00:00Z",
      "createdAt": "2026-05-01T00:00:00Z",
      "updatedAt": "2026-05-20T00:00:00Z"
    }
  ],
  "pageSize": 100,
  "nextToken": "2"
}
```

> 一部のバッチでは `redemptionCodeId`、`sourceChannel`、`thirdPartyInstanceId`、`productCode` が**返されない**場合があります。統合時はオプションフィールドとして処理してください。

**バッチなし / 最終ページ：**

```json theme={null}
{
  "seatMonthBatches": [],
  "pageSize": 100
}
```

> `nextToken` が存在しない場合は最終ページです。ページネーション時はレスポンスの `nextToken` を次のリクエストの `pageToken` にそのまま渡してください。

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

| フィールド                                     | 型       | 説明                                                 |
| ----------------------------------------- | ------- | -------------------------------------------------- |
| `seatMonthBatches`                        | array   | シート·月残高バッチリスト                                      |
| `seatMonthBatches[].id`                   | string  | バッチ ID                                             |
| `seatMonthBatches[].redemptionCodeId`     | string  | 関連引き換えコードレコード ID（平文コードではない）、空の場合あり                 |
| `seatMonthBatches[].status`               | string  | バッチステータス：`active`、`exhausted`、`expired`、`refunded` |
| `seatMonthBatches[].sourceChannel`        | string  | ソースチャネル（例：引き換えコード、年間返還、マーケットプレイス）、空の場合あり           |
| `seatMonthBatches[].thirdPartyInstanceId` | string  | サードパーティインスタンス ID、空の場合あり                            |
| `seatMonthBatches[].productCode`          | string  | サードパーティ商品コード、空の場合あり                                |
| `seatMonthBatches[].reportRequired`       | boolean | マーケットプレイス使用量報告が必要か                                 |
| `seatMonthBatches[].totalSeatMonths`      | float64 | このバッチの元のシート·月総量                                    |
| `seatMonthBatches[].usedSeatMonths`       | float64 | このバッチの消費済みシート·月                                    |
| `seatMonthBatches[].remainingSeatMonths`  | float64 | このバッチの残りシート·月                                      |
| `seatMonthBatches[].effectiveAt`          | string  | 有効開始時刻（RFC 3339 / ISO 8601 形式、UTC）                 |
| `seatMonthBatches[].expiresAt`            | string  | 有効期限（RFC 3339 / ISO 8601 形式、UTC）                   |
| `seatMonthBatches[].createdAt`            | string  | 作成時刻（RFC 3339 / ISO 8601 形式、UTC）                   |
| `seatMonthBatches[].updatedAt`            | string  | 更新時刻（RFC 3339 / ISO 8601 形式、UTC）                   |
| `pageSize`                                | int32   | このリクエストのページサイズ                                     |
| `nextToken`                               | string  | 次ページカーソル。最終ページの場合は返されません                           |

#### 現在利用可能なシート·月残高の計算方法

API は合計残高を直接返しません。以下の条件でバッチをフィルタし、`remainingSeatMonths` を合計してください：

```text theme={null}
利用可能バッチ = status == "active"
                   AND effectiveAt <= now
                   AND expiresAt > now
                   AND remainingSeatMonths > 0
```

例えば 3 つのバッチが返された場合：

| バッチ | ステータス       | 残りシート·月 | 有効開始 | 有効期限 | 利用可能残高に加算 |
| --- | ----------- | ------- | ---- | ---- | --------- |
| A   | `active`    | 90.0    | 有効済み | 未期限  | はい        |
| B   | `exhausted` | 0.0     | 有効済み | 未期限  | いいえ       |
| C   | `active`    | 20.0    | 未有効  | 未期限  | いいえ       |

現在利用可能なシート·月合計残高は `90.0` です。

#### エラーレスポンス

**status パラメータ無効（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "invalid status, must be one of: active, exhausted, expired, refunded"
}
```

**pageToken パラメータ無効（400）**

```json theme={null}
{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "invalid pageToken"
}
```

#### ステータス説明

| ステータス       | 説明   | 遷移条件                                 |
| ----------- | ---- | ------------------------------------ |
| `active`    | 有効中  | バッチ作成後のデフォルト。まだ使い切り・期限切れ・返金無効になっていない |
| `exhausted` | 使い切り | バッチ残量がゼロ                             |
| `expired`   | 期限切れ | システムの期限切れ回収後に遷移                      |
| `refunded`  | 返金無効 | 返金または無効化フローで遷移                       |

期限切れステータスはバックグラウンドタスクにより非同期で更新されるため、実際の期限切れからステータス変更まで遅延が生じる可能性があります。「現在利用可能か」を正確に判定するには、`status`、`effectiveAt`、`expiresAt`、`remainingSeatMonths` を総合的に判断してください。

### 6. 指定期間シート·月消費照会

<Note>
  この API はサードパーティチャネル（例：マーケットプレイス引き換えコード）で購入した組織のみに適用されます。返されるのはマーケットプレイスの認賬/報告用の実際の純消費であり、組織内部のすべてのシート·月トランザクションではありません。
</Note>

`GET /v1/organizations/{organization_id}/seat-month-usages`

組織単位で指定期間範囲内のメンバーシート·月消費をページネーションで取得します。レスポンスはメンバーと請求期間で集約され、シート·月バッチ明細は返されません。

#### 計算式

```text theme={null}
netSeatMonths = max(consumedSeatMonths - refundedSeatMonths, 0)
```

| フィールド                | 説明                            |
| -------------------- | ----------------------------- |
| `consumedSeatMonths` | 当該期間にメンバーが原始消費したシート·月         |
| `refundedSeatMonths` | 当該期間に返還され、元のシート・期間に帰属できるシート·月 |
| `netSeatMonths`      | メンバーの当該期間の実際純消費               |

> 履歴境界：API のリリース時刻は 2026-06-24T16:00:00Z です。この時刻以前は一部の期間情報が不足しているためデータの完全性を保証できません。リリース後の期間計算を基準としてください。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明    |
| ----------------- | ------ | -- | ----- |
| `organization_id` | string | はい | 組織 ID |

#### クエリパラメータ

| パラメータ         | 型       | 必須  | 説明                                               |
| ------------- | ------- | --- | ------------------------------------------------ |
| `periodStart` | string  | はい  | 期間範囲開始時刻、RFC 3339 形式、例 `2026-06-01T00:00:00Z`    |
| `periodEnd`   | string  | はい  | 期間範囲終了時刻、RFC 3339 形式、`periodStart` より後である必要があります |
| `memberId`    | string  | いいえ | 組織メンバー ID でフィルタ                                  |
| `userId`      | string  | いいえ | ユーザー ID でフィルタ                                    |
| `pageSize`    | integer | いいえ | ページサイズ（デフォルト 100、最大 500）                         |
| `pageToken`   | string  | いいえ | ページネーションカーソル。前回レスポンスの `nextToken` を渡してください       |

> 結果には `periodStart >= リクエスト periodStart` かつ `periodEnd <= リクエスト periodEnd` を満たす完全な請求期間のみが含まれます。実際の請求期間境界でクエリすることをお勧めします。

#### 成功レスポンス (200 OK)

**消費レコードあり、次ページあり：**

```json theme={null}
{
  "seatMonthUsages": [
    {
      "memberId": "member_abc123",
      "userId": "user_abc123",
      "periodStart": "2026-06-01T00:00:00Z",
      "periodEnd": "2026-07-01T00:00:00Z",
      "consumedSeatMonths": 20.0,
      "refundedSeatMonths": 5.0,
      "netSeatMonths": 15.0
    },
    {
      "memberId": "member_def456",
      "userId": "user_def456",
      "periodStart": "2026-06-01T00:00:00Z",
      "periodEnd": "2026-07-01T00:00:00Z",
      "consumedSeatMonths": 1.0,
      "refundedSeatMonths": 1.0,
      "netSeatMonths": 0.0
    }
  ],
  "pageSize": 100,
  "nextToken": "2"
}
```

> 全額返還後、`netSeatMonths` が `0` になる場合があります。例えばメンバーにシートが割り当てられた後、Credits を使用せずに削除された場合、シート·月が組織に返還され、当該期間の純消費は 0 になります。

**消費レコードなし / 最終ページ：**

```json theme={null}
{
  "seatMonthUsages": [],
  "pageSize": 100
}
```

> `nextToken` が返されない場合は最終ページです。レスポンスの `nextToken` を次のリクエストの `pageToken` として渡してください。

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

| フィールド                                  | 型       | 説明                              |
| -------------------------------------- | ------- | ------------------------------- |
| `seatMonthUsages`                      | array   | メンバーシート·月消費リスト                  |
| `seatMonthUsages[].memberId`           | string  | 組織メンバー ID                       |
| `seatMonthUsages[].userId`             | string  | ユーザー ID                         |
| `seatMonthUsages[].periodStart`        | string  | 請求期間開始時刻、RFC 3339 / ISO 8601 形式 |
| `seatMonthUsages[].periodEnd`          | string  | 請求期間終了時刻、RFC 3339 / ISO 8601 形式 |
| `seatMonthUsages[].consumedSeatMonths` | float64 | 当該期間にメンバーが原始消費したシート·月           |
| `seatMonthUsages[].refundedSeatMonths` | float64 | 当該期間に返還されたシート·月                 |
| `seatMonthUsages[].netSeatMonths`      | float64 | 当該期間の実際純消費シート·月                 |
| `pageSize`                             | int32   | このリクエストのページサイズ                  |
| `nextToken`                            | string  | 次ページカーソル。最終ページの場合は返されません        |

#### エラーレスポンス

**periodStart パラメータ欠落 (400)**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "periodStart is required"
}
```

**periodEnd パラメータ欠落 (400)**

```json theme={null}
{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "periodEnd is required"
}
```

**時刻形式無効 (400)**

```json theme={null}
{
  "requestId": "req_ghi789",
  "code": "BadRequest",
  "message": "invalid periodStart, must be RFC3339"
}
```

**時間範囲無効 (400)**

```json theme={null}
{
  "requestId": "req_jkl012",
  "code": "BadRequest",
  "message": "periodStart must be before periodEnd"
}
```

#### 口径説明

**マーケットプレイス報告口径**

この API はマーケットプレイスの認賬/報告用の実際の純消費を返します。組織内部の報告不要なシート·月レコード（テスト、贈呈等）はレスポンスに含まれません。

**返還控除口径**

メンバーが当該期間中に削除され、その期間に Credits を使用していない場合、システムは対応するシート·月を組織残高に返還します。以下の条件を満たす返還はメンバーの当該期間消費から控除されます：

| 条件      | 説明                                |
| ------- | --------------------------------- |
| 同一組織    | 返還レコードが同一組織に属する                   |
| 同一シート割当 | 返還レコードが元のシート割当 ID に関連付け可能         |
| 同一請求期間  | 返還レコードが元の期間開始・終了時刻を保持             |
| 返還タイプ   | 返還トランザクションが `REFUND` / `INCREASE` |

**ソートとページネーション**

結果は `periodStart` 降順（新しい期間が先）、`memberId` 昇順、`userId` 昇順でソートされます。ページネーションにはレスポンスの `nextToken` を使用してください。`nextToken` が返されない場合は次ページがありません。

***

## 使用例

### メンバー使用量イベント一覧

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?maxResults=20" \
  -H "Authorization: Bearer <api_key>"
```

### 日付範囲でフィルタ

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?startDate=2025-06-01T00:00:00Z&endDate=2025-06-30T23:59:59Z" \
  -H "Authorization: Bearer <api_key>"
```

### 組織使用量イベント一覧

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/usage-events?maxResults=20" \
  -H "Authorization: Bearer <api_key>"
```

### ソースと操作でフィルタ

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-events?sources=IDE&operations=Ask,Agent" \
  -H "Authorization: Bearer <api_key>"
```

### ソース別使用量サマリー

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-summary?startDate=2026-03-13T00:00:00Z&endDate=2026-03-20T00:00:00Z&groupBy=source" \
  -H "Authorization: Bearer <api_key>"
```

### 操作別使用量サマリー

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/usage-summary?startDate=2026-03-13T00:00:00Z&endDate=2026-03-20T00:00:00Z&groupBy=operation" \
  -H "Authorization: Bearer <api_key>"
```

### 組織 Shared Add-on Credits 一覧

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/resource-packages?status=active&orderBy=expiresAt&order=asc&maxResults=20" \
  -H "Authorization: Bearer <api_key>"
```

### Shared Add-on Credits のページネーション

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/resource-packages?nextToken=eyJwYWdlIjogMn0%3D" \
  -H "Authorization: Bearer <api_key>"
```

> `nextToken` には URL 予約文字が含まれる場合があります。クエリパラメータとして渡す際は URL エンコードしてください（例：`=` → `%3D`）。

### 組織シート·月残高バッチ一覧

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?pageSize=100" \
  -H "Authorization: Bearer <api_key>"
```

### 有効中のシート·月残高バッチのみ取得

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?status=active&pageSize=100" \
  -H "Authorization: Bearer <api_key>"
```

### シート·月バッチのページネーション

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-batches?pageToken=2" \
  -H "Authorization: Bearer <api_key>"
```

> `pageToken` は前ページレスポンスの `nextToken` です。

### 指定期間のシート·月消費照会

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-07-01T00:00:00Z&pageSize=100" \
  -H "Authorization: Bearer <api_key>"
```

### メンバー別シート·月消費照会

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-07-01T00:00:00Z&memberId=member_xxx&pageSize=100" \
  -H "Authorization: Bearer <api_key>"
```

### シート·月消費のページネーション

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/seat-month-usages?periodStart=2026-06-01T00:00:00Z&periodEnd=2026-08-01T00:00:00Z&pageSize=20&pageToken=2" \
  -H "Authorization: Bearer <api_key>"
```

> `pageToken` は前ページレスポンスの `nextToken` です。

***

## エラーコード

| エラーコード          | HTTP ステータス | 説明                                                                                                             |
| --------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
| `BadRequest`    | 400        | リクエストパラメータが無効（例：member\_id が空、日付形式が不正、期間超過、groupBy が無効、status が無効、pageToken が無効、periodStart/periodEnd 欠落または無効） |
| `Unauthorized`  | 401        | API キーが欠落または無効                                                                                                 |
| `Forbidden`     | 403        | この組織へのアクセス権限なし                                                                                                 |
| `NotFound`      | 404        | リソースが見つからない                                                                                                    |
| `InternalError` | 500        | サーバー内部エラー                                                                                                      |

エラーレスポンスの形式は [共通仕様](/ja/account/teams/openapi/conventions) の **エラーレスポンス** を参照してください。