# Analytics API Stripe 定義の指標にプログラムからアクセスできます。 Analytics API を使用すると、月間経常収益 (MRR)、年間経常収益 (ARR)、利用収益など、Stripe が定義するメトリクスに同期的かつプログラムでアクセスできます。独自のダッシュボードの構築、AI エージェントからのメトリクスのクエリ、または Stripe データの内部ツールへの統合にご活用ください。 Stripe には 3 つのプログラマティックデータ製品があります。必要なデータの種類に合ったものをお選びください。 - **Analytics API (本製品)**: Stripe が定義するメトリクスを JSON 形式で同期的に返します。オンデマンドで少数の構築済みメトリクスを取得したい場合、本番ダッシュボードで使用するメトリクスを取得したい場合、または AI エージェントにメトリクスを提供したい場合に適しています。 - [Reports API](https://docs.stripe.com/reports/api.md): 大規模な構築済みデータセットを CSV ファイルとして非同期で返します。スケジュールに従って生のトランザクションデータを一括エクスポートする必要がある場合に適しています。 - [Query Runs API](https://docs.stripe.com/reports/query-runs.md): 生の Stripe データに対してフリーフォーム SQL を非同期で実行し、CSV ファイルを返します。基になるデータに対して SQL の完全な柔軟性が必要な場合に適しています。 ## 概念 ### メトリクス **メトリクス** とは、生の Stripe データを集計して算出される定量的な値です。MRR、ARR、利用収益などが例として挙げられます。 メトリクスは **ID** (例: `metric_61Sud3n5oAGVCWiSr5`) または **共通名** (例: `revenue.mrr`) で参照できます。各メトリクスには本番環境とサンドボックスで別々の ID がありますが、共通名はどちらのモードでも同じです。`id` と `name` の両方を指定する場合は、同じメトリクスを参照している必要があります。 金額メトリクスの値は最小単位 (USD の場合はセント) で返されます。パーセンテージメトリクスの値はベーシスポイント (1% の場合は 100) で返されます。各メトリクスが返す単位は[サポートされるメトリクス](https://docs.stripe.com/data/analytics/supported-metrics.md)に記載されています。 メトリクスには **ディメンション** (`customer`、`product`、`price` などのカテゴリ属性) が含まれることが多く、結果をフィルタリングまたはグループ化する際に使用できます。 ### メトリクスの名前空間 **メトリクスの名前空間** とは、同じディメンションを共有するメトリクスのグループです。1 つの `metric_query` リクエスト内のすべてのメトリクスは、同じ名前空間に属している必要があります。 たとえば、`revenue` 名前空間には `revenue.mrr` と `revenue.arr` が含まれます。どちらも `price`、`product`、`customer`、`subscription` で絞り込むことができ、`price_name`、`product_name`、`customer_email` などの追加ディメンションでグループ化できます。 ### 時間範囲と粒度 各 `metric_query` は、指定した `granularity` で時系列データを返します。サポートされている粒度は `day`、`week`、`month`、`year` です。クエリできる最大時間範囲は粒度によって異なります。 - `day`: 最大 92 日間 - `week`: 最大 397 日間 - `month` および `year`: 固定の上限なし `day` 以外の粒度では、API は `starts_at` と `ends_at` を最も近いバケット境界にスナップするため、バケット内のどのタイムスタンプを指定しても同じ結果が返されます。例えば、`starts_at=2026-01-15T00:00:00Z` を指定した月次クエリでは、各月の 1 日始まりのバケットが返されます。 週のバケットは日曜日から土曜日までです。 ### サンドボックス Analytics API は[サンドボックス](https://docs.stripe.com/sandboxes.md)でも動作します。サンドボックスからクエリを実行する際は、メトリクスのサンドボックス ID (または両モードで同じ共通名) を使用します。 ### メトリクスのバージョン管理 メトリクスのバージョンは [API バージョン](https://docs.stripe.com/upgrades.md)に紐づいています。メトリクスの定義が変更されると、新しいバージョンに新しい ID が割り当てられ、共通名は新しいバージョンを指すようになります。以前のバージョンには引き続き ID でアクセスできます。 ## サポートされる指標 利用可能なメトリクスの全一覧、各ディメンション、結果が返される単位、およびグループ化とフィルタリングに対応するディメンションについては、[サポートされるメトリクス](https://docs.stripe.com/data/analytics/supported-metrics.md)を参照してください。 ## 例 メトリクスデータを取得するには、[`/v2/data/analytics/metric_query`](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/create.md) に `POST` リクエストを送信してください。リクエストボディは JSON 形式で、`Stripe-Version` ヘッダーを含める必要があります。 ### リクエストの例 ```curl curl -X POST https://api.stripe.com/v2/data/analytics/metric_query \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "metrics": [ { "name": "revenue.mrr" } ], "starts_at": "2026-03-01T00:00:00Z", "ends_at": "2026-03-04T00:00:00Z", "granularity": "day", "currency": "usd", "filters": { "price": [ "price_HG4jxINMyHorkI", "price_HG4UtyJbuJIsVt" ] }, "group_by": [ "price" ] }' ``` ### レスポンスの例 ```json { "id": "mqr_UQTLLvlABBZlw0", "object": "v2.data.analytics.metric_query_result", "livemode": true, "refreshed_at": "2026-03-04T02:34:15Z", "created": "2026-03-04T18:00:00Z", "next_page_url": null, "previous_page_url": null, "data": [ { "id": "mqdr_UQTLKfAhfsdatx", "timestamp": "2026-03-01T00:00:00Z", "dimensions": { "price": "price_HG4jxINMyHorkI" }, "results": [ { "metric": "metric_61Sud3n5oAGVCWiSr5", "name": "revenue.mrr", "currency": "usd", "value": 9000 } ] }, { "id": "mqdr_UQTLXYtgGM7TNp", "timestamp": "2026-03-01T00:00:00Z", "dimensions": { "price": "price_HG4UtyJbuJIsVt" }, "results": [ { "metric": "metric_61Sud3n5oAGVCWiSr5", "name": "revenue.mrr", "currency": "usd", "value": 12000 } ] }, { "id": "mqdr_UQTLcb70nAS3vR", "timestamp": "2026-03-02T00:00:00Z", "dimensions": { "price": "price_HG4jxINMyHorkI" }, "results": [ { "metric": "metric_61Sud3n5oAGVCWiSr5", "name": "revenue.mrr", "currency": "usd", "value": 9150 } ] } ] } ``` リクエストおよびレスポンスの全スキーマについては、[`MetricQueryResult` API リファレンス](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/object.md)を参照してください。 ## Stripe MCP を使用すればよいです [Stripe Model Context Protocol (MCP) サーバー](https://docs.stripe.com/mcp.md)の `execute_analytics` ツールを使用すると、AI エージェントやコードエディターからアナリティクスメトリクスをクエリできます。MCP ツールが [`POST /v2/data/analytics/metric_query`](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/create.md) エンドポイントを代わりに呼び出すため、API リクエストを手動で構築するのではなく、自然言語で求めるものを記述するだけでメトリクスを取得できます。 > Analytics MCP ツールでは OAuth に対応していません。認証するには、[制限付き API キーを bearer token として使用](https://docs.stripe.com/mcp.md?mcp-client=other)してください。 ## ユースケース ### 内部 MRR ダッシュボードを構築する 社内収益ダッシュボードを構築するために、いくつかの価格の日次 MRR を価格別にグループ化してクエリします。 ```javascript const stripe = require('stripe')('sk_test_...', { apiVersion: '2026-04-22.preview', }); const response = await stripe.v2.data.analytics.metricQuery.create({ metrics: [{ name: 'revenue.mrr' }], starts_at: '2026-01-01T00:00:00Z', ends_at: '2026-01-31T00:00:00Z', granularity: 'day', currency: 'usd', filters: { price: ['price_HG4jxINMyHorkI', 'price_HG4UtyJbuJIsVt'], }, group_by: ['price'], }); response.data.forEach((row) => { const date = new Date(row.timestamp).toISOString().split('T')[0]; const priceId = row.dimensions.price; const mrrDollars = (row.results[0].value / 100).toFixed(2); const currency = row.results[0].currency.toUpperCase(); console.log(`${date} | ${priceId} | ${currency} ${mrrDollars}`); }); ``` ### 同じ名前空間内の複数のメトリクスを追跡 MRR と ARR を一緒にクエリして、1 つのチャートに経常収益のトレンドを表示します。どちらのメトリクスも `revenue` 名前空間に属しているため、1 回の呼び出しでリクエストできます。 ```javascript const stripe = require('stripe')('sk_test_...', { apiVersion: '2026-04-22.preview', }); const response = await stripe.v2.data.analytics.metricQuery.create({ metrics: [ { name: 'revenue.mrr' }, { name: 'revenue.arr' }, ], starts_at: '2026-01-01T00:00:00Z', ends_at: '2026-01-31T00:00:00Z', granularity: 'month', currency: 'usd', }); response.data.forEach((row) => { const month = row.timestamp.slice(0, 7); row.results.forEach((result) => { const dollars = (result.value / 100).toFixed(2); console.log(`${month} | ${result.name}: ${dollars} ${result.currency}`); }); }); ``` ## ページネーションと `limit` パラメーター Stripe はページネーションに対応していません。代わりに、`next_page_url` と `previous_page_url` は常に `null` です。`limit` パラメーターは返される行数の上限を設定しますが、ページネーションは発生しません。API はまず `timestamp` で結果を決定論的に並べ替え、`group_by` が指定されている場合はその後にディメンション値で並べ替えるため、`limit` を小さくすると、その順序で最も早い行が返されます。 ## エラー | エラーコード | HTTP ステータス | 説明 | | ------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `not_found` | 404 | 指定したメトリクスが存在しないか、そのメトリクスが本番環境でのみアクセス可能です (サンドボックスからクエリした場合)。 | | `metric_inaccessible` | 403 | この指標を表示するために必要な権限がありません。 | | `metric_invalid_parameter_use` | 400 | 1 つのリクエスト内のメトリクスが同じ名前空間を共有していないか、メトリクスに存在しないディメンションがグループ化またはフィルタリングに指定されたか、または指定したディメンションに対してフィルター値が有効ではありません。 | | `metric_invalid_parameter_value` | 400 | パラメーター値が無効です。例えば、サポートされていない `granularity`、サポートされていない `currency` または `timezone`、`group_by` ディメンションが 1 つより多い、フィルターディメンションが 2 つより多い、フィルターあたりの値が 10 個より多い、または `limit` が 1,000 を超えている場合が該当します。 | | `metric_invalid_time_range` | 400 | 時間範囲が無効です。例えば、`starts_at` が `ends_at` より後、いずれかが未来の日付、またはリクエストした `granularity` の最大範囲を超えている場合が該当します。 | | `metric_query_rate_limit_exceeded` | 429 | 1 秒あたりのメトリッククエリが多すぎます。 | | `metric_query_concurrency_limit_exceeded` | 429 | 同時実行されるメトリッククエリが多すぎます。 | | `metric_query_metric_rate_limit_exceeded` | 429 | この特定のメトリックに対するクエリが 1 秒あたり多すぎます。 | | `metric_query_metric_concurrency_limit_exceeded` | 429 | この特定のメトリックに対する同時クエリが多すぎます。 |