Report Runs

The Report Run object represents an instance of a report type generated with specific run parameters. Once the object is created, Stripe begins processing the report. When the report has finished running, it will give you a reference to a file where you can retrieve your results. For an overview, see API Access to Reports.

Note that certain report types can only be run based on your live-mode data (not test-mode data), and will error when queried without a live-mode API key.

Endpoints

POST/v1/reporting/report_runs

GET/v1/reporting/report_runs/:id

GET/v1/reporting/report_runs

The Report Run object

Attributes

idstring
Unique identifier for the object.

parametersobject
Parameters of this report run.

report_typestring
The ID of the report type to run, such as "balance.summary.1".

resultnullable object
The file object representing the result of the report run (populated when status=succeeded).

statusstring
Status of this report run. This will be pending when the run is initially created. When the run finishes, this will be set to succeeded and the result field will be populated. Rarely, we may encounter an error, at which point this will be set to failed and the error field will be populated.

More attributes

objectstring

createdtimestamp

errornullable string

livemodeboolean

succeeded_atnullable timestamp

The Report Run object

{
  "id": "frr_1MrQwrLkdIwHu7ixUov4x2b3",
  "object": "reporting.report_run",
  "created": 1680203749,
  "error": null,
  "livemode": false,
  "parameters": {
    "interval_end": 1680100000,
    "interval_start": 1680000000
  },
  "report_type": "balance.summary.1",
  "result": null,
  "status": "pending",
  "succeeded_at": null
}

Create a Report Run

Creates a new object and begin running the report. (Certain report types require a live-mode API key.)

Parameters

report_typestringRequired
The ID of the report type to run, such as "balance.summary.1".

parametersobject
Parameters specifying how the report should be run. Different Report Types have different required and optional parameters, listed in the API Access to Reports documentation.

Returns

Returns the new ReportRun object.

POST /v1/reporting/report_runs

Server-side language

curl https://api.stripe.com/v1/reporting/report_runs \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d report_type="balance.summary.1" \
  -d "parameters[interval_start]"=1680000000 \
  -d "parameters[interval_end]"=1680100000

Response

{
  "id": "frr_1MrQwrLkdIwHu7ixUov4x2b3",
  "object": "reporting.report_run",
  "created": 1680203749,
  "error": null,
  "livemode": false,
  "parameters": {
    "interval_end": 1680100000,
    "interval_start": 1680000000
  },
  "report_type": "balance.summary.1",
  "result": null,
  "status": "pending",
  "succeeded_at": null
}

Retrieve a Report Run

Retrieves the details of an existing Report Run.

Parameters

No parameters.

Returns

Returns the specified ReportRun object if found, and raises an error otherwise.

GET /v1/reporting/report_runs/:id

Server-side language

curl https://api.stripe.com/v1/reporting/report_runs/frr_1MrQwrLkdIwHu7ixUov4x2b3 \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

Response

{
  "id": "frr_1MrQwrLkdIwHu7ixUov4x2b3",
  "object": "reporting.report_run",
  "created": 1680203749,
  "error": null,
  "livemode": false,
  "parameters": {
    "interval_end": 1680100000,
    "interval_start": 1680000000
  },
  "report_type": "balance.summary.1",
  "result": null,
  "status": "pending",
  "succeeded_at": null
}

List all Report Runs

Returns a list of Report Runs, with the most recent appearing first.

Parameters

createdobject
Only return Report Runs that were created during the given date interval.

More parameters

ending_beforestring

limitinteger

starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit Report Runs, starting after the argument starting_after if it is provided. Each entry in the array is a separate ReportRun object. If no more Report Runs are available, the resulting array will be empty.

GET /v1/reporting/report_runs

Server-side language

curl -G https://api.stripe.com/v1/reporting/report_runs \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3

Response

{
  "object": "list",
  "url": "/v1/reporting/report_runs",
  "has_more": false,
  "data": [
    {
      "id": "frr_1MrQwrLkdIwHu7ixUov4x2b3",
      "object": "reporting.report_run",
      "created": 1680203749,
      "error": null,
      "livemode": false,
      "parameters": {
        "interval_end": 1680100000,
        "interval_start": 1680000000
      },
      "report_type": "balance.summary.1",
      "result": null,
      "status": "pending",
      "succeeded_at": null
    }
    {...}
    {...}
  ],
}

Report Runs

The Report Run object

Attributes

idstring

parametersobject

report_typestring

resultnullable object

statusstring

More attributesExpand all

objectstring

createdtimestamp

errornullable string

livemodeboolean

succeeded_atnullable timestamp

Create a Report Run

Parameters

report_typestringRequired

parametersobject

Returns

Retrieve a Report Run

Parameters

Returns

List all Report Runs

Parameters

createdobject

More parametersExpand all

ending_beforestring

limitinteger

starting_afterstring

Returns

More attributes

More parameters