# API Analytics Accédez par voie programmatique aux indicateurs définis par Stripe. L’API Analytics vous offre un accès synchrone et programmatique aux indicateurs définis par Stripe, tels que le revenu récurrent mensuel (MRR), le revenu récurrent annuel (ARR) et les revenus d’utilisation. Utilisez-la pour créer vos propres dashboards, interroger des indicateurs depuis un agent d’IA ou intégrer des données Stripe dans vos outils internes. Stripe propose trois produits de données programmatiques. Choisissez celui qui correspond au type de données dont vous avez besoin : - L’**API Analytics (ce produit)** : renvoie les indicateurs définis par Stripe de manière synchrone, au format JSON. Choisissez cette API, par exemple, lorsque vous souhaitez obtenir un petit ensemble d’indicateurs préconfigurés à la demande. Vous pourrez ainsi utiliser ces indicateurs dans un dashboard en mode production ou les exposer à un agent d’IA. - L’[API Reports](https://docs.stripe.com/reports/api.md) : renvoie de grands ensembles de données préconfigurés de manière asynchrone sous forme de fichiers CSV. Choisissez cette API lorsque vous avez besoin d’une exportation en masse de données de transactions brutes selon un calendrier défini. - L’[API Query Runs](https://docs.stripe.com/reports/query-runs.md) : exécute des requêtes SQL libres sur vos données Stripe brutes de manière asynchrone et renvoie des fichiers CSV. Choisissez cette API lorsque vous avez besoin d’une flexibilité SQL complète sur vos données sous-jacentes. ## Concepts ### Indicateurs Un **indicateur** est une valeur quantitative calculée en agrégeant des données Stripe brutes, par exemple le MRR, l’ARR ou les revenus d’utilisation. Vous pouvez référencer un indicateur par son **ID** (par exemple, `metric_61Sud3n5oAGVCWiSr5`) ou par son **nom commun** (par exemple, `revenue.mrr`). Chaque indicateur possède un ID distinct pour le mode production et l’environnement de test. Le nom commun est identique dans les deux modes. Si vous fournissez à la fois `id` et `name`, ils doivent faire référence au même indicateur. Les valeurs d’indicateurs monétaires sont renvoyées en unités mineures (par exemple, en centimes pour le dollar). Les valeurs d’indicateurs en pourcentage sont renvoyées en points de base (par exemple, 100 pour 1 %). L’unité renvoyée par chaque indicateur est indiquée sur la page [Indicateurs pris en charge](https://docs.stripe.com/data/analytics/supported-metrics.md). Les indicateurs ont souvent des **dimensions**, c’est-à-dire des attributs catégoriels tels que `customer`, `product` ou `price`. Vous pouvez filtrer ou regrouper les résultats selon ces attributs. ### Espaces de noms des indicateurs Un **espace de noms d’indicateurs** est un groupe d’indicateurs partageant les mêmes dimensions. Tous les indicateurs d’une même requête `metric_query` doivent appartenir au même espace de noms. Par exemple, l’espace de noms `revenue` contient `revenue.mrr` et `revenue.arr`. Vous pouvez filtrer les deux par `price`, `product`, `customer` et `subscription`, et les regrouper selon des dimensions supplémentaires, notamment `price_name`, `product_name` et `customer_email`. ### Plages temporelles et granularité Chaque `metric_query` renvoie une série temporelle à la granularité (`granularity`) spécifiée. Les granularités prises en charge sont `day`, `week`, `month` et `year`. La plage temporelle maximale qu’il est possible d’interroger dépend de la granularité : - `day` : jusqu’à 92 jours - `week` : jusqu’à 397 jours - `month` et `year` : aucune limite fixe Pour les granularités autres que `day`, l’API aligne `starts_at` et `ends_at` sur la limite de compartiment la plus proche, de sorte que tout horodatage au sein d’un compartiment produit le même résultat. Par exemple, une requête mensuelle avec `starts_at=2026-01-15T00:00:00Z` renvoie des compartiments commençant le premier de chaque mois. Les semaines sont regroupées du dimanche au samedi. ### Environnements de test L’API Analytics fonctionne dans les [environnements de test](https://docs.stripe.com/sandboxes.md). Utilisez l’ID de l’environnement de test d’un indicateur (ou son nom commun, identique pour le mode production et l’environnement de test) lorsque vous effectuez une requête depuis un environnement de test. ### Gestion des versions des indicateurs Les versions des indicateurs sont liées aux [versions de l’API](https://docs.stripe.com/upgrades.md). Lorsque la définition d’un indicateur change, la nouvelle version reçoit un nouvel ID et le nom commun pointe vers la nouvelle version. Les versions précédentes restent accessibles via leur ID. ## Indicateurs pris en charge Rendez-vous sur la page [Indicateurs pris en charge](https://docs.stripe.com/data/analytics/supported-metrics.md) pour consulter la liste complète des indicateurs disponibles, leurs dimensions, les unités dans lesquelles les résultats sont renvoyés, ainsi que les dimensions prenant en charge le regroupement et le filtrage. ## Exemple Envoyez une requête `POST` à [`/v2/data/analytics/metric_query`](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/create.md) pour récupérer des données d’indicateurs. Le corps de la requête est en JSON. Vous devez inclure l’en-tête `Stripe-Version`. ### Exemple de requête ```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" ] }' ``` ### Exemple de réponse ```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 } ] } ] } ``` Pour les schémas complets de requête et de réponse, consultez la [documentation de l’API `MetricQueryResult`](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/object.md). ## Utiliser le MCP Stripe Vous pouvez utiliser l’outil `execute_analytics` du [serveur Stripe Model Context Protocol (MCP)](https://docs.stripe.com/mcp.md) pour interroger des indicateurs analytiques depuis un agent d’IA ou un éditeur de code. L’outil MCP appelle l’endpoint [`POST /v2/data/analytics/metric_query`](https://docs.stripe.com/api/v2/data/analytics/metric-query-results/create.md) pour vous, ce qui vous permet de récupérer des indicateurs en décrivant ce que vous souhaitez en langage naturel plutôt qu’en construisant manuellement des requêtes API. > La prise en charge d’OAuth n’est pas disponible pour l’outil Analytics MCP. Pour vous identifier, [utilisez une clé API limitée comme token porteur](https://docs.stripe.com/mcp.md?mcp-client=other). ## Cas d’usage ### Créer un Dashboard interne de MRR Interrogez le MRR quotidien pour plusieurs prix, regroupé par prix, pour alimenter un dashboard interne des revenus. ```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}`); }); ``` ### Suivez plusieurs indicateurs dans le même espace de noms Interrogez le MRR et l’ARR ensemble pour afficher les tendances des revenus récurrents dans un seul graphique. Les deux indicateurs appartiennent à l’espace de noms `revenue`, vous pouvez donc les récupérer en une seule requête API. ```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}`); }); }); ``` ## Pagination et paramètre `limit` Stripe ne prend pas en charge la pagination, et la valeur de `next_page_url` et de `previous_page_url` est toujours `null`. Le paramètre `limit` plafonne le nombre de lignes renvoyées mais ne déclenche pas de pagination. L’API trie les résultats de manière déterministe par `timestamp`, puis par valeurs de dimension lorsque `group_by` est spécifié. Ainsi, une valeur `limit` plus petite renvoie les premières lignes dans cet ordre. ## Erreurs | Code d’erreur | État HTTP | Description | | ------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `not_found` | 404 | L’indicateur spécifié n’existe pas ou il n’est accessible qu’en mode production (lorsqu’il est interrogé depuis un environnement de test). | | `metric_inaccessible` | 403 | Vous ne disposez pas des autorisations nécessaires pour afficher cet indicateur. | | `metric_invalid_parameter_use` | 400 | Les indicateurs d’une même requête ne partagent pas le même espace de noms, ou vous avez tenté de regrouper ou de filtrer selon une dimension qui n’existe pas sur l’indicateur, ou une valeur de filtre n’est pas valide pour la dimension spécifiée. | | `metric_invalid_parameter_value` | 400 | Une valeur de paramètre n’est pas valide, par exemple une `granularity` non prise en charge, une `currency` ou un `timezone` non pris en charge, plus d’une dimension `group_by`, plus de 2 dimensions de filtre, plus de 10 valeurs par filtre, ou une valeur `limit` supérieure à 1 000. | | `metric_invalid_time_range` | 400 | La plage temporelle n’est pas valide, par exemple `starts_at` est postérieur à `ends_at`, l’un ou l’autre est dans le futur, ou la plage dépasse le maximum autorisé pour la `granularity` demandée. | | `metric_query_rate_limit_exceeded` | 429 | Trop de requêtes d’indicateurs par seconde. | | `metric_query_concurrency_limit_exceeded` | 429 | Trop de requêtes d’indicateurs simultanées. | | `metric_query_metric_rate_limit_exceeded` | 429 | Trop de requêtes par seconde pour cet indicateur spécifique. | | `metric_query_metric_concurrency_limit_exceeded` | 429 | Trop de requêtes simultanées pour cet indicateur spécifique. |