openrouter-analytics

OpenRouter Analytics

Analytics API を使って、OpenRouter の使用状況データをプログラムから照会できます。「今月の支出はいくらですか？」「最もコストが高いモデルはどれですか？」「請求額を抑えるにはどうすればよいですか？」といった質問に回答できます。

前提条件

• OpenRouter の管理キー（プロビジョニングキー）。通常の API キーでは 403 が返されます。
• https://openrouter.ai/settings/management-keys で管理キーを取得してください（通常の API キーのページとは別です）。
• --api-key <key> で渡すか、OPENROUTER_API_KEY 環境変数を設定してください。

初回セットアップ

cd <skill-path>/scripts && npm install

判断ツリー

ユーザーの要望	実行すること
利用可能なデータを知りたい	discover-schema.ts を実行して、メトリクス、ディメンション、フィルターを確認します
支出／使用状況／量を確認したい	適切なメトリクスを指定して query-analytics.ts を実行します
モデル、プロバイダー、API キー別に内訳を確認したい	クエリに --dimensions を追加します
時系列の推移を確認したい	--granularity day（または hour、week、month）を追加します
コストを削減したい	suggest-queries.ts を実行し、コスト最適化テンプレートを見つけて実行します
個々の生成を調べたい	--dimensions generation_id を追加し、詳細については openrouter-generations スキルを使用します
分類ラベル別に内訳を確認したい	リクエストボディで classifier_dimensions を使用します（openrouter-analytics-query スキルを参照）
分類ラベルで絞り込みたい	リクエストボディで classifier_filters を使用します（openrouter-analytics-query スキルを参照）
特定の質問に回答したい	質問をメトリクス＋ディメンションに対応付けてから、クエリを実行します

ワークフロー

ユーザーの分析に関する質問に回答するための推奨ワークフローは次のとおりです。

1. 確認 — discover-schema.ts を呼び出して、利用可能なメトリクスとディメンションを確認します。
2. 対応付け — ユーザーの質問をメトリクス、ディメンション、フィルター、時間範囲に対応付けます。
3. クエリ — query-analytics.ts で実行します。
4. 解釈 — 返されたデータを分析し、結果を説明します。

一般的な質問には、suggest-queries.ts のすぐに使えるクエリテンプレートを利用できます。

利用可能なデータを確認する

cd <skill-path>/scripts && npx tsx discover-schema.ts

メトリクス、ディメンション、フィルター演算子、粒度を含む完全なスキーマが返されます。

特定のセクションに絞り込むには：

npx tsx discover-schema.ts --section metrics
npx tsx discover-schema.ts --section dimensions
npx tsx discover-schema.ts --section operators
npx tsx discover-schema.ts --section granularities

スキーマの応答を解釈し、ユーザーの質問を適切なメトリクスとディメンションに対応付ける方法について詳しくは、openrouter-analytics-schema スキルを参照してください。

分析データをクエリする

cd <skill-path>/scripts && npx tsx query-analytics.ts --metrics request_count,total_usage

パラメーターの完全なリファレンスとクエリの組み立て方については、openrouter-analytics-query スキルを参照してください。

簡単な例

過去 7 日間の支出を日別に集計する場合：

npx tsx query-analytics.ts --metrics total_usage --granularity day

コストが高い上位 10 モデル：

npx tsx query-analytics.ts --metrics total_usage,request_count --dimensions model --order-by total_usage --limit 10

API キー別の使用状況：

npx tsx query-analytics.ts --metrics request_count,tokens_total --dimensions api_key_id --order-by request_count --limit 10

プロバイダー別のレイテンシ（範囲は 31 日間まで）：

npx tsx query-analytics.ts --metrics avg_latency,p90_latency --dimensions provider --order-by p90_latency

使用コストの内訳（クレジット、BYOK、アップストリーム、キャッシュ、データロギング、ウェブ検索）：

npx tsx query-analytics.ts --metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web --granularity day

一般的なクエリテンプレート

cd <skill-path>/scripts && npx tsx suggest-queries.ts

一般的な質問向けにあらかじめ用意されたクエリテンプレートの一覧が返されます。各テンプレートには次の内容が含まれます。

• 回答する自然言語の質問
• クエリパラメーター（メトリクス、ディメンション、フィルター、時間範囲）
• query-analytics.ts に渡す CLI フラグ
• 解釈のガイダンス（該当する場合）

結果の解釈

クエリエンドポイントは、データ行の配列を返します。各行は、リクエストされたメトリクスとディメンションに一致するキーを持つフラットなオブジェクトです。

ユーザー向けに結果を解釈する際は、以下を参考にしてください。

