# Eine SQL-Abfrage über die Reports API v2 ausführen Führen Sie programmatisch ad-hoc-SQL-Abfragen zu Ihren Stripe-Daten aus. Sie können SQL-Abfragen programmgesteuert mit Ihren Stripe-Daten ausführen, indem Sie die `QueryRun` Endpoints der v2 Reports-API verwenden. Dadurch können Sie dieselben Abfragen ausführen, die im [Sigma-Editor](https://docs.stripe.com/stripe-data/write-queries.md) verfügbar sind, ohne das Dashboard zu verwenden. Dies ermöglicht es Ihnen, die Datenextraktion zu automatisieren, Abfragen in benutzerdefinierten Intervallen zu planen und Stripe-Daten in Ihre eigenen Systeme zu integrieren. > #### Verwendung der Query Run API > > Die Query Run API benötigt ein aktives [Sigma](https://stripe.com/sigma)-Abonnement. ## Berechtigungen für API-Schlüssel Um Abfragen zu erstellen, muss Ihr API-Schlüssel über die Berechtigungen `reporting_write` und `sigma_api_write` verfügen. Wenn Ihr Schlüssel nur über `reporting_read` verfügt, können Sie bestehende Abfragen abrufen, aber keine neuen erstellen. Über die Seite [API-Schlüssel](https://dashboard.stripe.com/apikeys) können Sie Berechtigungen anzeigen und verwalten. Wenn Sie einen eingeschränkten Schlüssel im Dashboard erstellen, wird `reporting_write` als **Sigma** und `sigma_api_write` als **Sigma API** angezeigt. ## Erstellen eines QueryRuns [Erstellen Sie einen QueryRun](https://docs.stripe.com/api/v2/data/reporting/query-runs/create.md?api-version=2026-04-22.preview), indem Sie eine SQL-Anweisung im `sql`-Parameter bereitstellen. Verwenden Sie dieselbe SQL-Syntax, die vom [Sigma-Abfrageeditor](https://docs.stripe.com/stripe-data/write-queries.md) unterstützt wird. Die Antwort enthält ein neues [QueryRun-Objekt](https://docs.stripe.com/api/v2/data/reporting/query-runs/object.md?api-version=2026-04-22.preview) mit dem `status=running` und `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 } ``` Benutzen Sie die zurückgegebene `id` um den Fortschritt der Abfrageausführung zu verfolgen. ## Abrufen eines QueryRuns [Rufen Sie einen QueryRun ab](https://docs.stripe.com/api/v2/data/reporting/query-runs/retrieve.md?api-version=2026-04-22.preview), um seinen Status zu überprüfen. Wenn die Abfrage abgeschlossen ist, greifen Sie mit der URL in `result.file.download_url.url` auf die Ergebnisse zu. ```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 } ``` > Die Download-URL ist nur von kurzer Dauer und läuft nach 5 Minuten ab. Wenn Sie sie regenerieren müssen, rufen Sie nochmals das `QueryRun`-Objekt ab. ## Webhooks Anstelle einer Abfrage können Sie Webhooks überwachen, um zu erfahren, wann eine Abfrage abgeschlossen ist. Stripe sendet einen 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), wenn die Abfrage erfolgreich abgeschlossen wurde. Im Falle eines Fehlers sendet Stripe stattdessen einen 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). Rufen Sie nach Erhalt des Webhooks den `QueryRun` ab und greifen Sie wie oben beschrieben auf die Ergebnis-URL zu. ## Zusätzliche Ergebnisoptionen ### Anfrage-Dateikompression Für große Ergebnismengen legen Sie `result_options.compress_file=true` fest, um eine zip-komprimierte Ausgabedatei zu empfangen. ```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 } }' ``` ## Verwenden Sie einen Organisations-API-Schlüssel Die Query Run API unterstützt [Organisations-API-Schlüssel](https://docs.stripe.com/keys.md#organization-api-keys). ### Führen Sie eine Abfrage in Ihrer gesamten Organisation durch Wenn Sie einen Organisations-API-Schlüssel ohne einen verwenden `Stripe-Context`-Header verwenden, läuft die Abfrageausführung im vollen Organisationsmodus – vergleichbar mit dem Ausführen einer Abfrage in [Sigma für Organisationen](https://docs.stripe.com/stripe-data/sigma-organizations.md). In diesem Modus hat Ihre Abfrage Zugriff auf Daten aller direkten Konten Ihrer Organisation und eine `account`-Spalte ist in Datentabellen verfügbar, um zu identifizieren, zu welchem Konto jede Zeile gehört. ```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" }' ``` ### Ausführen einer Abfrage, die auf ein einziges Konto beschränkt ist Um eine Abfrage auszuführen, die auf ein einziges Konto in Ihrer Organisation beschränkt ist, richten Sie den [Stripe-Kontext](https://docs.stripe.com/context.md)-Header für dieses Konto aus. ```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" }' ``` ## Beschränkungen Allgemeine Details zu APIs im v2-Namespace finden Sie in der [API v2-Übersicht](https://docs.stripe.com/api-v2-overview.md). Allgemeine API-Begrenzungen finden Sie auf der Seite [Begrenzungen](https://docs.stripe.com/rate-limits.md). Zu den spezifischen Begrenzungen für die Query Run-API gehören: ### Gleichzeitige Abfrageausführungen Die API begrenzt die Anzahl der `QueryRuns`, die sich gleichzeitig im Status `running` befinden können, auf 500 im Live-Modus und 100 im Test-Modus pro Konto oder Organisation. Wenn Sie dieses Limit überschreiten, gibt die API den Statuscode `429` zurück. Sie können Kapazität freigeben, indem Sie warten, bis laufende Abfragen abgeschlossen sind. ### Zeitüberschreitung bei der Abfrageausführung Abfragen, die 90 Minuten Ausführungszeit überschreiten, werden automatisch beendet und der `QueryRun` wechselt in den Status `status=failed`. ### Dateigröße Die maximal unterstützte Dateigröße für ein Abfrageergebnis beträgt 5 GB. Wenn Sie diese Grenze erreichen, fordern Sie komprimierte Ergebnisse an, indem Sie `result_options.compress_file=true` einstellen. ### Aufbewahrung von Dateien Abfrageergebnisse werden 90 Tage lang gespeichert.