openrouter-analytics-schema

OpenRouter Analytics スキーマの確認

クエリで利用できる分析データを確認します。メタエンドポイントは、メトリクス、ディメンション、フィルター演算子、粒度の定義を常に最新の状態で返します。

前提条件

• OpenRouter の管理キー。管理キーは通常の API キーとは別のものです。https://openrouter.ai/settings/management-keys で取得してください
• --api-key <key> で渡すか、OPENROUTER_API_KEY 環境変数を設定してください

確認用エンドポイント

GET https://openrouter.ai/api/v1/analytics/meta
Authorization: Bearer sk-or-v1-...

openrouter-analytics スキルのスクリプトを使用する場合：

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

レスポンスの形式

{
  "data": {
    "metrics": [
      { "name": "request_count", "display_label": "Request Count", "is_rate": false, "display_format": "number" }
    ],
    "dimensions": [
      { "name": "model", "display_label": "Model" }
    ],
    "operators": [
      { "name": "eq", "value_type": "scalar" }
    ],
    "granularities": [
      { "name": "day", "display_label": "Day" }
    ]
  }
}

メトリクスについて

各メトリクスには次の項目があります。

フィールド	意味
name	クエリリクエストで使用する識別子
display_label	人が読みやすいラベル
is_rate	比率／レートかどうか（合計ではなく平均を算出）
display_format	値の表示形式：number、currency、percent、latency、throughput

時間範囲の上限

大半のボリュームおよびコストのメトリクスでは、日単位またはそれより粗い粒度で、最大 367 日の時間範囲をサポートします。レイテンシ／スループットのメトリクス、blended_cost_per_million_tokens、および生成のみのディメンション（provider、origin、country、data_region、skin、finish_reason、external_user、context_length_bucket、generation_id、session_id、streamed）は、時間範囲が 31 日までに制限されます。hour 粒度も同様です。キャッシュ可能性メトリクス（possible_cached_tokens、possible_cache_hit_rate、cache_capture_rate）は常に時間単位の集計データを参照するため、こちらも 31 日までに制限され、より粗い粒度にしても上限は変わりません。

上限を超えると、結果が切り捨てられるのではなく、適用される最大値をメッセージに含む 400 が返されます。クエリがタイムアウトする場合は、時間範囲を狭めるか、レイテンシ／スループットのメトリクスや生成ごとのディメンションを削除してください。

メトリクスのカテゴリ

ボリュームメトリクス（量を示します）：

• request_count — API リクエスト数（最大 367 日）。リクエストと併せて記録されるサーバーツールの行（ウェブ検索／ファイル解析の料金）は除外されるため、課金明細ではなくモデルリクエスト数を数えます
• tokens_total、tokens_prompt、tokens_completion — トークン数（最大 367 日）
• reasoning_tokens — 拡張思考で使用されたトークン数（最大 367 日）
• cached_tokens — キャッシュから提供されたトークン数（最大 367 日）
• possible_cached_tokens — キャッシュの対象になり得たプロンプトトークン数。実際にキャッシュされたかどうかは問いません（31 日までの制限があり、時間単位の集計データのみ）
• byok_request_count — BYOK リクエスト数（最大 367 日）。クエリが生成データを直接参照する場合（同じリクエストにレイテンシ／スループットのメトリクス、または生成のみのディメンションが含まれる場合）はサーバーツールの行が除外されますが、集計データから提供される場合は引き続きカウントされるため、サーバーツールを使用する BYOK トラフィックでは、この 2 つの経路で結果が異なることがあります
• guardrail_invoked_count — ガードレールを作動させたリクエスト数（31 日までの制限）
• response_cached_count — キャッシュから提供されたレスポンス数（31 日までの制限） コスト指標（費用）：
• total_usage — BYOK の推論コストを含む合計コスト（USD、最大367日分）。sum(usage) + sum(byok_usage_inference) として計算されるため、クレジット利用者と BYOK 利用者の両方について実際の支出が反映されます。
• byok_usage — BYOK（Bring Your Own Key）の推論コスト（USD、最大367日分）
• credits_usage — BYOK のプラットフォーム手数料を含む、OpenRouter クレジットへの全請求額（USD、最大367日分）
• openrouter_usage — BYOK 以外の推論支出（USD）。ユーザー提供のキーを使用したリクエストは含まれません（31日間の制限）
• byok_fees — BYOK のプラットフォーム手数料（USD）。BYOK リクエストに対して請求される credits_usage のうち、プラットフォーム手数料にあたる部分です（31日間の制限）。credits_usage には、BYOK 以外の推論料金と BYOK のプラットフォーム手数料の両方が含まれます。
• usage_upstream — プロバイダー側（上流）のコスト（USD、最大367日分）
• usage_cache — キャッシュコストの内訳（USD、最大367日分）
• usage_data — データロギングのコスト調整額（USD）。データロギングの割引が適用される場合、通常はマイナスになります（最大367日分）
• usage_web — ウェブ検索のコスト（USD、最大367日分）
• usage_upstream_web — プロバイダー側のウェブ検索コスト（USD、最大367日分）
• usage_file — ファイル処理のコスト（USD、31日間の制限）
• usage_upstream_file — プロバイダー側のファイル処理コスト（USD、31日間の制限）
• usage_web_fetch — ウェブ取得のコスト（USD、31日間の制限）
• usage_upstream_web_fetch — プロバイダー側のウェブ取得コスト（USD、31日間の制限）
• blended_cost_per_million_tokens — BYOK の推論コストを含む、100万トークン（プロンプト＋生成）の平均コスト（31日間の制限。常に生の生成データを参照します）。サーバーツールの支出は分子に含まれません。レート指標のため、トークン数がないバケットでは null となり、行をまたいで合計できません。

