Exécuter une requête SQL par voie programmatiqueVersion bêta publique

Exécutez des requêtes SQL ad hoc à partir de l’API Query Run.

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 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 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 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 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. La réponse inclut systématiquement un nouvel objet QueryRun avec le statut status=running et un résultat result=null.

{
  "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 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.

{
  "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
}

Erreur fréquente

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 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. 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.

Utiliser une clé API d’organisation

L’API Query Run prend en charge les clés API de l’organisation.

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. 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.

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 sur ce compte.

Stripe MCP

Vous pouvez utiliser l’outil d’analyse du serveur Model Context Protocol (MCP) Stripe pour interroger les données Sigma à partir d’un agent d’IA ou d’un éditeur de code. L’outil MCP appelle l’endpoint pour vous, et vous pouvez créer des rapports personnalisés et analyser vos données en langage naturel au lieu de construire manuellement des requêtes d’API.

Limites

Pour des informations générales sur les API dans l’espace de noms v2, consultez l’aperçu de l’API v2. Pour les limites de débit générales des API, consultez la page Limites de débit. 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.