# Run a report from the Reports API v2

Access Stripe's reporting suite programmatically to automate your business workflow.

You can programmatically generate reports using the Reports API v2. Reports can be scoped for a single account or multiple accounts within a Stripe Organization. This API provides additional reporting options to support the existing multi-account reporting features available in the Stripe Dashboard, including [Sigma for Organizations](https://docs.stripe.com/stripe-data/sigma-organizations.md), [Stripe Data Pipeline for Organizations](https://docs.stripe.com/stripe-data/access-data-in-warehouse.md#organizations), and [multi-account Dashboard reporting](https://docs.stripe.com/reports/multiple-accounts.md).

The Reports API v2 provides several features, including:

- Integration with the [Organization API](https://docs.stripe.com/keys.md#organization-api-keys) keys, allowing for the generation of reports across multiple accounts.
- Improved speed and reliability when downloading report results.
- An option for file compression to reduce report size.
- Compatibility with *Sandboxes* (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) for testing in an isolated environment.
- Simplified report versioning reduces the need for integration updates when reports are modified with non-breaking changes.

## API key permissions

To generate reports, make sure that your API keys have the `reporting_write` permission. If your API keys only have the `reporting_read` permission, you can read the results of already generated reports, but you can’t create new ones. Use the [API keys](https://dashboard.stripe.com/apikeys) page to view the permissions associated with an API key.

## Retrieve details about a supported Report template

First, [retrieve details of a supported report template](https://docs.stripe.com/api/v2/reporting/reports/retrieve.md). The [`Report` object](https://docs.stripe.com/api/v2/reporting/reports/object.md) includes the report’s name and description, while the `parameters` field lists all required and optional parameters that the Report accepts, including field-level validations. This helps you understand the capabilities and requirements of a particular report before you request a [`ReportRun` object](https://docs.stripe.com/api/v2/reporting/report-runs/object.md). For the list of supported report IDs, see [Supported reports](https://docs.stripe.com/reports/v2-api-supported-reports.md).

```curl
curl https://api.stripe.com/v2/reporting/reports/report_test_123 \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-07-03.private"
```

```json
{
  "id": "report_test_123",
  "name": "example report",
  "object": "v2.reporting.report",
  "livemode": false,
  "parameters": {
    "interval_start": {
      "description": "Starting timestamp of data to be included.",
      "required": true,
      "type": "timestamp",
      "timestamp_details": {
        "max": "2025-01-01T00:00:00.000Z",
        "min": "2025-07-05T00:00:00.000Z"
      }
    },
    "columns": {
      "description": "The set of output columns which can be requested.",
      "required": false,
      "type": "array",
      "array_details": {
        "element_type": "enum",
        "enum_details": {
          "allowed_values": ["col_1", "col_2"]
        }
      }
    }
  }
}
```

## Request a ReportRun object

After you examine a Report template, [request a `ReportRun` object](https://docs.stripe.com/api/v2/reporting/report-runs/create.md) using report parameters to configure the data you want to access. The response includes a new [`ReportRun` object](https://docs.stripe.com/api/v2/reporting/report-runs/object.md), initialized with `status=running`, which you can use to track the progress and retrieve the results of the report. A `ReportRun` object represents an instance of a Report generated with specific run parameters.

```curl
curl -X POST https://api.stripe.com/v2/reporting/report_runs \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-07-03.private" \
  --json '{
    "report": "report_test_123",
    "report_parameters": {
        "columns": [
            "col_1",
            "col_2"
        ],
        "interval_start": "2025-06-25T00:00:00.000Z"
    }
  }'
```

## Access results after the ReportRun completes

When the run completes, Stripe sends a [`v2.reporting.report_run.succeeded`](https://docs.stripe.com/api/v2/reporting/report-runs/event-types.md#v2.reporting.report_run.succeeded) webhook. In case of failure, Stripe sends a [`v2.reporting.report_run.failed`](https://docs.stripe.com/api/v2/reporting/report-runs/event-types.md#v2.reporting.report_run.failed) webhook instead. While rare, we recommend that integrations handle this case similarly to catching a `500` response.

After receiving the webhook, [retrieve the `ReportRun`](https://docs.stripe.com/api/v2/reporting/report-runs/retrieve.md) and access the results with the URL located in `result.file.download_url.url`.

> Keep in mind that this URL is short-lived and expires after 5 minutes. If you need to regenerate the URL, retrieve the `ReportRun` object again.

```curl
curl https://api.stripe.com/v2/reporting/report_runs/reprun_123 \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-07-03.private"
```

```json
{
  "id": "reprun_123",
  "object": "v2.reporting.report_run",
  "created": "2025-07-03T01:02:29.964240312Z",
  "report": "report_test_123",
  "report_name": "example report",
  "report_parameters": {
    "columns": ["col_1","col_2"],
    "interval_start": "2025-06-25T00:00:00.000Z"
  },
  "result": {
    "file": {
      "content_type": "csv",
      "download_url": {
        "expires_at": "2025-07-03T01:10:46.679781407Z","url": "https://stripeusercontent.com/files/us-west-2/download/wksp_123/file_123/reprun_123.csv..."
      },
      "size": "209"
    },
    "type": "file"
  },
  "result_options": {
    "compress_file": false
  },
  "status": "succeeded",
  "status_details": {},
  "livemode": false
}
```

## Use an Organization API key

The Reports API v2 supports [Organization API keys](https://docs.stripe.com/keys.md#organization-api-keys) alongside account-level API keys. You can use Organization API keys in the following ways:

### Request a report for a single direct account

Use the [Stripe-Context](https://docs.stripe.com/context.md) header to target a specific direct account in your organization and pull a report for it. This eliminates the need for account API keys when retrieving a report for that account.

```curl
curl -X POST https://api.stripe.com/v2/reporting/report_runs \
  -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \
  -H "Stripe-Version: 2025-07-03.private" \
  -H "Stripe-Context: {{CONTEXT_ID}}" \
  --json '{
    "report": "report_123"
  }'
```

Use the `url` in the response to retrieve the report.

### Request a report for a single connected account

Some reports accept the `connected_account` parameter, allowing you to retrieve a report for a specific connected account. When accessing these reports, set the [Stripe-Context](https://docs.stripe.com/context.md) header to the platform account that the requested connected account belongs to.

```curl
curl -X POST https://api.stripe.com/v2/reporting/report_runs \
  -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \
  -H "Stripe-Version: 2025-07-03.private" \
  -H "Stripe-Context: {{CONTEXT_ID}}" \
  --json '{
    "report": "report_123",
    "report_parameters": {
        "connected_account": "acct_123"
    }
  }'
```

Use the `url` in the response to retrieve the report.

### Request multi-account reports

You can run reports across organizations in either aggregated or concatenated mode. Every report can be run in “concatenated” mode, but only some reports can be run in “aggregated” mode. If you run a report that supports both modes, you must set the `organization_report_granularity` report parameter to either `concatenated_report` or `aggregated_report`.

#### Request a multi-account concatenated report

You can run separate reports for each direct account in your organization and concatenate the results into a single file. For example, you can retrieve separate balance summary reports for each account.

To use this feature, set `organization_report_granularity` to `concatenated_report` if the report you’re running supports both aggregated and concatenated modes, and omit the [Stripe-Context](https://docs.stripe.com/reports/v2-api.md#concurrent-report-runs) header.

```curl
curl -X POST https://api.stripe.com/v2/reporting/report_runs \
  -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \
  -H "Stripe-Version: 2025-07-03.private" \
  --json '{
    "report": "report_123",
    "report_parameters": {
        "organization_report_granularity": "concatenated_report"
    }
  }'
```

If the report only supports concatenated mode, omit `organization_report_granularity`.

```curl
curl -X POST https://api.stripe.com/v2/reporting/report_runs \
  -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \
  -H "Stripe-Version: 2025-07-03.private" \
  --json '{
    "report": "report_123",
    "report_parameters": {}
  }'
```

Use the `url` in the response to retrieve the concatenated report.

#### Request a multi-account aggregated report

Some reports allow you to aggregate results across all direct accounts in your organization. For example, you can retrieve a single balance summary report that sums across all accounts. To use this option, don’t set the [Stripe-Context](https://docs.stripe.com/context.md) header, and set the report parameter `organization_report_granularity` to `aggregated_report`.

```curl
curl -X POST https://api.stripe.com/v2/reporting/report_runs \
  -H "Authorization: Bearer {{ORG_SECRET_KEY}}" \
  -H "Stripe-Version: 2025-07-03.private" \
  --json '{
    "report": "report_123",
    "report_parameters": {
        "organization_report_granularity": "aggregated_report"
    }
  }'
```

Use the `url` in the response to retrieve the aggregated report.

## Limits

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

### Concurrent report runs

The API limits the number of `ReportRuns` that can be `running` simultaneously. If you request a `ReportRun` after reaching the limits listed below, the API responds with a status code of `429`.

- **Live mode**: 500 running reports
- ***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)**: 100 running reports

### File size

The maximum supported file size for a report is 5 GB. If you reach this limit, request compressed results by setting the parameter `result_options.compress_file=true` when creating a `ReportRun`.

### File retention

The results of reports are retained for 90 days.

## Private preview considerations

The Reports API v2 is currently in [private preview](https://docs.stripe.com/release-phases.md). Here are key considerations:

- **Support for the v1 Reporting API**: The v1 Reporting API and any integrations continue to function as they do today. Transitioning to the Reports API v2 won’t disrupt existing v1 integrations.
- **No SDK support**: Because we don’t provide SDK support, you must access the API directly.