Gateway の使用量とエクスポート

使用量タブには、支出、リクエスト数、各リクエストのモデル・キー・部門・エンドユーザーが表示されます。1 か月分はコンソールか gateway.usage.export から CSV で取得でき、プロンプトや応答の本文は含みません。

最終更新 2026-10-28

使用量タブ#

AI Gateway › 使用量 は、ワークスペースのオーナーと管理者向けです。期間を選び、必要なら 1 つのキーに絞り込みます。支出、リクエスト数、成功率、日ごとの推移、キー別とモデル別の支出、auto がどう選んだかに続いて、各リクエストが表示されます。実行日時、キー、応答したモデルとその理由、トークン数、結果です。拒否されたリクエストには、どの上限で拒否されたかが表示されます。

エンドユーザー#

1 つのキーで多くの人にサービスを提供するシステムは、各リクエストが誰のためのものかを示せます。Gateway はそれをリクエストのエンドユーザーとして記録します。

エンドポイント	フィールド
`/v1/chat/completions`	`user`
`/v1/responses`	`user`
`/v1/messages`	`metadata.user_id`

記録されるのはこの識別子だけで、そのためにリクエストの他の内容が保存されることはありません。フィールドはそのままプロバイダーにも渡されます。名前ではなく、社員番号やハッシュ化したアドレスなど、自社のシステムで意味のある ID を使ってください。識別子のないリクエストは、エンドユーザーなしとして表示されます。

タグ#

タグはリクエストの用途（チーム、機能、顧客など）を示すラベルで、使用量タブで支出をタグごとに分けたり絞り込んだりできます。どの推論エンドポイントでも、X-AgentLab-Metadata ヘッダーに JSON オブジェクトを 1 つ送ります。

bash

curl https://api.agentlab.cresclab.com/v1/chat/completions \
  -H "Authorization: Bearer $AGENTLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'X-AgentLab-Metadata: {"team": "support", "feature": "summary"}' \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'

SDK では同じヘッダーを渡します。Python の例：

python

reply = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={"X-AgentLab-Metadata": '{"team": "support", "feature": "summary"}'},
)

/v1/chat/completions と /v1/responses では、OpenAI の metadata 本文フィールドもタグとして読み取り、プロバイダーにはそのまま渡します。両方を送ると結合され、両方にあるキーは同じ値でなければなりません。ヘッダーはプロバイダーに送られません。

規則	上限
タグ	1 リクエストにつき最大 16 個。
キー	英数字・`_`・`.`・`-` の 1〜64 文字。
値	1〜512 文字の文字列。制御文字は使えません。

規則に反するタグを含むリクエストは 400 invalid_metadata で拒否され、メッセージが反した規則を示します。タグが黙って捨てられることはありません。AI Gateway › 使用量の内訳でタグを選びキーを選ぶと、値ごとの支出が見られます。値を選ぶとページ全体がその値に絞り込まれます。リクエストの詳細と CSV エクスポートにも各リクエストのタグが表示されます。タグはエンドユーザーと同じくあなた自身のラベルです。個人情報やプロンプトの内容は入れないでください。

1 か月分をエクスポートする#

使用量タブで CSV を出力 を選び、月を選んでダウンロードします。ファイルはリクエストの試行ごとに 1 行で、Excel で開いても文字化けせず、プロンプトや応答のテキストは含まれません。

列	内容
`request_id`	リクエストの ID。`X-Request-Id` ヘッダーで送られるものと同じです。
`attempt_id`	この試行。`auto` が先に判断したリクエストや、再試行されたリクエストには複数あります。
`started_at`	試行の開始日時。UTC（ISO 8601）。
`state`	`completed`、`failed`、`uncertain`（使用量が報告されなかった）、`dispatched`、`prepared` のいずれか。
`model`	試行を送ったモデル。
`decision`	そのモデルにした理由。指定したモデルなら `explicit_pin`、それ以外は `auto` の判断内容。
`input_tokens`, `output_tokens`	実測のトークン数。使用量が不明な場合は空欄。
`cached_read_tokens`, `cache_write_tokens`	プロンプトキャッシュのトークン数。プロバイダーが報告しなかった場合は空欄。
`cost_usd`	その日のモデルのカタログ価格による費用。使用量または価格が不明な場合は空欄。
`key_id`, `key_name`	送信したキー。
`departments`	試行の開始時にキーが計上されていた部門。`;` で区切られます。
`end_user`	リクエストが示したエンドユーザー。なければ空欄。
`failure_code`	Gateway が記録した、試行が応答しなかった理由（`inference_allowance_exceeded` など）。
`tags`	リクエストのタグ。`{"team":"support"}` のような JSON オブジェクト。なければ空欄。

空欄は不明を意味し、ゼロではありません。月は UTC の暦月です。=、+、-、@、タブ、復帰文字で始まるセルには先頭に ' が付くので、表計算ソフトはそれを実行せずにそのまま表示します。

コードからエクスポートする#

同じファイルを、コンソール API の gateway.usage.export プロシージャからページ単位で取得できます。1 回の呼び出しで最大 5,000 行を content に CSV テキストとして、あわせて nextCursor を返します。nextCursor が null になるまでそのカーソルで呼び出しを繰り返し、各ページの content を順に連結します。バイトオーダーマークとヘッダー行は最初のページにだけ含まれます。呼び出せるのはワークスペースのオーナーまたは管理者だけです。