使用量 API

この統計 API の Lite / lite は過去の利用状況の検索・表示用であり、現在選択可能なモデルティアを示すものではありません。

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

Credits の利用イベントとサマリーをメンバーまたは組織単位で取得し、組織の Shared Add-on Credits、サービスアカウント専用 Credits パッケージ、シート·月残高バッチ明細および指定期間シート·月消費を照会します（シート·月バッチと消費はサードパーティチャネルで購入した組織のみ適用）。事前に API キーの取得 を完了し、共通仕様 を参照してください。

前提条件

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

概要

使用量 API は、日付、取得元、操作、モデルティアで絞り込めるメンバー単位の Credits 使用明細と集計を提供します。サービスアカウントの期間別使用量、組織単位の共有パッケージ、サービスアカウント専用 Credits パッケージ、シート·月残高バッチ、指定期間シート·月消費の照会にも対応し、ステータスや期間のフィルターとページネーションを利用できます。

主な機能

組織パッケージ一覧：組織共有パッケージの明細をページネーションで取得します。
サービスアカウントパッケージ一覧：組織内のサービスアカウント専用 Credits パッケージをページネーションで取得します。紐づけ先、有効期間、総クォータ、累積使用量、帳簿上の残高、消費の適用条件を含みます。
サービスアカウントの期間別使用量：利用可能な集計期間と、選択期間の Credits 使用量・上限をページネーションで取得します。

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 ミリ秒タイムスタンプ。開始・終了の両方を指定する場合、期間は 7 日以内
`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）

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

{
  "usages": [
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ab",
      "timestamp": 1719849600000,
      "beginAt": "2024-07-01T16:00:00Z",
      "finishAt": "2024-07-01T16:01:00.123Z",
      "userId": "user_abc123",
      "memberId": "member_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ac",
      "timestamp": 1719849500000,
      "beginAt": "2024-07-01T15:58:20Z",
      "finishAt": "2024-07-01T16:00:00.456Z",
      "userId": "user_abc123",
      "memberId": "member_abc123",
      "source": "CLI",
      "operation": "Completion",
      "credits": 0.02,
      "cost": 0.02
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}

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

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

{

  "usages": [],

  "maxResults": 20
}

nextToken が存在しない場合は最終ページです。

レスポンスフィールド

フィールド	型	説明
`usages`	array	使用量レコードリスト
`usages[].eventId`	string	集約使用量レコードの安定した一意の ID
`usages[].timestamp`	int64	開始時間（Unix ミリ秒タイムスタンプ）
`usages[].beginAt`	string	使用量イベントの開始時刻。UTC の RFC 3339 形式でミリ秒精度を保持し、`timestamp` と同じ時刻を表します。
`usages[].finishAt`	string	最新の報告に基づく使用量イベントの終了時刻。UTC の RFC 3339 形式でミリ秒精度を保持します。取得できない場合は省略されます。
`usages[].userId`	string	ユーザー ID
`usages[].memberId`	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	課金換算後のコスト。`billingCredits × billingFactor` を計算し、小数点以下 2 桁で切り捨て
`maxResults`	int32	このリクエストのページサイズ
`nextToken`	string	次ページカーソル。最終ページでは省略

同じイベントの新しい使用量が報告されると、finishAt が更新されることがあります。eventId と beginAt は変わりません。

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**）：

{
  "summary": {
    "IDE": 12.50,
    "CLI": 3.25
  }
}

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

{
  "summary": {
    "Agent": 8.40,
    "Completion": 5.10,
    "Inline Chat": 2.25
  }
}

使用量データなし：

{
  "summary": {}
}

レスポンスフィールド

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

エラーレスポンス

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

{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "startDate is required"
}

期間超過（400）

{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "date range must not exceed 7 days"
}

無効な groupBy（400）

{
  "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 ミリ秒タイムスタンプ。開始・終了の両方を指定する場合、期間は 7 日以内
`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）