• 支出メトリクス（total_usage、credits_usage、openrouter_usage、byok_usage、byok_fees、usage_upstream、usage_cache、usage_web、usage_upstream_web、usage_file、usage_upstream_file、usage_web_fetch、usage_upstream_web_fetch）の単位は USD です。total_usage には BYOK の推論コストが含まれます。usage_data は通常、データ記録の割引を表す負の値です
• トークン数（tokens_total、tokens_prompt、tokens_completion）は、モデル固有のトークン数です
• レイテンシ（avg_latency、p50_latency など）の単位はミリ秒です。*_latency はプロバイダー側の初回トークンまでの時間、*_router_latency は OpenRouter のルーティング時間、*_total_time_to_first_token はストリーミングリクエストのみを対象にした両者の合計、*_generation_time はプロバイダー側の生成時間、*_inter_token_latency は、完了トークンが2つ以上あるストリーミングリクエストにおける完了トークン間の平均時間です。各ファミリーには avg_、p50_、p90_、p95_、p99_ のバリエーションがあり、サーバーツールの行は除外されます
• レート（cache_hit_rate、possible_cache_hit_rate、cache_capture_rate）は、0〜1 の比率です
• スループット（avg_throughput、p50_／p90_／p95_／p99_throughput）は、1秒あたりの完了トークン数です
• granularity を設定すると、時間区分を示す date__<granularity> フィールド（例：date__day、date__hour、date__month）が各行に含まれます
• ラベルの解決：ディメンション api_key_id、app、user、workspace では、生の ID が人間に読みやすい名前（キー名、アプリのタイトル、ユーザー名、ワークスペース名）に置き換えられ、データ行に直接含まれます。generation_id と session_id は生の値を返します。特別なバケットにはラベルが付けられます（api_key_id の -1 → Chatroom、app の -1 → Unknown、最大 UUID のワークスペース → Unattributed）
• 切り詰め：出力をプログラムで処理する場合は、metadata.truncated を確認してください。true の場合、結果は --limit で上限に達しており、データセットは不完全です。合計やランキングを報告する前に、--limit を増やすかページネーションを行ってください

コスト最適化のガイダンス

ユーザーから「支出を抑えるにはどうすればよいですか？」などと尋ねられた場合：

1. 支出上位のモデルをクエリします：--metrics total_usage,tokens_total,cache_hit_rate,request_count --dimensions model --order-by total_usage --limit 10
2. コストの内訳をクエリします：--metrics credits_usage,byok_usage,byok_fees,usage_upstream,usage_cache,usage_data,usage_web,usage_file --granularity day を使用して、支出の内訳を確認します
3. 次の点を確認します：
   • 支出が多い一方で cache_hit_rate が低いモデル — プロンプトキャッシュが有効な場合があります
   • 特定のタスクで、より安価な代替モデルに置き換えられる高価なモデル
   • リクエスト数が少ないのにトークン数が多い場合 — プロンプトが過剰に大きい可能性があります
   • reasoning_tokens が合計に占める割合が大きいモデル — 必要がなければ、拡張思考を無効にすることを検討してください
   • usage_upstream と比べて usage_web または usage_file が多い場合 — ウェブ検索やファイル処理の追加コストが大きい可能性があります

個々の生成を詳しく調べる

分析結果から特定の生成やセッションを調べるには、ディメンションとしてgeneration_idまたはsession_idを追加します。どちらも生成専用のディメンションで、期間の上限は31日です。generation_idは、結果セット内の各生成の一意なIDを返します。session_idは、セッションのないリクエストを文字列noneとしてグループ化およびフィルタリングします。ClickHouseのカラムはデフォルトで空文字列となり、クエリビルダーがこれをnoneにまとめます。セッションのないリクエストを除外するにはneq 'none'を使用してください。''でフィルタリングしても一致するものはありません。

npx tsx query-analytics.ts --metrics total_usage,tokens_total --dimensions generation_id --order-by total_usage --limit 10

生成ID（例：gen-aBcDeFgHiJkLmNoPqRsT）を取得したら、openrouter-generationsスキルを使用して詳細情報を取得します。

• get-generation — リクエストの完全なメタデータ（コストの内訳、トークン数、レイテンシ、プロバイダーのルーティングチェーン、終了理由など）を取得します
• get-generation-content — 保存されたプロンプトと完了テキストを取得します（Zero Data Retentionが有効になっている場合を除く）

cd <openrouter-generations-skill-path>/scripts
npx tsx get-generation.ts gen-aBcDeFgHiJkLmNoPqRsT
npx tsx get-generation-content.ts gen-aBcDeFgHiJkLmNoPqRsT

このワークフローでは、分析を通じて最もコストの高いリクエストや処理に時間のかかるリクエストを特定し、実際のプロンプトと完了テキストを調べてその理由を把握できます。

API リファレンス

どちらのエンドポイントも、Authorization: Bearer sk-or-v1-...による管理キーが必要です。

エンドポイント	メソッド	説明
/api/v1/analytics/meta	GET	利用可能なメトリクス、ディメンション、演算子、粒度を返します
/api/v1/analytics/query	POST	分析クエリを実行し、構造化データを返します

完全なドキュメント：https://openrouter.ai/docs/api/api-reference/analytics