Run a SQL query programmaticallyPublic 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 query runs, your API key must have both the reporting_write and sigma_api_write permissions. If your key only has reporting_read, you can retrieve existing query runs but can’t create new ones. Use the API keys page to view and manage permissions. When creating a restricted key in the Dashboard, reporting_write appears as Sigma and sigma_api_write appears as Sigma API.

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.

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

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

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.

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.

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.

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.