# Access Stripe data with the API

Run SQL queries, generate reports, and browse table schemas programmatically.

Use the API to analyze Stripe data from your own systems. You can browse the available data, run the same SQL available in the [Sigma query editor](https://docs.stripe.com/data/write-queries.md), and generate custom reports.

If you’re using the [Reports API v2](https://docs.stripe.com/reports/v2-api.md) or the [Query Run API](https://docs.stripe.com/reports/query-runs.md), this API consolidates improved functionality into a single Data API.

A typical workflow looks like this: authenticate, [discover the tables](https://docs.stripe.com/data/api/schemas.md) or [reports](https://docs.stripe.com/data/api/reports.md) you can run, [create a run](https://docs.stripe.com/data/api.md#create-a-run) with SQL or a report name, then [retrieve the results](https://docs.stripe.com/data/api.md#get-results) after the run completes.

### Request to join the preview for the Data API.

Enter your email to request access.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/data/api" \
  -d '{"email": "EMAIL", "preview": "analytics_core_eng_preview"}'
```

## Concepts 

### Dataset

A `Dataset` is a collection of tables with the same set of performance characteristics. The Data API consists of one dataset: `analytical`. It’s the same set of tables you see in the Dashboard’s [Stripe data schema](https://docs.stripe.com/data/schema.md), and in Sigma.

### Schema

A `Schema` describes one table: its name, columns, data types, and keys. List schemas when you need to know which tables and columns you can query. See [Browse table schemas](https://docs.stripe.com/data/api/schemas.md).

### Report

A `Report` is a named template with parameters, such as `balance.summary` and a date range. Stripe-defined reports and Sigma query templates both appear as reports. You pass the report name and parameters; you don’t write the SQL. See [Run a report](https://docs.stripe.com/data/api/reports.md).

### Run

Queries and reports don’t return rows in the create response. They run asynchronously, and a “run” is the job that tracks that work.

- A `QueryRun` executes SQL you send in `query.sql`.
- A `ReportRun` executes a report template with the parameters you pass.

Creating a run returns an object immediately with an `id` and `status=running`. `result` is empty until the job finishes. When the run succeeds or fails, `status` becomes `succeeded` or `failed`. Retrieve the same `id` to download a CSV or page rows in the API response.

## Choose an API 

> #### Sigma for query runs
> 
> Creating a query run requires an active [Sigma](https://stripe.com/sigma) subscription. Some reports also require Sigma.

Start with the resource that matches the job:

[Browse table schemas](https://docs.stripe.com/data/api/schemas.md): List and retrieve `Schema` objects to see table names, columns, types, and foreign keys before you write SQL.

[Run a SQL query](https://docs.stripe.com/data/api/query-runs.md): Create a `QueryRun` with ad-hoc SQL against the `analytical` dataset, then download or page the results.

[Run a report](https://docs.stripe.com/data/api/reports.md): List Stripe-defined reports and Sigma query templates, then create a `ReportRun` with the parameters that report accepts.

## Get SQL to run 

A query run needs a SQL string in `query.sql`. You don’t have to write it from scratch:

- Copy a query you’ve already written or saved in the [Sigma query editor](https://docs.stripe.com/data/write-queries.md).
- Ask a coding agent in natural language with the [Stripe MCP server](https://docs.stripe.com/data/analyze-with-ai.md). For example: “Total my refunds by month for this year.”
- [List table schemas](https://docs.stripe.com/data/api/schemas.md), then start from a table name, such as `SELECT id, amount, currency FROM balance_transactions LIMIT 10`.
- Skip SQL and [run a report](https://docs.stripe.com/data/api/reports.md) instead. Reports use parameters, not a SQL string you supply.

The API accepts the same ANSI SQL as Sigma.

## Required permissions 

Grant only the permissions you need on a [restricted API key](https://dashboard.stripe.com/apikeys):

- Go to **Data** > **Queries** > **Read** (`data_queries_read`) to list and retrieve schemas and to create and retrieve query runs.
- Go to **Data** > **Reports** > **Read** (`data_reports_read`) to list and retrieve reports and to create and retrieve report runs.

To grant these permissions:

1. Go to the [API keys](https://dashboard.stripe.com/apikeys) page in the Dashboard.
2. Create or edit a restricted key.
3. Enable **Data** > **Queries** > **Read**, **Data** > **Reports** > **Read**, or both.

Creating a query run or report run is a read of your data. You don’t need write access.

## Authenticate requests 

Send a [restricted API key](https://docs.stripe.com/data/api.md#required-permissions) in the `Authorization` header. v2 requests also require a `Stripe-Version` header.

```curl
curl https://api.stripe.com/v2/data/schemas \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-09-30.preview"
```

## Create a run 

After you authenticate, create a run. That’s the request that actually executes a query or report.

- [Create a QueryRun](https://docs.stripe.com/data/api/query-runs.md#create-query-run) with SQL in `query.sql`.
- [Create a ReportRun](https://docs.stripe.com/data/api/reports.md#create-report-run) with a report `name` or `id` and that report’s parameters.

The create response includes an `id` and `status=running`. Results aren’t ready yet. Save the `id` so you can retrieve the run.

## Get results 

When the run completes, [retrieve the QueryRun](https://docs.stripe.com/data/api/query-runs.md#retrieve-query-run) or [retrieve the ReportRun](https://docs.stripe.com/data/api/reports.md#retrieve-report-run). You can poll for `status=succeeded`, or [listen for webhooks](https://docs.stripe.com/data/api.md#webhooks) instead.

When a run succeeds, the default result is a file:

- Read the download URL at `result.file.download_url.url`.
- The URL expires after 5 minutes. Retrieve the run again to get a new URL.
- Results are retained for 90 days.
- The maximum file size is 5 GB. For large results, set `result_options.compress_file` to `true` when you create the run.
- The only supported `format` is `csv`.

To page rows in the API response instead of downloading a file, retrieve the run with `include[0]=result.inline`. Inline pages default to 100 rows and accept a `limit` up to 1,000. Keep the same `limit` on every request in a pagination sequence.

## Use the Stripe MCP 

You can use the [Stripe Model Context Protocol (MCP) server](https://docs.stripe.com/mcp.md) to run queries and reports from an AI agent or code editor. The `stripe_analytics` tool calls [POST /v2/data/query_runs](https://docs.stripe.com/api/v2/data/query-runs/create.md) for SQL, and the `stripe_reports` tool calls [POST /v2/data/report_runs](https://docs.stripe.com/api/v2/data/report-runs/create.md) for Stripe-defined reports, so you can describe what you want in natural language rather than constructing API requests manually.

## Webhooks 

Listen for these events instead of polling:

- `v2.data.query_run.succeeded` and `v2.data.query_run.failed`
- `v2.data.report_run.succeeded` and `v2.data.report_run.failed`

After receiving a succeeded or failed event, retrieve the query run and read `result` or `status_details`. For a failed query run, `status_details.code` is `query_run_invalid_sql`, `file_size_above_limit`, or `internal_error`. See [Handle a failed query](https://docs.stripe.com/data/api/query-runs.md#handle-a-failed-query). Before processing these events, [verify incoming webhook signatures](https://docs.stripe.com/webhooks.md#verify-events) and review the Stripe [public IP addresses](https://docs.stripe.com/ips.md).

## Use an Organization API key 

The Data API accepts [Organization API keys](https://docs.stripe.com/keys/organization-api-keys.md).

- Omit `Stripe-Context` to run across every direct account in the organization. Query results include an `account` column.
- Set [Stripe-Context](https://docs.stripe.com/context.md) to scope a request to one account.

Report templates that support both modes can accept an `organization_report_granularity` parameter of `concatenated_report` or `aggregated_report`. See [Run a report](https://docs.stripe.com/data/api/reports.md#organization-api-key).

## Limits 

For general details about APIs in the v2 namespace, see the [API v2 overview](https://docs.stripe.com/api-v2-overview.md). For general API rate limits, see [Rate limits](https://docs.stripe.com/rate-limits.md). Specific limits include:

|  |
| Concurrent runs | 500 query runs or report runs can be `running` at the same time in live mode, and 100 in a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes). Requests that exceed the limit return a `429` status code. |
| Query execution timeout | Queries that run longer than 90 minutes fail. |
| File size | 5 GB per result file. Request `result_options.compress_file=true` if you reach this limit. |
| File retention | Stripe retains result files for 90 days. |
| Download URL lifetime | File download URLs expire after 5 minutes. |

## See also

- [Browse table schemas](https://docs.stripe.com/data/api/schemas.md)
- [Run a SQL query](https://docs.stripe.com/data/api/query-runs.md)
- [Run a report](https://docs.stripe.com/data/api/reports.md)
- [Write queries using Sigma](https://docs.stripe.com/data/write-queries.md)
- [Analyze your Stripe data with AI](https://docs.stripe.com/data/analyze-with-ai.md)