Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Create a Report Run v2

Reporting
Report Runs
Create a Report Run

Initiates the generation of a ReportRun based on the specified report template and user-provided parameters. It’s the starting point for obtaining report data, and returns a ReportRun object which can be used to track the progress and retrieve the results of the report.

Learn more about calling API v2 endpoints.

Parameters

  • reportstringRequired

    The unique identifier of the Report being requested.

  • report_parametersmapRequired

    A map of parameter names to values, specifying how the report should be customized. The accepted parameters depend on the specific Report being run.

  • result_optionsobject

    Optional settings to customize the results of the ReportRun.

    • result_options.compress_fileboolean

      If set, the generated report file will be compressed into a ZIP folder. This is useful for reducing file size and download time for large reports.

Returns

Response attributes

  • idstring

    The unique identifier of the ReportRun object.

  • objectstring, value is "v2.reporting.report_run"

    String representing the object’s type. Objects of the same type share the same value of the object field.

  • createdtimestamp

    Time at which the object was created.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • reportstring

    The unique identifier of the Report object which was run.

  • report_namestring

    The human-readable name of the Report which was run.

  • report_parametersmap

    The parameters used to customize the generation of the report.

  • resultnullable object

    Details how to retrieve the results of a successfully completed ReportRun.

    • result.fileobject

      Contains metadata about the file produced by the ReportRun, including its content type, size, and a URL to download its contents.

      • result.file.content_typeenum

        The content type of the file.

        Possible enum values
        csv

        CSV content type. Mime type of text/csv.

        zip

        ZIP content type. Mime type of application/zip.

      • result.file.download_urlobject

        A pre-signed URL that allows secure, time-limited access to download the file.

        • result.file.download_url.expires_atnullable timestamp

          The time that the URL expires.

        • result.file.download_url.urlstring

          The URL that can be used for accessing the file.

      • result.file.sizeinteger

        The total size of the file in bytes.

    • result.typeenum

      The type of the ReportRun result.

      Possible enum values
      file

      File result type.

  • result_optionsnullable object

    The options specified for customizing the output file of the ReportRun.

    • result_options.compress_filenullable boolean

      If set, the generated report file will be compressed into a ZIP folder. This is useful for reducing file size and download time for large reports.

  • statusenum

    The current status of the ReportRun.

    Possible enum values
    failed

    Report has failed to complete due to an error.

    running

    Report generation is in progress.

    succeeded

    Report has successfully generated.

  • status_detailsmap

    Additional details about the current state of the ReportRun. The field is currently only populated when a ReportRun is in the failed state, providing more information about why the report failed to generate successfully.

Error Codes
429report_run_rate_limit_exceeded

Returned when an API key has reached its limit of concurrently running reports. Wait for existing reports to complete before retrying the request.

POST /v2/reporting/report_runs
cURL
curl -X POST https://api.stripe.com/v2/reporting/report_runs \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2026-01-28.preview" \
  --json '{
    "report": "report_test_xxx",
    "report_parameters": {
        "interval_start": "2025-08-18T00:00:00.000Z",
        "interval_end": "2025-08-25T00:00:00.000Z"
    }
  }'
Response
{
  "created": "2025-08-26T00:00:00.000Z",
  "id": "reprun_test_xxx",
  "object": "v2.reporting.report_run",
  "report": "report_test_xxx",
  "report_name": "test report name",
  "report_parameters": {
    "interval_start": "2025-08-18T00:00:00.000Z",
    "interval_end": "2025-08-25T00:00:00.000Z"
  },
  "result": null,
  "result_options": {
    "compress_file": false
  },
  "status": "running",
  "status_details": {},
  "livemode": false
}