パフォーマンス指標（速度。すべて31日間の制限で、特記がない限りミリ秒単位）。各グループには avg_、p50_、p90_、p95_、p99_ のバリエーションがあります。

• *_latency — プロバイダー側で最初のトークンが返されるまでの時間（ストリーミングでないリクエストでは応答全体にかかる時間）
• *_router_latency — プロバイダーへのリクエスト前に OpenRouter のルーティングにかかる時間
• *_total_time_to_first_token — latency + router_latency。ストリーミングリクエストのみを対象に計算されます。
• *_generation_time — プロバイダー側での生成時間
• *_inter_token_latency — 連続する生成トークン間の平均時間。(generation_time - latency) / (native_tokens_completion - 1) で計算され、生成トークンが2つ以上あるストリーミングリクエストのみが対象です。
• *_throughput — 1秒あたりの生成トークン数。native_tokens_completion / generation_time から算出され、生成トークンがないリクエストでは null になります。

すべてのパフォーマンス指標から、サーバーツールの行（リクエストと併せて記録されるウェブ検索／ファイル解析の料金）は除外されます。

効率性指標（効率）：

• cache_hit_rate — プロンプトトークンに対するキャッシュ済みトークンの割合（0～1）
• possible_cache_hit_rate — プロンプトトークンに対するキャッシュ対象になり得るプロンプトトークンの割合（0～1。31日間の制限、時間単位の集計のみ）
• cache_capture_rate — キャッシュ対象になり得るプロンプトトークンのうち、実際にキャッシュから提供されたトークンの割合（仕様上0～1。31日間の制限、時間単位の集計のみ）
• guardrail_invoked_rate — ガードレールが作動したリクエストの割合
• response_cached_rate — キャッシュから提供された応答の割合

ディメンションについて

各ディメンションには次の項目があります。

フィールド	意味
name	クエリリクエストで使用する識別子
display_label	人が読めるラベル

ディメンションは、データを分類して表示する基準です。「モデル別の支出を表示する」は、dimensions: ["model"] を意味します。

1つのクエリで最大2つのディメンションを組み合わせられます（例：["model", "provider"]）。

ラベルの解決

一部のディメンションでは、クエリ結果で生の ID が人間に読みやすいラベルに自動的に解決されます。データ行には、解決後の表示名が直接含まれます。

ディメンション	解決後
api_key_id	キー名／ラベル
app	アプリのタイトルまたはオリジン URL
user	ユーザー名またはメールアドレス
workspace	ワークスペース名（削除済みのワークスペースにも名前が表示されます）

特別な値を示すバケットには、生の値ではなく名前付きラベルが付けられます。

• api_key_id の -1 → Chatroom（API キーなしのトラフィック。例：チャットルームのリクエスト）
• app の -1 → Unknown（アプリに帰属しない行）
• workspace の最大 UUID の特別値 → Unattributed（行の書き込み時にワークスペースを解決できなかった場合）

それ以外のディメンション（例：model、provider、country）は、解決されずそのまま返されます。

user の値が空の行は、特定の組織メンバーに帰属しないトラフィックを表します（例：組織レベルで作成された API キー）。

ワークスペースの解決が導入される前に書き込まれた行には、すべてゼロのワークスペース UUID が付与されています。グループ化ではこれらの行がアカウントのデフォルトのワークスペースにまとめられ、デフォルトのワークスペース UUID でフィルタリングした場合にも一致するため、論理上のワークスペースが 1 つのグループとして扱われます。

ディメンションのカテゴリ

すべての期間で利用可能：

