課金グループ API

課金グループ API は、メンバーの Credits 消費の帰属、統計期間の共有上限の設定、期間使用量の取得に使用します。1 人のメンバーは同時に最大 1 つの課金グループに所属します。

対象プラン：Enterprise。

呼び出す前に API キーの取得を完了し、OpenAPI 共通仕様を確認してください。

前提条件

Authorization: Bearer <api_key> を送信します。
JSON リクエストボディがある場合は Content-Type: application/json を送信します。
API キーに紐づく組織を organization_id に指定します。
メンバー割り当てリクエストには、組織メンバー ID ではなくユーザー ID を使用します。メンバー APIが返す userId フィールドから取得できます。

主な動作

Unassigned は、明示的な割り当てがないメンバー用の組み込み課金グループです。ID は固定文字列 unassigned です。
Unassigned の名前変更、削除、グループ上限の設定はできません。
メンバーの再割り当てで変わるのは現在の所属のみです。記録済みの使用量は、Credits 消費時に取得された課金グループに残ります。
課金グループを削除すると現在のメンバーは Unassigned に移動します。履歴使用量、削除済みグループ ID、最後に保存された名前は使用量 API から引き続き取得できます。
グループ上限と使用量の単位は Credits です。

データモデル

BillingGroup

フィールド	型	説明
`id`	string	課金グループ ID。組み込みグループは `unassigned`
`organizationId`	string	組織 ID
`name`	string	課金グループ名。組み込みグループは常に `Unassigned`
`description`	string	説明。空の場合は省略
`isUnassigned`	boolean	組み込み `Unassigned` グループかどうか
`memberCount`	integer	現在グループに割り当てられているメンバー数
`limitAmount`	number	期間の Credits 上限。`-1` は無制限、`0` は凍結
`currentUsed`	number	選択期間の Credits 使用量。設定上限を超える場合があります
`isBlocked`	boolean	選択期間の使用量が 0 以上の上限に到達または超過したか
`creatorId`	string	作成者のユーザー ID。取得できない場合は省略
`createdAt`	string	作成日時（ISO 8601）。取得できない場合は省略
`updatedAt`	string	最終更新日時（ISO 8601）。取得できない場合は省略

使用期間

使用期間は半開区間です。periodStart を含み、periodEnd は含みません。

フィールド	型	説明
`periodStart`	string	期間開始（ISO 8601）
`periodEnd`	string	期間終了（ISO 8601）

API リファレンス

課金グループ一覧

GET /v1/organizations/{organization_id}/billing-groups

クエリパラメーター	型	必須	説明
`periodEnd`	string	いいえ	RFC 3339 形式の正確な期間終了。省略すると現在または最新期間を使用
`keyword`	string	いいえ	課金グループ名、または現在のメンバー名・メールアドレスを検索
`maxResults`	integer	いいえ	1 ページあたりの通常課金グループ数。デフォルト 20、最大 100
`nextToken`	string	いいえ	前回のレスポンスで返されたカーソル

最初のページでは、生成された Unassigned 行が先頭に追加されます。この行は maxResults に含まれないため、最初のページは最大 maxResults + 1 件を返す場合があります。keyword 指定時は、名前または現在のメンバーが一致する場合にのみ Unassigned が含まれます。

成功レスポンス（200 OK）

