# Analytics API Greifen Sie programmgesteuert auf von Stripe definierte Kennzahlen zu. Die Analytics API bietet Ihnen synchronen, programmgesteuerten Zugriff auf von Stripe definierte Kennzahlen wie monatlich wiederkehrender Umsatz (MRR), jährlich wiederkehrender Umsatz (ARR) und Nutzungsumsatz. Verwenden Sie diese, um eigene Dashboards zu erstellen, Kennzahlen über einen KI-Agenten abzufragen oder Stripe-Daten in Ihre internen Tools zu integrieren. Stripe bietet drei programmgesteuerte Datenprodukte. Wählen Sie dasjenige aus, das dem Typ der benötigten Daten entspricht: - Die **Analytics API (dieses Produkt)**: Gibt von Stripe definierte Kennzahlen synchron als JSON zurück. Wählen Sie diese Option beispielsweise, wenn Sie einen kleinen Satz vordefinierter Kennzahlen auf Abruf benötigen, Kennzahlen für ein Live-Dashboard abrufen möchten oder Kennzahlen für einen KI-Agenten bereitstellen möchten. - Die [Reports API](https://docs.stripe.com/reports/api.md): Gibt große, vordefinierte Datensätze asynchron als CSV-Dateien zurück. Wählen Sie diese Option, wenn Sie einen Bulk-Export roher Transaktionsdaten nach einem festgelegten Zeitplan benötigen. - Die [Query Runs API](https://docs.stripe.com/reports/query-runs.md): Führt freies SQL asynchron anhand Ihrer rohen Stripe-Daten aus und gibt CSV-Dateien zurück. Wählen Sie diese Option, wenn Sie vollständige SQL-Flexibilität auf Basis Ihrer zugrunde liegenden Daten benötigen. ## Konzepte ### Kennzahlen Eine **Kennzahl** ist ein quantitativer Wert, der durch die Aggregation roher Stripe-Daten berechnet wird – beispielsweise MRR, ARR oder Nutzungsumsatz. Sie können auf eine Kennzahl entweder über ihre **ID** (zum Beispiel `metric_61Sud3n5oAGVCWiSr5`) oder ihren **gebräuchlichen Namen** (zum Beispiel `revenue.mrr`) verweisen. Jede Kennzahl hat eine separate ID für den Live-Modus und den Sandbox-Modus; der gebräuchliche Name ist in beiden Modi identisch. Wenn Sie sowohl `id` als auch `name` angeben, müssen beide auf dieselbe Kennzahl verweisen. Werte für monetäre Kennzahlen werden in Untereinheiten zurückgegeben (zum Beispiel Cent für USD). Werte für prozentuale Kennzahlen werden in Basispunkten zurückgegeben (zum Beispiel 100 für 1 %). Die von jeder Kennzahl zurückgegebene Einheit ist unter [Unterstützte Kennzahlen](https://docs.stripe.com/data/analytics/supported-metrics.md) aufgeführt. Kennzahlen haben häufig **Dimensionen** – Kategorie-Attribute wie `customer`, `product` oder `price` –, nach denen Sie Ergebnisse filtern oder gruppieren können. ### Namensräume für Kennzahlen Ein **Kennzahl-Namespace** ist eine Gruppe von Kennzahlen, die dieselben Dimensionen teilen. Alle Kennzahlen in einer einzelnen `metric_query`-Anfrage müssen zum selben Namespace gehören. Der Namensraum `revenue` enthält beispielsweise `revenue.mrr` und `revenue.arr`. Sie können beide nach `price`, `product`, `customer` und `subscription` filtern und sie nach weiteren Dimensionen gruppieren, darunter `price_name`, `product_name` und `customer_email`. ### Zeiträume und Granularität Jede `metric_query` gibt eine Zeitreihe mit der angegebenen `granularity` zurück. Die unterstützten Granularitäten sind `day`, `week`, `month` und `year`. Der maximale Zeitraum, den Sie abfragen können, hängt von der Granularität ab: - `day`: bis zu 92 Tage - `week`: bis zu 397 Tage - `month` und `year`: keine feste Begrenzung Bei anderen Granularitäten als `day` richtet sich die API `starts_at` und `ends_at` an der nächsten Bucket-Grenze aus, sodass jeder Zeitstempel innerhalb eines Buckets dasselbe Ergebnis liefert. Eine monatliche Abfrage mit `starts_at=2026-01-15T00:00:00Z` gibt zum Beispiel Buckets zurück, die jeweils am ersten des Monats beginnen. Wochen werden von Sonntag bis Samstag in Buckets eingeteilt. ### Sandboxes Die Analytics API funktioniert in [Sandboxes](https://docs.stripe.com/sandboxes.md). Verwenden Sie die Sandbox-ID einer Kennzahl (oder ihren gebräuchlichen Namen, der in beiden Modi identisch ist), wenn Sie aus einer Sandbox abfragen. ### Versionsverwaltung für Kennzahlen Kennzahlversionen sind an [API-Versionen](https://docs.stripe.com/upgrades.md) gebunden. Wenn sich die Definition einer Kennzahl ändert, erhält die neue Version eine neue ID, und der gebräuchliche Name verweist auf die neue Version. Frühere Versionen bleiben über ihre ID zugänglich. ## Unterstützte Kennzahlen Unter [Unterstützte Kennzahlen](https://docs.stripe.com/data/analytics/supported-metrics.md) finden Sie die vollständige Liste der verfügbaren Kennzahlen, ihrer Dimensionen, der Einheiten, in denen Ergebnisse zurückgegeben werden, sowie der Dimensionen, die Gruppierung und Filterung unterstützen. ## Beispiel Senden Sie eine `POST`-Anfrage an [`/v2/data/analytics/metric_query`](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/create.md), um Kennzahlendaten abzurufen. Der Anfragetext ist JSON; Sie müssen den `Stripe-Version`-Header angeben. ### Beispielanfrage ```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" ] }' ``` ### Beispielantwort ```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 } ] } ] } ``` Die vollständigen Anfrage- und Antwortschemata finden Sie in der [`MetricQueryResult`-API-Dokumentation](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/object.md). ## Stripe MCP verwenden Sie können das `execute_analytics`-Tool des [Stripe Model Context Protocol (MCP)-Servers](https://docs.stripe.com/mcp.md) verwenden, um Analyse-Kennzahlen von einem KI-Agenten oder einem Code-Editor abzufragen. Das MCP-Tool ruft den [`POST /v2/data/analytics/metric_query`](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/create.md)-Endpoint für Sie auf, sodass Sie Kennzahlen durch eine Beschreibung in natürlicher Sprache abrufen können, anstatt API-Anfragen manuell zu erstellen. > OAuth-Support steht für das Analytics-MCP-Tool nicht zur Verfügung. Um sich zu authentifizieren, [verwenden Sie bitte einen eingeschränkten API-Schlüssel als Bearer-Token](https://docs.stripe.com/mcp.md?mcp-client=other). ## Anwendungsszenarien ### Erstellen Sie ein internes MRR-Dashboard Sie können den täglichen MRR für einige Preise abfragen, nach Preis gruppiert, um ein internes Umsatz-Dashboard zu betreiben. ```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}`); }); ``` ### Sie können mehrere Kennzahlen im selben Namespace verfolgen Sie können MRR und ARR gemeinsam abfragen, um Trends beim wiederkehrenden Umsatz in einem einzigen Diagramm anzuzeigen. Beide Kennzahlen befinden sich im `revenue`-Namespace, sodass Sie sie in einem einzigen Aufruf abrufen können. ```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}`); }); }); ``` ## Paginierung und der `limit`-Parameter Stripe unterstützt keine Paginierung. Stattdessen sind `next_page_url` und `previous_page_url` immer `null`. Der Parameter `limit` begrenzt die Anzahl der zurückgegebenen Zeilen, löst aber keine Paginierung aus. Die API sortiert Ergebnisse deterministisch nach `timestamp` und anschließend nach Dimensionswerten, wenn `group_by` angegeben ist. Ein kleinerer `limit`-Wert gibt daher die frühesten Zeilen in dieser Reihenfolge zurück. ## Fehler | Fehlercode | HTTP-Status | Beschreibung | | ------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `not_found` | 404 | Die angegebene Kennzahl existiert nicht, oder die Kennzahl ist nur im Live-Modus zugänglich (wenn sie in einer Sandbox abgefragt wird). | | `metric_inaccessible` | 403 | Sie verfügen nicht über die erforderlichen Berechtigungen, um diese Metrik anzuzeigen. | | `metric_invalid_parameter_use` | 400 | Die Kennzahlen in einer einzelnen Anfrage teilen nicht denselben Namespace, oder Sie haben versucht, nach einer Dimension zu gruppieren oder zu filtern, die für die Kennzahl nicht existiert, oder ein Filterwert ist für die angegebene Dimension nicht gültig. | | `metric_invalid_parameter_value` | 400 | Ein Parameterwert ist ungültig – zum Beispiel eine nicht unterstützte `granularity`, eine nicht unterstützte `currency` oder `timezone`, mehr als 1 `group_by`-Dimension, mehr als 2 Filterdimensionen, mehr als 10 Werte pro Filter oder ein `limit` größer als 1.000. | | `metric_invalid_time_range` | 400 | Der Zeitraum ist ungültig – zum Beispiel liegt `starts_at` nach `ends_at`, einer der beiden Werte liegt in der Zukunft, oder der Zeitraum überschreitet das Maximum für die angeforderte `granularity`. | | `metric_query_rate_limit_exceeded` | 429 | Zu viele Metrikabfragen pro Sekunde. | | `metric_query_concurrency_limit_exceeded` | 429 | Zu viele gleichzeitige Metrikabfragen. | | `metric_query_metric_rate_limit_exceeded` | 429 | Zu viele Abfragen pro Sekunde für diese Metrik. | | `metric_query_metric_concurrency_limit_exceeded` | 429 | Zu viele gleichzeitige Abfragen für diese Metrik. |