--- title: Gateway の使用量とエクスポート description: 使用量タブには、支出、リクエスト数、各リクエストのモデル・キー・部門・エンドユーザーが表示されます。1 か月分はコンソールか gateway.usage.export から CSV で取得でき、プロンプトや応答の本文は含みません。 url: https://agentlab.cresclab.com/docs/ja/gateway/usage language: ja updated: 2026-10-28 --- # Gateway の使用量とエクスポート 使用量タブには、支出、リクエスト数、各リクエストのモデル・キー・部門・エンドユーザーが表示されます。1 か月分はコンソールか gateway.usage.export から CSV で取得でき、プロンプトや応答の本文は含みません。 ## 使用量タブ **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` を順に連結します。バイトオーダーマークとヘッダー行は最初のページにだけ含まれます。呼び出せるのはワークスペースのオーナーまたは管理者だけです。