{
  "usages": [
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ab",
      "timestamp": 1719849600000,
      "beginAt": "2024-07-01T16:00:00Z",
      "finishAt": "2024-07-01T16:01:00.123Z",
      "userId": "user_abc123",
      "memberId": "member_abc123",
      "userEmail": "user@example.com",
      "source": "IDE",
      "operation": "Agent",
      "modelTier": "Ultimate",
      "credits": 0.35,
      "cost": 0.35
    },
    {
      "eventId": "019c1234-5678-7abc-8def-0123456789ac",
      "timestamp": 1719849500000,
      "beginAt": "2024-07-01T15:58:20Z",
      "finishAt": "2024-07-01T16:00:00.456Z",
      "userId": "user_def456",
      "memberId": "member_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 一覧

組織共有パッケージとサービスアカウント専用 Credits パッケージの総クォータ、累積使用量、残高、有効期間を照会します。クォータダッシュボード、請求照合、残高通知に利用できます。

接続要件

対象組織の Organization API Key を使用し、HTTPS で呼び出します：

Authorization: Bearer <ORGANIZATION_API_KEY>
Accept: application/json

API キーの所属組織はパスの organization_id と一致する必要があります。両 API とも組織の認証情報が必要であり、個人やサービスアカウントの認証情報は使用できません。サービスアカウントパッケージの照会には、組織でサービスアカウント機能が有効になっている必要があります。以下の例では OpenAPI サービス URL を BASE_URL と表します。このサイトの接続先は https://api.qoder.com です。末尾に / を付けないでください。

メソッド	パス	対象
GET	`/v1/organizations/{organization_id}/resource-packages`	組織共有パッケージ
GET	`/v1/organizations/{organization_id}/service-accounts/resource-packages`	組織内のサービスアカウント専用 Credits パッケージ

2 種類のパッケージは別々に照会します。レスポンスはパッケージ明細であり、個人用パッケージやパッケージ横断の集計フィールドは含みません。

organization_id は必須の string 型パスパラメータです。
レスポンスは lowerCamelCase のフィールドを持つ JSON です。時刻は 2027-09-01T00:00:00Z などの UTC RFC 3339 文字列です。
クォータフィールドは小数を含む JSON number です。計算、保存、表示では精度を維持し、整数に丸めないでください。
成功時は HTTP 200 と Cache-Control: no-store を返します。デフォルトでは全ステータスを照会し、該当パッケージがなければ空配列を返します。

組織共有パッケージの照会

GET /v1/organizations/{organization_id}/resource-packages クエリパラメータ

パラメータ	型	必須	デフォルト	説明
`status`	string	いいえ	フィルターなし	`active`, `exhausted`, `expired`, `suspended`。大文字と小文字を区別しません
`orderBy`	string	いいえ	`expiresAt`	`expiresAt`, `activatedAt`, `remainingValue`
`order`	string	いいえ	`asc`	`asc`（昇順）または `desc`（降順）。大文字と小文字を区別しません
`maxResults`	integer	いいえ	20	ページサイズ。推奨値は 1～100。100 を超える値は 100、無効な値は 20 として扱います
`nextToken`	string	いいえ	なし	前のレスポンスのカーソル。初回は省略

ソート値が同じ場合は、order と同じ方向のパッケージ ID 順で並べます。デフォルトで期限切れ、使用済み、一時停止のレコードを含み、削除済みパッケージは返しません。 リクエスト例

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  -H 'Accept: application/json' \
  --data-urlencode 'status=active' \
  --data-urlencode 'orderBy=expiresAt' \
  --data-urlencode 'order=asc' \
  --data-urlencode 'maxResults=20'

成功レスポンス例

{
  "resourcePackages": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Organization Shared Credits Pack",
      "source": "purchased",
      "status": "active",
      "activatedAt": "2026-09-01T00:00:00Z",
      "expiresAt": "2027-09-01T00:00:00Z",
      "limitValue": 3000,
      "usedValue": 800.25,
      "remainingValue": 2199.75,
      "unit": "credits"
    }
  ],
  "maxResults": 20
}

パッケージフィールド