• model — OpenRouter のモデル ID（permaslug）
• variant — モデルのバリアント（例：standard、extended）
• api_key_id — リクエストを行った API キー
• user — 作成者のユーザー ID（組織レベルのクエリ用）
• workspace — ワークスペース ID
• app — アプリケーション ID

期間が 31 日以内の場合に利用可能：

• generation_id — 各生成に固有の ID（個々のリクエストを詳しく調べる際に使用し、その後 openrouter-generations スキルで確認します）
• provider — 上流プロバイダー名
• origin — リクエストのオリジン／ソース
• country — リクエスト元の国
• data_region — リクエストの処理元データリージョン。値が空の場合は global として報告されます
• skin — API スキン（リクエストパスから判定される、リクエストで使用された API 形式）
• finish_reason — 生成が終了した理由（stop、length など）
• external_user — 呼び出し元が渡したカスタムユーザー ID
• context_length_bucket — バケット化されたコンテキスト長（1K、10K、100K など）
• session_id — リクエストが属するセッション。セッションのないリクエストは、文字列そのものの none としてグループ化されます
• streamed — リクエストがストリーミングされたかどうか。値は文字列の true と false です

分類器ディメンション

上記の標準ディメンションに加えて、分類器ディメンションでグループ化できます。分類器ディメンションとは、ユーザーが作成した分類器が生成する動的なラベルです（例：トピック、感情、カテゴリ）。

• 分類器が生成した値でグループ化するには、リクエストフィールド classifier_dimensions を使用します
• 1 クエリにつき指定できる分類器ディメンション名は最大 2 つです。2 つ指定すると、両方によるクロス集計結果が返されます
• 分類器の値でフィルタリングするには、リクエストフィールド classifier_filters を使用します
• 分類器はアカウントに属している必要があります（サーバー側で検証されます）
• 分類器ディメンション／フィルターを使用する場合、クエリ期間は 31 日以内に制限されます
• リクエストの全体像については、openrouter-analytics-query スキルを参照してください

質問を分類器クエリに対応付ける

質問のパターン	リクエストフィールド	備考
「トピック別の支出」	classifier_dimensions: { classifier_id, dimension_names: ["topic"] } + metrics: ["total_usage"]	ディメンションが 1 つの場合、列のエイリアスは topic になります
「請求関連のリクエストのみ」	classifier_filters: { classifier_id, filters: [{ field: "category", operator: "eq", value: "billing" }] }	フィルターでサポートされる演算子は eq、neq、in、not_in のみです
「未分類を含む感情の内訳」	classifier_dimensions: { classifier_id, dimension_names: ["sentiment"], include_nulls: true }	分類されていない行も含まれます

演算子について

クエリリクエストの filters 配列で使用するフィルター演算子です。

演算子	値の型	意味
eq	スカラー	等しい
neq	スカラー	等しくない
gt	スカラー	より大きい
gte	スカラー	以上
lt	スカラー	より小さい
lte	スカラー	以下
in	配列	リスト内に含まれる
not_in	配列	リスト内に含まれない

in と not_in では、値が設定されていないディメンションを持つ行も一致対象にするために、オプションの include_unset: true を指定できます。未設定バケットに対応しているディメンション（api_key_id、app、user）のみで使用できます。それ以外を指定すると、400 エラーが返されます。

時間粒度について

時系列クエリでの時間バケット化に使用します。

粒度	使用する場面
minute	直近数時間、リアルタイム監視
hour	直近 1～3 日
day	直近 1 週間～3 か月
week	直近 3～12 か月
month	年単位の傾向

粒度を設定しない場合、クエリは時間バケット化せず、集計合計を返します。

質問をクエリに対応付ける

このガイドを使って、自然言語の質問に適したメトリクス、ディメンション、フィルターの組み合わせを選択します。