{
  "billingGroups": [
    {
      "id": "unassigned",
      "organizationId": "org_xxx",
      "name": "Unassigned",
      "isUnassigned": true,
      "memberCount": 4,
      "limitAmount": -1,
      "currentUsed": 320,
      "isBlocked": false
    },
    {
      "id": "9bcb59cb-07e6-4a2d-9655-56aaf16b0e34",
      "organizationId": "org_xxx",
      "name": "Platform",
      "description": "Platform cost center",
      "isUnassigned": false,
      "memberCount": 12,
      "limitAmount": 10000,
      "currentUsed": 4250,
      "isBlocked": false,
      "creatorId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-08-01T08:00:00Z",
      "updatedAt": "2026-08-10T09:30:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response",
  "selectedPeriod": {
    "periodStart": "2026-08-01T00:00:00Z",
    "periodEnd": "2026-09-01T00:00:00Z"
  }
}

selectedPeriod は、各グループの currentUsed と isBlocked に使用された期間です。期間がない場合は省略されます。limitAmount は現在の設定であり、履歴スナップショットではありません。履歴期間を選択した場合、isBlocked は現在の上限と選択期間の使用量を比較します。最終ページでは nextToken が省略されます。トークンは不透明な値として扱ってください。

課金グループの作成

POST /v1/organizations/{organization_id}/billing-groups name は前後の空白が除去され、空にはできません。有効な課金グループ名は一意である必要があります。大文字・小文字に関係なく Unassigned は予約名です。

リクエストボディ

{
  "name": "Platform",
  "description": "Platform cost center"
}

フィールド	型	必須	説明
`name`	string	はい	課金グループ名
`description`	string	いいえ	課金グループの説明

作成された BillingGroup を 201 Created で返します。新しい課金グループのデフォルトは limitAmount: -1（無制限）です。グループ作成、上限設定、メンバー割り当ては、トランザクションで結合されない別々のリクエストです。返されたグループ ID を保存し、失敗した手順から再開してください。

課金グループの更新

PUT /v1/organizations/{organization_id}/billing-groups/{billing_group_id} 省略したフィールドは変更されません。空の description で説明を消去できます。組み込み Unassigned グループは更新できません。

リクエストボディ

{
  "name": "Platform Engineering",
  "description": ""
}

フィールド	型	必須	説明
`name`	string	いいえ	新しい名前。前後の空白を除去した後に空にはできません
`description`	string	いいえ	新しい説明。空文字列で消去

更新された BillingGroup を 200 OK で返します。

課金グループの削除

DELETE /v1/organizations/{organization_id}/billing-groups/{billing_group_id} 組み込み Unassigned グループは削除できません。他の課金グループを削除すると、現在のメンバーは Unassigned に移動します。履歴使用量には billingGroupId が保持され、削除済みグループの最後に保存された名前が解決されます。 200 OK を返します：

{}

課金グループ上限の設定

POST /v1/organizations/{organization_id}/billing-groups/{billing_group_id}/limit 各使用期間に適用される共有 Credits 上限を設定します。フィールドの省略による意図しない凍結を防ぐため、limitAmount は必須です。新しい値は後続の Credits 消費に直ちに適用されます。

リクエストボディ

{
  "limitAmount": 10000
}

サポートされる値：

`limitAmount`	意味
`-1`	無制限
`0`	グループを凍結
`0` より大きい	期間の Credits 上限

上限はソフトな実行しきい値です。記録済み使用量が上限に達すると、組織の共有 Credits プールからの後続消費がブロックされます。実行中・同時実行の消費や記録の遅延により、currentUsed が limitAmount を超える場合があるため、厳密なハードキャップとして扱わないでください。現在の使用量以下に上限を下げると、後続消費がブロックされます。組み込み Unassigned グループには上限を設定できません。更新された BillingGroup を 200 OK で返します。

1 メンバーの割り当て

POST /v1/organizations/{organization_id}/billing-groups/assign 1 人の組織メンバーを割り当て、または再割り当てします。billingGroupId を unassigned にすると、明示的な課金グループ割り当てを解除できます。

リクエストボディ

{
  "userId": "550e8400-e29b-41d4-a716-446655440001",
  "billingGroupId": "9bcb59cb-07e6-4a2d-9655-56aaf16b0e34"
}

フィールド	型	必須	説明
`userId`	string	はい	組織メンバーのユーザー UUID
`billingGroupId`	string	はい	対象課金グループ ID、または `unassigned`

200 OK を返します：

{}

Unassigned メンバーの一括解決

POST /v1/organizations/{organization_id}/billing-groups/resolve Unassigned のメンバーを 1 つの通常課金グループに移動します。1 メンバー割り当て API と異なり、すでに別の通常課金グループに所属するメンバーは再割り当てしません。バッチ全体を失敗させず、部分成功の詳細を返します。

リクエストボディ

{
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "billingGroupId": "9bcb59cb-07e6-4a2d-9655-56aaf16b0e34"
}

userIds には 1 リクエストあたり 1～100 件のユーザー ID が必要で、重複値は含めないでください。billingGroupId には通常課金グループを指定し、unassigned は指定できません。

成功レスポンス（200 OK）

{
  "succeeded": 1,
  "failed": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440002",
      "reason": "not_unassigned"
    }
  ]
}

失敗理由	意味
`not_found`	ユーザーが存在しない
`not_in_org`	ユーザーが現在の組織メンバーではない
`not_unassigned`	メンバーがすでに通常課金グループに所属している

課金グループメンバー一覧

GET /v1/organizations/{organization_id}/billing-groups/{billing_group_id}/members 明示的な課金グループ割り当てがないメンバーを取得するには、billing_group_id に unassigned を指定します。

クエリパラメーター	型	必須	説明
`keyword`	string	いいえ	メンバー名またはメールアドレスを検索
`maxResults`	integer	いいえ	ページサイズ。デフォルト 20、最大 100
`nextToken`	string	いいえ	前回のレスポンスで返されたカーソル

成功レスポンス（200 OK）