フィールド	型	説明
`id`	string	パッケージの一意の識別子
`name`	string	パッケージ名
`source`	string	取得元。値は次の表を参照
`status`	string	ステータス。「ステータスと使用量の定義」を参照
`activatedAt`	string	有効化時刻。存在しない場合は省略
`expiresAt`	string	有効期限
`limitValue`	number	パッケージの総クォータ
`usedValue`	number	パッケージの累積使用量
`remainingValue`	number	パッケージの帳簿上の残高
`unit`	string	クォータの単位（例：`credits`）。実際の戻り値を使用

`source`	意味
`purchased`	購入
`bonus`	運営による付与
`trial`	試用
`carryOver`	プランからの繰越
`refund`	返金補償による付与。取得元であり、返金ステータスではありません
`dev`	開発用途
`sales`	営業用途
`unknown`	認識できない取得元

サービスアカウントパッケージの照会

GET /v1/organizations/{organization_id}/service-accounts/resource-packages 組織内のサービスアカウント専用 big_model_credits パッケージを照会します。単位は常に credits です。 クエリパラメータ

パラメータ	型	必須	デフォルト	説明
`status`	string	いいえ	フィルターなし	`active`, `exhausted`, `expired`, `suspended`, `refunded`。大文字と小文字を区別しません
`maxResults`	integer	いいえ	20	ページサイズ。推奨値は 1～100。100 を超える値は 100、無効な値は 20 として扱います
`nextToken`	string	いいえ	なし	前のレスポンスのカーソル。初回は省略

有効期限、作成時刻、パッケージ ID の昇順で固定ソートします。ソート項目、期間、個別サービスアカウントによるフィルター指定はサポートしていません。 リクエスト例

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/service-accounts/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  -H 'Accept: application/json' \
  --data-urlencode 'status=active' \
  --data-urlencode 'maxResults=20'

成功レスポンス例

{
  "resourcePackages": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Service Account Credits Pack",
      "targetId": "",
      "quotaKey": "big_model_credits",
      "status": "active",
      "createdAt": "2026-09-01T00:00:00Z",
      "expiresAt": "2027-09-01T00:00:00Z",
      "limitValue": 300000,
      "usedValue": 12.75,
      "remainingValue": 299987.25,
      "unit": "credits",
      "applicabilityConditions": []
    }
  ],
  "maxResults": 20
}

パッケージフィールド

フィールド	型	説明
`id`	string	パッケージの一意の識別子
`name`	string	パッケージ名
`targetId`	string	空文字列の場合は組織内のサービスアカウントで専用パッケージを共有。それ以外は紐づくサービスアカウント ID
`quotaKey`	string	固定値 `big_model_credits`
`status`	string	ステータス。「ステータスと使用量の定義」を参照
`createdAt`	string	作成時刻
`expiresAt`	string	有効期限
`limitValue`	number	パッケージの総クォータ
`usedValue`	number	パッケージの累積使用量
`remainingValue`	number	パッケージの帳簿上の残高。最小値は 0
`unit`	string	固定値 `credits`
`applicabilityConditions`	array	消費の適用条件。空配列は消費ディメンションの制限なし
`applicabilityConditions[].dimension`	string	適用ディメンション名（例：`model`）
`applicabilityConditions[].allowedValues`	string[]	このディメンションで許可される値または一致式
`applicabilityConditions[].matchType`	string	`exact` は完全一致、`regex` は正規表現一致。認識できない場合は `unknown`

targetId が空のパッケージの累積使用量は、共有するサービスアカウント全体で発生したものであり、単一アカウントの消費量ではありません。サービスアカウントパッケージには source、activatedAt フィールドはありません。

ステータスと使用量の定義

ステータス	共有パッケージ	サービスアカウントパッケージ	意味
`active`	対応	対応	有効。有効期限とその他の消費条件も確認が必要
`exhausted`	対応	対応	クォータを使用済み
`expired`	対応	対応	期限切れ
`suspended`	対応	対応	一時停止
`refunded`	フィルター値として非対応	対応	返金済み。以後の消費を停止し、累積使用量は保持
`unknown`	返される場合あり	返される場合あり	認識できない状態。クエリパラメータとして指定不可

