# Access Stripe data with the API

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

Use the Queries API and Reports API to analyze Stripe data from your own systems. You can browse the available data, programmatically access Stripe’s financial reports, and generate custom analysis.

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.

## Concepts 

### Dataset

A `Dataset` is a collection of tables with the same set of performance characteristics. The Queries and Reports API uses 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), in Stripe Sigma, and with Stripe Data Pipeline.

### 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 SQL 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 

Start with the resource that matches the job:

[Search data resources](https://docs.stripe.com/data/api/search.md): Find schemas, metrics, and reports relevant to a natural-language question, then use the corresponding API to query your data.

[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/queries.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 SQL query templates, then create a `ReportRun` with the parameters that report accepts.

## 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-10-28.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/queries.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/queries.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.compression` to `zip` 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 [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/queries.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 Queries and Reports 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:

|  |
| Run creation rate | You can create 10 `QueryRun` objects and 5 `ReportRun` objects per second in live mode, and 1 of each per second 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). These limits apply per account or organization. |
| Concurrent runs | You can have 100 `QueryRun` objects and 50 `ReportRun` objects in the `running` state at the same time in live mode, and 10 of each in a sandbox. These limits apply per account or organization. Wait for in-progress runs to finish before creating new ones. |
| Query execution timeout | Queries that run longer than 90 minutes fail with `status_details.code` set to `resource_limit_exceeded`. See [Handle a failed query](https://docs.stripe.com/data/api/queries.md#handle-a-failed-query). |
| File size | 5 GB per result file. If the result exceeds this limit, the run fails with `status_details.code` set to `file_size_above_limit`. Set `result_options.compression` to `zip` if you reach this limit. |
| File retention | Stripe retains result files for 90 days. |
| Download URL lifetime | File download URLs expire after 5 minutes. |

Requests that exceed the run creation rate or concurrent run limits return a `429` status code. Stripe also limits query runs and report runs across all accounts. This means you can receive a `429` even when you’re within your own limits. Retry with exponential backoff.

## See also

- [Browse table schemas](https://docs.stripe.com/data/api/schemas.md)
- [Run a SQL query](https://docs.stripe.com/data/api/queries.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)
