logo
Development
概要開発スペースワークスペースAPI Referenceベストプラクティス更新履歴
検索
日本語
API Reference / アナリティクスAPI / 組織のクレジット使用量分布を取得
組織のクレジット使用量分布を取得
最終更新日：14日前

組織のクレジット使用量分布を取得

Agent / Workflow ごとに組織のクレジットまたはトークンの占有比ランキング、および日別、週別、月別の傾向を取得できます。Agent のみ、または Workflow のみを見ることも可能です。

注意：最大で 92 日間のデータを照会可能です；開発スペースのみ統計対象で、統計範囲は下記「統計基準」を参照してください。

リクエスト方法

GET

呼び出し先

https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution

呼び出し認証

アカウントレベルの DevKey / DevSecret を使った Basic 認証：Authorization: Basic ${BASIC_TOKEN}。なお ${BASIC_TOKEN} は DevKey:DevSecret の Base64 エンコードです。

  • 呼び出しアカウントは org_id に対応する組織のメンバーであり、「使用量閲覧」権限を持っている必要があります（組織オーナー、管理者はデフォルトで権限あり）。
  • 組織が所在するデータセンターのアドレスを呼び出してください。${endpoint} は 組織一覧の照会 で返される region を使用します（SG → sg、TH → th、JP → jp）。他のデータセンターを呼び出すと「その組織のメンバーではありません」と返されます。

呼び出し頻度

  • 各開発者キーによるこの API 呼び出しは、1 分あたり最大 10 回までです。
  • 各呼び出しは同時に組織プランの「統計用 API」の1分あたりのクオータにもカウントされ、Agent API Key による統計用インターフェース呼び出しとクオータを共有します。
  • 検索結果は 10 分間キャッシュされます。毎日一度の呼び出しが推奨されます。

リクエスト

リクエスト例

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \ -H 'Authorization: Basic ${BASIC_TOKEN}'
                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'
このコードブロックをポップアップで表示

リクエストヘッダー

フィールド タイプ 説明
Authorization Basic ${BASIC_TOKEN} DevKey:DevSecret を Base64 した後の Basic トークンを使用。

リクエストパラメータ

フィールド タイプ 必須 説明
org_id String はい 組織 ID。
start_time Long はい 開始時間、ミリ秒タイムスタンプ。組織のタイムゾーンに従って当日の0時まで拡張。
end_time Long はい 終了時間（含まず）、ミリ秒タイムスタンプ。開始日と終了日は最大92日間。
metric String いいえ CREDITS（クレジット、デフォルト）または TOKENS。
granularity String いいえ トレンドの時間粒度：DAY（デフォルト）、WEEK（週の月曜日始まり）、MONTH。
agent_type String いいえ AGENT は Agent のみ、WORKFLOW は Workflow のみ。指定しない場合は両方をランキング。
top_n Integer いいえ トレンドシリーズで保持する件数、1 から 50、デフォルトは 50。残りは OTHER にまとめられる。

レスポンス

レスポンス例

{ "code": 0, "message": "OK", "data": { "timezone": "+07:00", "data_since": "2026-10-15", "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"], "total": 812.4411, "series": [ { "row_type": "ITEM", "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "total": 402.1200, "share": 49.49, "points": [130.5000, 141.0200, 130.6000] }, { "row_type": "OTHER", "agent_id": null, "name": null, "agent_type": null, "total": 410.3211, "share": 50.51, "points": [120.1000, 150.2000, 140.0211] } ], "ranking": [ { "row_type": "ITEM", "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "total": 402.1200, "share": 49.49 } ] } }
                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "timezone": "+07:00",
        "data_since": "2026-10-15",
        "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"],
        "total": 812.4411,
        "series": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49,
                "points": [130.5000, 141.0200, 130.6000]
            },
            {
                "row_type": "OTHER",
                "agent_id": null,
                "name": null,
                "agent_type": null,
                "total": 410.3211,
                "share": 50.51,
                "points": [120.1000, 150.2000, 140.0211]
            }
        ],
        "ranking": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49
            }
        ]
    }
}
このコードブロックをポップアップで表示

成功レスポンス

フィールド 型 説明
timezone String 組織のタイムゾーン（UTC オフセット、例：+07:00）。
data_since String クレジットデータが最も早く存在する日（yyyy-MM-dd）、それ以前の期間は不完全；まだデータがない場合は null。
buckets String[] 時間バケットの開始日、昇順：日単位なら当日、週単位なら月曜日（yyyy-MM-dd）、月単位なら yyyy-MM。points はこの順序に対応。
total Number 期間内の合計量（クレジットまたはトークン、metric に依存）。
series Object[] トレンド用の最初の top_n 行、合計量順に高いものから残りは一行にまとめる row_type = OTHER。
ranking Object[] 完全ランキング、最大 500 行、超過部分は一行にまとめる OTHER。points を含まない。
series[].row_type / ranking[].row_type String ITEM が Agent または Workflow；OTHER がまとめ項目；UNATTRIBUTED はどの Agent にも属さない消費（例：ナレッジベースストレージ、音声認識）、agent_type が渡された場合、この行は返さない。
series[].agent_id / ranking[].agent_id String Agent または Workflow の ID；OTHER / UNATTRIBUTED 行は null。
series[].name / ranking[].name String 名称；OTHER / UNATTRIBUTED 行は null。
series[].agent_type / ranking[].agent_type String AGENT または WORKFLOW；OTHER / UNATTRIBUTED 行動 null。
series[].total / ranking[].total Number 区間合計、4 桁の小数を保持。
series[].share / ranking[].share Number 区間合計に占める割合、0 から 100、2 桁の小数を保持。
series[].points Number[] 各時間バケットの数値。

失敗レスポンス

フィールド 型 説明
code Integer エラーコード。
message String エラー詳細。

エラーコード

HTTP ステータスコードはエラーコードの先頭3桁に対応、例: 40000 は 400、40100 は 401、403132 は 403。

エラーコード 説明
40000 パラメータエラー：必須パラメータの欠如、またはパラメータの値が不正。
40001 呼び出しが頻繁すぎます：この開発者キーが本 API の1分間上限を超えました。
40008 組織プラン「統計系 API」の1分間限度を超過。
40010 API は一時的に閉鎖中です、後でもう一度お試しください。
40100 権限がありません：使用量参照権限の欠如。
40105 組織のメンバーではない、または他のデータセンターのアドレスを呼び出しました。
40324 DevKey または DevSecret に誤りがあります。
403132 時間範囲が無効：開始時間が終了時間より前でない、または最大クエリ範囲を超えた。

統計基準

  • 統計範囲：開発スペースのみを統計対象とし、API、共有ページ、ウェブ埋め込み、バブルコンポーネント、LiveDesk、および各即時通訊や電話チャンネル、開発スペースのWorkflowを含む；ワークスペース（GWork）の使用は含まれず、公開されたAgentがワークスペースで使用された部分も含まれない。そのため、総額はコンソールの「組織 → 使用量」ページの同じ期間よりやや低くなる可能性がある。
  • クレジット：全ての消費タイプ（クレジット期限切れやサブスクリプション支払いを除く）；Workflowの消費はWorkflow自身の名義で記録される。
  • データ開始日：機能リリース日（data_since）から存在し、過去のデータは遡って適用されない。
  • 更新頻度：リアルタイム更新。