usedValue はパッケージのライフサイクル全体の累積消費量です。当日の使用量ではなく、組織のサブスクリプション周期でリセットされません。日別、メンバー別、サービスアカウント別の消費明細は提供しません。 remainingValue は帳簿上の未消費クォータであり、現在消費できることを保証しません。期限切れ、一時停止、返金済みのパッケージは残高があっても使用できません。有効なパッケージも紐づけ先、適用条件、予算などの制限を受けます。ステータス更新には遅延が生じる場合があるため、status と expiresAt の両方で有効性を確認してください。残高通知では status=active で絞り込み、有効期間と適用範囲を確認します。パッケージ横断の集計では全ページを取得し、単位と集計範囲を揃えてください。累積使用量は総クォータを超える場合があります。戻り値をそのまま使用し、usedValue を limitValue で切り捨てないでください。

ページネーション

両 API は同じレスポンス構造を使用します：

フィールド	型	説明
`resourcePackages`	array	現在のページのパッケージ一覧。該当なしの場合は `[]`
`maxResults`	integer	今回のリクエストで実際に適用されたページサイズ
`nextToken`	string	省略可能な次ページのカーソル。省略または空の場合は終了

初回リクエストでは nextToken を省略します。
空でない nextToken が返された場合は、同じ API の次のリクエストにそのまま渡します。
ページ取得中は組織、フィルター、ソートパラメータ、maxResults を変更しません。
カーソルはサーバーが生成する不透明な文字列です。自分で生成や解析をせず、クエリパラメータは URL エンコードしてください。
リクエスト間のスナップショットは提供されません。取得中の追加、状態や使用量の変更が結果に影響する場合があります。データを更新するには最初から照会し直してください。

2 ページ目のリクエスト例：

curl --get "${BASE_URL}/v1/organizations/${ORGANIZATION_ID}/service-accounts/resource-packages" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  --data-urlencode 'status=active' \
  --data-urlencode 'maxResults=20' \
  --data-urlencode "nextToken=${NEXT_TOKEN}"

該当レコードがない場合のレスポンス：

{
  "resourcePackages": [],
  "maxResults": 20
}

エラー処理

エラーレスポンスには requestId、code、message が含まれ、一部では details も返されます。調査のため HTTP ステータスと requestId を保持してください。

{
  "requestId": "req-example-001",
  "code": "BadRequest",
  "message": "invalid nextToken"
}

HTTP ステータス	主な原因	対処方法
400	無効な `status`、`nextToken`、または共有パッケージの `orderBy`	パラメータを修正し、カーソルが無効な場合は最初から照会
401	認証情報の欠落または認証失敗	Organization API Key の有効性を確認
403	別組織へのアクセス、組織以外の認証情報、またはサービスアカウント機能が未有効	組織 ID、認証情報の種類、機能を確認。機能不足時は `OrganizationPlanCapabilityForbidden` が返される場合あり
500	サービス内部エラー	`requestId` を保持して後で再試行。継続する場合はサポートに連絡
503	サービスが一時的に利用不可	バックオフを使用して再試行

パッケージが存在しない場合やフィルター結果が空の場合は正常な結果として、HTTP 200 と空配列を返します。

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

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

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）

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

