# Exécuter une requête SQL depuis l’API Reports v2 Exécuter des requêtes SQL ad hoc sur vos données Stripe par voie programmatique. Vous pouvez exécuter des requêtes SQL par voie programmatique sur vos données Stripe en utilisant les endpoints `QueryRun` de l’API Reports v2. Cela vous permet d’exécuter les mêmes requêtes que celles disponibles dans l’[éditeur Sigma](https://docs.stripe.com/stripe-data/write-queries.md) sans utiliser le Dashboard, et ainsi d’automatiser l’extraction des données, de planifier des requêtes à des intervalles personnalisés et d’intégrer les données Stripe à vos propres systèmes. > #### Utilisation de l’API Query Run > > L’API Query Run nécessite un abonnement [Sigma](https://stripe.com/sigma) actif. ## Autorisations liées à la clé API Pour créer des exécutions de requêtes, votre clé API doit disposer des autorisations `reporting_write` et `sigma_api_write`. Si votre clé ne dispose que de `reporting_read`, vous pouvez récupérer des exécutions de requêtes existantes, mais pas en créer de nouvelles. Utilisez la page [API keys](https://dashboard.stripe.com/apikeys) pour consulter et gérer les autorisations. Lors de la création d’une clé restreinte dans le Dashboard, `reporting_write` apparaît comme **Sigma** et `sigma_api_write` apparaît comme **Sigma API**. ## Créer une QueryRun [Créez un QueryRun](https://docs.stripe.com/api/v2/data/reporting/query-runs/create.md?api-version=2026-04-22.preview) en fournissant une instruction SQL dans le paramètre `sql`. Utilisez la même syntaxe SQL que celle prise en charge par l’[éditeur de requêtes Sigma](https://docs.stripe.com/stripe-data/write-queries.md). La réponse inclut systématiquement un nouvel [objet QueryRun](https://docs.stripe.com/api/v2/data/reporting/query-runs/object.md?api-version=2026-04-22.preview) avec le statut `status=running` et un résultat `result=null`. ```curl curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "sql": "SELECT * FROM balance_transactions LIMIT 10" }' ``` ```json { "id": "qryrun_123", "object": "v2.data.reporting.query_run", "created": "2025-07-03T01:02:29.964Z", "sql": "SELECT * FROM balance_transactions LIMIT 10", "status": "running", "result": null, "result_options": { "compress_file": false, "result_type": "file" }, "livemode": false } ``` Utilisez l’`ID` renvoyé pour suivre l’avancement de l’exécution de la requête. ## Récupérer une QueryRun [Récupérez un QueryRun](https://docs.stripe.com/api/v2/data/reporting/query-runs/retrieve.md?api-version=2026-04-22.preview) pour vérifier son état. Une fois la requête terminée, accédez aux résultats à l’aide de l’URL figurant dans `result.file.download_url.url`. ```curl curl https://api.stripe.com/v2/data/reporting/query_runs/qryrun_123 \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" ``` ```json { "id": "qryrun_123", "object": "v2.data.reporting.query_run", "created": "2025-07-03T01:02:29.964Z", "sql": "SELECT * FROM balance_transactions LIMIT 10", "status": "succeeded", "result": { "file": { "content_type": "csv", "download_url": { "expires_at": "2025-07-03T01:10:46.679Z","url": "https://stripeusercontent.com/files/us-west-2/download/wksp_123/file_123/qryrun_123.csv..." }, "size": "512" }, "type": "file" }, "result_options": { "compress_file": false, "result_type": "file" }, "livemode": false } ``` > L’URL de téléchargement est éphémère et expire au bout de 5 minutes. Si vous devez la régénérer, récupérez de nouveau l’objet `QueryRun`. ## Webhooks Au lieu d’interroger l’API à intervalles réguliers, vous pouvez écouter les webhooks pour savoir quand une requête est terminée. Stripe envoie un webhook [v2.data.reporting.query_run.succeeded](https://docs.stripe.com/api/v2/data/reporting/query-runs/event-types.md?api-version=2026-04-22.preview#v2.data.reporting.query_run.succeeded) lorsque l’exécution de la requête se termine avec succès. En cas d’échec, Stripe envoie à la place un webhook [v2.data.reporting.query_run.failed](https://docs.stripe.com/api/v2/data/reporting/query-runs/event-types.md?api-version=2026-04-22.preview#v2.data.reporting.query_run.failed). Après avoir reçu le webhook, récupérez le `QueryRun` et accédez à l’URL du résultat comme décrit ci-dessus. ## Options de résultat supplémentaires ### Requête de compression de fichier Pour les grands ensembles de résultats, définissez `result_options.compress_file=true` pour recevoir un fichier de sortie compressé au format ZIP. ```curl curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "sql": "SELECT * FROM balance_transactions", "result_options": { "compress_file": true } }' ``` ## Utiliser une clé API d’organisation L’API Query Run prend en charge les [clés de l’API Organization](https://docs.stripe.com/keys.md#organization-api-keys). ### Exécuter une requête dans toute votre organisation Lorsque vous utilisez une clé de l’API Organization sans en-tête `Stripe-Context`, la requête s’exécute dans toute l’organisation, ce qui équivaut à exécuter une requête dans [Sigma for Organizations](https://docs.stripe.com/stripe-data/sigma-organizations.md). Dans ce mode, votre requête a accès aux données de tous les comptes directs de votre organisation, et une colonne `account` est disponible dans les tables de données pour identifier à quel compte appartient chaque ligne. ```curl curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \ -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \ -H "Stripe-Version: 2026-04-22.preview" \ --json '{ "sql": "SELECT account, id, amount FROM balance_transactions LIMIT 10" }' ``` ### Exécuter une requête sur un seul compte Pour exécuter une requête portant sur un seul compte de votre organisation, définissez l’en-tête [Stripe-Context](https://docs.stripe.com/context.md) sur ce compte. ```curl curl -X POST https://api.stripe.com/v2/data/reporting/query_runs \ -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \ -H "Stripe-Version: 2026-04-22.preview" \ -H "Stripe-Context: {{CONTEXT_ID}}" \ --json '{ "sql": "SELECT * FROM balance_transactions LIMIT 10" }' ``` ## Limites Pour des informations générales sur les API dans l’espace de noms v2, consultez l’[aperçu de l’API v2](https://docs.stripe.com/api-v2-overview.md). Pour les limites de débit générales des API, consultez la page [Limites de débit](https://docs.stripe.com/rate-limits.md). Les limites spécifiques à l’API Query Run comprennent : ### Requêtes exécutées simultanément L’API limite le nombre de `QueryRuns` pouvant être `en cours d’exécution` simultanément à 500 en mode production et à 100 en mode test par compte ou organisation. Si vous dépassez cette limite, l’API renvoie un code d’état `429`. Vous pouvez libérer de la capacité en attendant que les requêtes en cours se terminent. ### Délai d’exécution des requêtes Les requêtes dont le temps d’exécution dépasse 90 minutes sont automatiquement interrompues, et le `QueryRun` passe à `status=failed`. ### Taille de fichier La taille maximale de fichier prise en charge pour un résultat de requête est de 5 Go. Si vous atteignez cette limite, la requête compresse les résultats en définissant `result_options.compress_file=true`. ### Conservation des fichiers Les résultats de l’exécution de la requête sont conservés pendant 90 jours.