使用量 API

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

Credits の利用イベントとサマリーをメンバーまたは組織単位で取得し、組織の Shared Add-on Credits 明細を照会します。事前に API キーの取得 を完了し、共通仕様 を参照してください。

前提条件

対象組織に紐づく有効な 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）
`nextCredits`	string	いいえ	ページネーションカーソル

成功レスポンス（200 OK）

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

{
  "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,
  "nextCredits": "eyJwYWdlIjogMn0="
}

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

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

{

  "usages": [],

  "maxResults": 20
}

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

レスポンスフィールド

フィールド	型	説明
`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	このリクエストのページサイズ
`nextCredits`	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**）：

{
  "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 ミリ秒タイムスタンプ
`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": [
    {
      "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 あり、次ページあり：

{
  "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 なし / 最終ページ：

{

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

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

orderBy パラメータ無効（400）

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

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

{
  "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 を組み合わせて判断してください：

真の利用可能 = status == "active" AND expiresAt > now

使用例

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

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-30T23: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?nextToken=eyJwYWdlIjogMn0%3D" \
  -H "Authorization: Bearer <api_key>"

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

エラーコード

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

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

Documentation Index

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

​前提条件

​API 一覧

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

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

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

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

​エラーレスポンス

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

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

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

​パスパラメータ

​クエリパラメータ

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

​レスポンスフィールド

​エラーレスポンス

​ステータス説明

​使用例

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

​日付範囲でフィルタ

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

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

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

​操作別使用量サマリー

​組織 Shared Add-on Credits 一覧

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

​エラーコード

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

前提条件

API 一覧

1. 使用量イベント一覧

パスパラメータ

クエリパラメータ

成功レスポンス（200 OK）

レスポンスフィールド

2. 使用量サマリー取得

パスパラメータ

クエリパラメータ

成功レスポンス（200 OK）

レスポンスフィールド

エラーレスポンス

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

パスパラメータ

クエリパラメータ

成功レスポンス（200 OK）

レスポンスフィールド

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

パスパラメータ

クエリパラメータ

成功レスポンス（200 OK）

レスポンスフィールド

エラーレスポンス

ステータス説明

使用例

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

日付範囲でフィルタ

組織使用量イベント一覧

ソースと操作でフィルタ

ソース別使用量サマリー

操作別使用量サマリー

組織 Shared Add-on Credits 一覧

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

エラーコード