{
  "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 が返されない場合があります。統合時はオプションフィールドとして処理してください。

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

{
  "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 を合計してください：

利用可能バッチ = 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）

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

pageToken パラメータ無効（400）

{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "invalid pageToken"
}

ステータス説明

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

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

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

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

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

計算式

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)

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

{
  "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 になります。

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

{
  "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)

{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "periodStart is required"
}

periodEnd パラメータ欠落 (400)

{
  "requestId": "req_def456",
  "code": "BadRequest",
  "message": "periodEnd is required"
}

時刻形式無効 (400)

{
  "requestId": "req_ghi789",
  "code": "BadRequest",
  "message": "invalid periodStart, must be RFC3339"
}

時間範囲無効 (400)

{
  "requestId": "req_jkl012",
  "code": "BadRequest",
  "message": "periodStart must be before periodEnd"
}

口径説明

マーケットプレイス報告口径 この API はマーケットプレイスの認賬/報告用の実際の純消費を返します。組織内部の報告不要なシート·月レコード（テスト、贈呈等）はレスポンスに含まれません。 返還控除口径 メンバーが当該期間中に削除され、その期間に Credits を使用していない場合、システムは対応するシート·月を組織残高に返還します。以下の条件を満たす返還はメンバーの当該期間消費から控除されます：

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

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

7. サービスアカウントの期間別使用量を照会

選択した集計期間のサービスアカウントの Credits 使用量と上限を取得します。使用量ダッシュボードや過去の使用量の確認に利用できます。対象組織の Organization API Key を使用してください。組織でサービスアカウントが有効になっている必要があります。パスパラメーター organization_id は必須です。

利用可能な集計期間の一覧

GET /v1/organizations/{organization_id}/service-accounts/usage/periods 組織に存在するサービスアカウントの集計期間を、終了時刻、開始時刻の降順で返します。最新の期間が先頭になります。期間がない場合は 200 OK と {"periods":[]} を返します。

curl --get "https://api.qoder.com/v1/organizations/${ORGANIZATION_ID}/service-accounts/usage/periods" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}"

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

periodStart と periodEnd は UTC の RFC 3339 文字列で、小数秒を最大 9 桁まで保持します。一覧で返された両方の境界値をそのまま指定してください。小数秒の切り捨てや月単位の再計算は不要です。各期間は開始時刻を含み、終了時刻を含みません。

集計期間を指定してサービスアカウントを取得

GET /v1/organizations/{organization_id}/service-accounts

パラメーター	型	必須	説明
`periodStart`	string	いいえ	RFC 3339 形式の開始時刻。`periodEnd` と同時に指定
`periodEnd`	string	いいえ	RFC 3339 形式の終了時刻。`periodStart` と同時に指定
`status`	string	いいえ	現在の状態：`active` または `archived`。省略時は状態で絞り込まない
`keyword`	string	いいえ	名前または説明のキーワード。最大 500 文字
`maxResults`	integer	いいえ	ページサイズ。既定値 20、最大 100
`nextToken`	string	いいえ	前のレスポンスで返されたページネーションカーソル

期間を省略すると、管理コンソールのサービスアカウント一覧と同様に、利用可能な最新の期間を選択します。期間がない場合は、現在の上限と現在の期間の使用量を含むアカウント一覧を返し、selectedPeriod は省略します。開始時刻と終了時刻を明示する場合、組織に存在するサービスアカウントの集計期間と一致する必要があります。任意の時間範囲の使用量を集計するパラメーターではありません。 リクエスト例

curl --get "https://api.qoder.com/v1/organizations/${ORGANIZATION_ID}/service-accounts" \
  -H "Authorization: Bearer ${ORGANIZATION_API_KEY}" \
  --data-urlencode "periodStart=2026-09-01T00:00:00.123456789Z" \
  --data-urlencode "periodEnd=2026-10-01T00:00:00.123456789Z" \
  --data-urlencode "status=active" \
  --data-urlencode "maxResults=20"

成功レスポンス（200 OK） 以下の例は、期間別使用量に関連するフィールドを示しています。

{
  "serviceAccounts": [
    {
      "id": "sa_abc123",
      "organizationId": "org_xxx",
      "name": "CI Automation",
      "status": "active",
      "limitAmount": -1,
      "usedAmount": 125.5
    }
  ],
  "maxResults": 20,
  "selectedPeriod": {
    "periodStart": "2026-09-01T00:00:00.123456789Z",
    "periodEnd": "2026-10-01T00:00:00.123456789Z"
  }
}

フィールド	型	説明
`serviceAccounts`	array	サービスアカウント一覧。一致するアカウントがない場合は空配列
`serviceAccounts[].id`	string	サービスアカウント ID
`serviceAccounts[].name`	string	現在のサービスアカウント名
`serviceAccounts[].status`	string	現在の状態：`active` または `archived`
`serviceAccounts[].usedAmount`	number	選択した期間の累積 Credits 使用量。使用量がない場合は `0`
`serviceAccounts[].limitAmount`	number	選択した期間の Credits 上限。`-1` は無制限、`0` は凍結。過去の上限がない場合は `-1`
`selectedPeriod`	object	`periodStart` と `periodEnd` を含む選択期間。期間がない場合は省略
`maxResults`	integer	ページサイズ
`nextToken`	string	次ページのカーソル。次ページがない場合は省略

期間を選択し、status を省略した場合、現在有効なアカウントと、その期間に正の使用量があるアーカイブ済みアカウントを返します。status=archived でも、選択期間に正の使用量があるアーカイブ済みアカウントのみを返します。名前、説明、状態は現在の値で、過去のスナップショットではありません。使用量は非同期で加算されるため、反映まで短い遅延が生じる場合があります。使用量が設定上限を超えることもあります。この API は期間別使用量の確認用で、請求明細の代わりにはなりません。 nextToken でページを進める場合、期間、状態、キーワード、maxResults を変更しないでください。最初のリクエストで期間を省略した場合は、以降のページで selectedPeriod の両方の境界値を明示し、期間の切り替わりによる検索対象の変更を防いでください。 エラー処理 片方の期間境界のみの指定、無効な時刻、開始時刻以前の終了時刻、存在しない期間には 400 Bad Request を返します。認証情報がない場合は 401、別の組織へのアクセスやサービスアカウントが有効でない組織には 403 を返します。

使用例

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

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

日付範囲でフィルタ

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-07T23:59:59Z" \
  -H "Authorization: Bearer <api_key>"

組織使用量イベント一覧

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

ソースと操作でフィルタ

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>"

ソース別使用量サマリー

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>"

操作別使用量サマリー

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 一覧

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 のページネーション

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/resource-packages?status=active&orderBy=expiresAt&order=asc&maxResults=20&nextToken=eyJwYWdlIjogMn0%3D" \
  -H "Authorization: Bearer <api_key>"

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

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

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

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

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

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

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

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

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

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>"

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

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>"

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

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	サーバー内部エラー

エラーレスポンスの形式は共通仕様の エラーレスポンス を参照してください。

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

​前提条件

​概要

​主な機能

​API 一覧

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

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

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

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

​エラーレスポンス

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

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

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

​接続要件

​組織共有パッケージの照会

​サービスアカウントパッケージの照会

​ステータスと使用量の定義

​ページネーション

​エラー処理

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

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

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

​エラーレスポンス

​ステータス説明

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

​計算式

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

​エラーレスポンス

​口径説明

​7. サービスアカウントの期間別使用量を照会

​利用可能な集計期間の一覧

​集計期間を指定してサービスアカウントを取得

​使用例

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

​日付範囲でフィルタ

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

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

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

​操作別使用量サマリー

​組織 Shared Add-on Credits 一覧

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

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

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

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

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

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

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

​エラーコード

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

前提条件

概要

主な機能

API 一覧

1. 使用量イベント一覧

パスパラメータ

クエリパラメータ

成功レスポンス（200 OK）

レスポンスフィールド

2. 使用量サマリー取得

パスパラメータ

クエリパラメータ

成功レスポンス（200 OK）

レスポンスフィールド

エラーレスポンス

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

パスパラメータ

クエリパラメータ

成功レスポンス（200 OK）

レスポンスフィールド

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

接続要件

組織共有パッケージの照会

サービスアカウントパッケージの照会

ステータスと使用量の定義

ページネーション

エラー処理

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

パスパラメータ

クエリパラメータ

成功レスポンス（200 OK）

レスポンスフィールド

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

エラーレスポンス

ステータス説明

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

計算式

パスパラメータ

クエリパラメータ

成功レスポンス (200 OK)

レスポンスフィールド

エラーレスポンス

口径説明

7. サービスアカウントの期間別使用量を照会

利用可能な集計期間の一覧

集計期間を指定してサービスアカウントを取得

使用例

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

日付範囲でフィルタ

組織使用量イベント一覧

ソースと操作でフィルタ

ソース別使用量サマリー

操作別使用量サマリー

組織 Shared Add-on Credits 一覧

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

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

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

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

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

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

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

エラーコード