{
  "members": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Alice",
      "email": "alice@example.com"
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

email は取得できない場合に省略され、nextToken は最終ページで省略されます。現在のメンバーがいない課金グループ ID は、未知の ID を含めて、空の members 配列を 200 OK で返します。

課金グループ使用量の取得

GET /v1/organizations/{organization_id}/billing-groups/usage 課金グループ、ユーザー、使用期間ごとに 1 つの集計行を返します。行のキーは (billingGroupId, userId, periodStart, periodEnd) です。1 人のメンバーが同じ期間に 2 つの課金グループで Credits を消費した場合、そのユーザーには 2 行が返されます。Credits 消費時に帰属が固定されるため、メンバーの再割り当てや課金グループの削除後も履歴行は移動しません。

クエリパラメーター	型	必須	説明
`billingGroupId`	string	いいえ	課金グループ ID または `unassigned`。省略すると全グループを返す
`periodEnd`	string	いいえ	RFC 3339 形式の正確な期間終了。省略すると現在または最新期間を使用
`maxResults`	integer	いいえ	ページサイズ。デフォルト 20、最大 100
`nextToken`	string	いいえ	前回のレスポンスで返されたカーソル

使用期間一覧で返された periodEnd を使用してください。既知の期間と正確に一致しないタイムスタンプでは、レスポンスが空になる場合があります。削除済み課金グループを照会するには、保持された ID を billingGroupId に指定します。削除済みグループは課金グループ一覧には表示されないため、フィルターなしの使用量レスポンスから ID を取得してください。名前変更は履歴行に解決される名前にも反映されるため、名前ではなく billingGroupId で集計してください。

成功レスポンス（200 OK）

{
  "rows": [
    {
      "billingGroupId": "9bcb59cb-07e6-4a2d-9655-56aaf16b0e34",
      "billingGroupName": "Platform",
      "isUnassigned": false,
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "memberName": "Alice",
      "email": "alice@example.com",
      "periodStart": "2026-08-01T00:00:00Z",
      "periodEnd": "2026-09-01T00:00:00Z",
      "billingCycle": "monthly",
      "usedCredits": 1250
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

行フィールド	型	説明
`billingGroupId`	string	使用量記録時に取得された課金グループ ID
`billingGroupName`	string	現在または最後に保存された課金グループ名。論理削除済みグループも解決され、名前変更は履歴表示にも反映されます
`isUnassigned`	boolean	使用量が `Unassigned` に帰属したか
`userId`	string	ユーザー ID
`memberName`	string	メンバー名
`email`	string	メールアドレス。空の場合があります
`periodStart`	string	期間開始（ISO 8601）。使用量行では常に返されます
`periodEnd`	string	期間終了（ISO 8601）。使用量行では常に返されます
`billingCycle`	string	`monthly`、`yearly` など、この使用量行の課金サイクル
`usedCredits`	number	この期間にユーザーと課金グループに帰属した Credits

使用期間一覧

GET /v1/organizations/{organization_id}/billing-groups/usage/periods 組織で現在利用可能なすべての期間を新しい順に返します。使用量がない場合も現在のプラン月が含まれます。この API はページ分割されませんが、履歴期間の無期限保持を保証するものではありません。

成功レスポンス（200 OK）

{
  "periods": [
    {
      "periodStart": "2026-08-01T00:00:00Z",
      "periodEnd": "2026-09-01T00:00:00Z"
    },
    {
      "periodStart": "2026-07-01T00:00:00Z",
      "periodEnd": "2026-08-01T00:00:00Z"
    }
  ]
}

エラー

エラーは OpenAPI 共通仕様で説明する標準レスポンス形式を使用します。

HTTP ステータス	エラーコード	主な原因
400	`BadRequest`	不正なリクエスト、RFC 3339 日時、必須フィールド不足、または `Unassigned` に対する未対応操作
401	`Unauthorized`	API キーがない、または無効
403	`Forbidden`	API キーが対象組織に属していない
404	`NotFound`	操作対象の課金グループまたはメンバーが存在しない
409	`AlreadyExists`	同名の有効な課金グループがすでに存在する

メンバー一覧 API は、未知の課金グループ ID に対して空の一覧を返します。存在確認で NotFound が必要な場合は、操作 API を使用してください。

​前提条件

​主な動作

​データモデル

​BillingGroup

​使用期間

​API リファレンス

​課金グループ一覧

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

​課金グループの作成

​リクエストボディ

​課金グループの更新

​リクエストボディ

​課金グループの削除

​課金グループ上限の設定

​リクエストボディ

​1 メンバーの割り当て

​リクエストボディ

​Unassigned メンバーの一括解決

​リクエストボディ

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

​課金グループメンバー一覧

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

​課金グループ使用量の取得

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

​使用期間一覧

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

​エラー

前提条件

主な動作

データモデル

BillingGroup

使用期間

API リファレンス

課金グループ一覧

成功レスポンス（200 OK）

課金グループの作成

リクエストボディ

課金グループの更新

リクエストボディ

課金グループの削除

課金グループ上限の設定

リクエストボディ

1 メンバーの割り当て

リクエストボディ

Unassigned メンバーの一括解決

リクエストボディ

成功レスポンス（200 OK）

課金グループメンバー一覧

成功レスポンス（200 OK）

課金グループ使用量の取得

成功レスポンス（200 OK）

使用期間一覧

成功レスポンス（200 OK）

エラー