Public preview
Run a SQL query programmatically Public preview
Execute ad-hoc SQL queries from the Query Run API.
You can programmatically execute SQL queries against your Stripe data using the QueryRun endpoints of the Reports API v2. This allows you to run the same queries available in the Sigma editor without using the Dashboard, enabling you to automate data extraction, schedule queries at custom intervals, and integrate Stripe data into your own systems.
Using the Query Run API
The Query Run API requires an active Sigma subscription.
API key permissions
To create and retrieve query runs, grant Read access to Financial Reports. Use the API keys page to view and manage API key permissions.
Create a QueryRun
Create a QueryRun by providing a SQL statement in the sql parameter. Use the same SQL syntax supported by the Sigma query editor. The response always includes a new QueryRun object with status=running and result=null.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
{
"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
}
Use the returned id to track the progress of the query run.
Retrieve a QueryRun
Retrieve a QueryRun to check its status. When the query completes, access the results with the URL in result.file.download_url.url.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Common mistake
The download URL is short-lived and expires after 5 minutes. If you need to regenerate it, retrieve the QueryRun object again.
Webhooks
Instead of polling, you can listen for webhooks to know when a query completes. Stripe sends a v2.data.reporting.query_run.succeeded webhook when the query run completes successfully. In case of failure, Stripe sends a v2.data.reporting.query_run.failed webhook instead. After receiving the webhook, retrieve the QueryRun and access the result URL as described above.
Additional result options
Request file compression
For large result sets, set result_options.compress_file=true to receive a zip-compressed output file.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Use an Organization API key
The Query Run API supports Organization API keys.
Run a query across your entire organization
When you use an Organization API key without a Stripe-Context header, the query runs in full organization mode—equivalent to running a query in Sigma for Organizations. In this mode, your query has access to data across all direct accounts in your organization, and an account column is available in data tables to identify which account each row belongs to.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Run a query scoped to a single account
To run a query scoped to a single account in your organization, set the Stripe-Context header to that account.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Stripe MCP
You can use the Stripe Model Context Protocol (MCP) server ’s analytics tool to query Sigma data from an AI agent or code editor. The MCP tool calls the endpoint for you, and you can build custom reports and reason with your data in natural language instead of manually constructing API requests.
Limits
For general details about APIs in the v2 namespace, see the API v2 overview. For general API rate limits, see the Rate limits page. Specific limits for the Query Run API include:
Concurrent query runs
The API limits the number of QueryRuns that can be in running state simultaneously to 500 in livemode and 100 in testmode per account or organization. If you exceed this limit, the API responds with a status code of 429. You can free up capacity by waiting for running queries to complete.
Query execution timeout
Queries that exceed 90 minutes of execution time are automatically terminated and the QueryRun moves to status=failed.
File size
The maximum supported file size for a query result is 5 GB. If you reach this limit, request compressed results by setting result_options.compress_file=true.
File retention
Query run results are retained for 90 days.