質問のパターン	メトリクス	ディメンション	備考
「いくら使いましたか？」	total_usage	—	傾向を見るには粒度を追加
「最も費用がかかったモデルはどれですか？」	total_usage	model	total_usage の降順で並べ替え
「リクエスト数はいくつですか？」	request_count	—	内訳を見るには model または api_key_id を追加
「トークン数はいくつですか？」	tokens_total	—	内訳には tokens_prompt / tokens_completion を使用
「最も速いプロバイダーはどれですか？」	avg_latency, p90_latency	provider	31 日間の上限
「キャッシュヒット率はいくつですか？」	cache_hit_rate	model	レートメトリクス — モデルごとのキャッシュ状況を表示
「最も多く使用している API キーはどれですか？」	request_count, total_usage	api_key_id	—
「時間の経過に伴う使用状況」	request_count または total_usage	—	granularity: "day" を設定
「レイテンシの傾向」	p90_latency	—	granularity: "hour" を設定。31 日間の上限
「ストリーミングはどの程度スムーズですか？」	p50_inter_token_latency, p95_inter_token_latency	model または provider	31 日間の上限。完了トークンが 1 つより多いストリーミングリクエストのみ
「国別の使用状況」	request_count	country	31 日間の上限
「どうすれば費用を節約できますか？」	total_usage, cache_hit_rate, tokens_total	model	openrouter-analytics スキルのコスト最適化を参照
「個別のリクエストを表示」	total_usage, tokens_total	generation_id	31 日間の上限。返された ID を openrouter-generations スキルで使用すると、完全なメタデータとコンテンツを確認できます
「BYOK の利用額はいくらですか？」	byok_usage	model	最大 367 日間
「BYOK とクレジットの内訳は？」	byok_usage, credits_usage	—	どちらも最大 367 日間
「BYOK のプラットフォーム手数料はいくらですか？」	byok_fees	model	31 日間の上限
「BYOK 以外の推論費用はいくらですか？」	openrouter_usage	model	31 日間の上限
「ガードレールは何回作動しましたか？」	guardrail_invoked_count, guardrail_invoked_rate	model	31 日間の上限
「キャッシュされたレスポンスはいくつですか？」	response_cached_count, response_cached_rate	model	31 日間の上限
「費用の内訳は？」	usage_upstream, usage_cache, usage_data	—	費用の全内訳（最大 367 日間）
「ウェブ検索の費用はいくらですか？」	usage_web, usage_upstream_web	model	最大 367 日間
「ファイル処理の費用はいくらですか？」	usage_file, usage_upstream_file	model	31 日間の上限
「ウェブ取得の費用はいくらですか？」	usage_web_fetch, usage_upstream_web_fetch	model	31 日間の上限

フィルター値の参照先

クエリ結果では、いくつかのディメンションがラベルに解決されます。レスポンスには人が読める名前が表示されますが、フィルターには基になる ID を使用する必要があります。それぞれの参照先は次のとおりです。

ディメンション	フィルター値	参照先
api_key_id	数値 ID または 64 文字の SHA-256 ハッシュ	数値 ID：生成メタデータ（api_key_id フィールド）。ハッシュ：GET /api/v1/keys（key_hash フィールド）。ハッシュはサーバー側で自動的に解決されます。ハッシュを解決できない場合は、センチネル値によってエラーを返さずに 0 行が返されます。
user	Clerk ユーザー ID（例：user_abc123）	ユーザー設定または組織のメンバー一覧。結果に表示される表示名やメールアドレスではありません。
workspace	ワークスペース UUID。デフォルトのワークスペース UUID でフィルタリングすると、ワークスペースの解決が導入される前に書き込まれたレガシー行にも一致します。	ワークスペースの設定ページまたは GET /api/v1/workspaces。結果に表示されるワークスペース名ではありません。
app	数値のアプリ ID	生成メタデータ（app_id フィールド）またはアプリの設定。結果に表示されるアプリのタイトルではありません。
model	Permaslug（例：openai/gpt-4o）	モデルページの URL または GET /api/v1/models。表示名ではありません。

その他のディメンション（provider、origin、country、finish_reason、external_user など）は拡張されません。フィルター値は結果に返される値と一致します。

制約

• クエリあたり最大 2 個のディメンション
• クエリあたり最大 20 個のフィルター
• クエリあたり最大 2 個の分類器ディメンション名
• クエリあたり最大 10 個の分類器フィルター
• クエリあたり最大 10,000 行を返します（デフォルトは 1,000 行）
• group_limit（1～10,000）：ディメンションの組み合わせごとの最大行数を制御します。ディメンションを指定した時系列クエリでは、時間範囲全体を網羅できるよう自動計算されます。グループごとの行数を制限するには明示的に設定します（例：1 日あたりのモデルごとの上位 N 件）。
• ほとんどのボリューム／コスト指標：日単位の粒度で最大 367 日
• レイテンシ／スループット指標、blended_cost_per_million_tokens、および生成ごとのディメンション：最大 31 日
• 分類器ディメンション／フィルター：常に最大 31 日
• 分単位の粒度：時間範囲が 3 時間以下の場合にのみ利用可能
• hour の粒度では分単位のマテリアライズドビューを読み取ります。最大 31 日です
• キャッシュ可能性の指標（possible_cached_tokens、possible_cache_hit_rate、cache_capture_rate）：最大 31 日、hour 以上の粒度が必要で、ディメンションとフィルターに指定できるのは model／provider のみです。それ以外のディメンション、フィルター、分類器、または minute の粒度を指定すると 400 が返されます
• レート制限：1 分あたり 64 リクエスト