Report Runs

Submit a report layout for execution, poll the run, and download the result file.

Operations

Run a report

Request

Submits a report layout for background execution and returns the new run. A 200 response means the run was accepted, not that the file is ready. Poll Get a report run until status is Available, then call Get a download URL.

Purpose: Produce report files on demand from your own scheduler, for example at period close or for an auditor extract, without using the Zuora Revenue user interface.

When to use: Each time you need a fresh report file: period close, an auditor request, a scheduled data feed, or an on-demand extract triggered by another system.

Notes:

Filters are merged with the layout's saved defaults: omit filters to use all defaults; send some filters to override only those (your values win, defaults fill the rest); send [] to use no filters.
Required layout filters are checked after the merge. If any is still missing, the run is rejected with 400 and the labels of the missing filters.
$revpro.CurrPrd and $revpro.PriorPrd are replaced with the current or prior open period of the book and organization. If that cannot be resolved (for example several organizations with different open periods), the run is rejected with errorCode INVALID_PERIOD_ORG; send a concrete period name or organization instead.
Date values use YYYY-MM-DD. The value -999 means All for book, period and organization filters.
Use a layoutId returned by List layouts for the same report. Operators outside the documented list are not supported and can make the run fail.

Request definition

Parameter	In	Type	Required	Description
`reportId`	path	integer	Yes	Identifier of the report to run.
`Accept-Language`	header	string	No	Optional language for translated report names, labels and filter options, for example `en` or `ja`. Defaults to the user's profile language.
`Zuora-Track-Id`	header	string	No	Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.
`Authorization`	header	string	Yes	`Bearer <access_token>` (Zuora OneID OAuth).

Request body (required, application/json): RunReportRequest

RunReportRequest: Request body that submits a report layout for execution.

Field	Type	Required	Description
`layoutId`	integer	Yes	Identifier of the layout to run. Use a layout returned by List layouts for the same report.
`filters`	array of ReportFilterParam	No	Filter conditions. Omit the property (or send `null`) to apply all saved layout defaults. Send a partial list to override some filters; layout defaults fill in the rest. Send `[]` to run with no filters at all (required filters are still enforced).
`filters[].fieldName`	string	Yes	Field to filter on, in lowerCamelCase as returned by the layout operations (for example `periodName`). The service converts it to the stored field key.
`filters[].operator`	string	No	Comparison operator. When omitted, `=` is used. See Filter operators for the value rules of each operator. Allowed: `=`, `!=`, `<`, `<=`, `>`, `>=`, `LIKE`, `NOT LIKE`, `IS NULL`, `IS NOT NULL`, `BETWEEN`, `IN`, `VS`.
`filters[].value`	string	No	Filter value. Dates use `YYYY-MM-DD`. For `IN`, a comma-separated list. For `VS`, the from-book. Omit for `IS NULL` and `IS NOT NULL`. The macros `$revpro.CurrPrd` and `$revpro.PriorPrd` are replaced with the current or prior open period name.
`filters[].valueTo`	string	No	Upper bound for `BETWEEN` (date `YYYY-MM-DD`) or the to-book for `VS`. Not used by other operators.

Response definition

HTTP status	Content type	Response schema
`200`	`application/json`	ReportRun
`400`	`application/json`	MissingFiltersError or SimpleError or ServiceError or SpringError
`401`	`application/json`	GatewayError
`403`	`application/json`	GatewayError
`429`	`application/json`	GatewayError
`500`	`application/json`	SimpleError or ServiceError

ReportRun: One execution (submission) of a report layout.

Field	Type	Required	Description
`id`	integer	No	Submission identifier of the run. Use it as `submissionId` to poll status and download.
`reportId`	integer	No	Identifier of the report that was run.
`layoutId`	integer	No	Identifier of the layout that was run.
`status`	string	No	Current run status. See Report run status values. Allowed: `Submitted`, `Upload Started`, `File Created`, `Available`, `Error`, `Terminated`, `Cancelled`.
`fileName`	string	No	Name of the output file. Populated once the file is produced.
`filterParameters`	string	No	JSON text of the filters stored for the run, after defaults and period macros were resolved. Filters are stored with internal filter keys (`key`), operator (`opr`, omitted for `=`) and values (`val1`, `val2`). Treat the content as informational; its format can change.
`config`	string	No	JSON text of output options: `Show Filters` (Y/N, print the filters in the file) and `Enable Totals` (Y/N, add total rows).
`createdBy`	string	No	User that submitted the run.
`runDate`	string (date-time)	No	Date and time the run was submitted, formatted `yyyy-MM-dd'T'HH:mm:ss`.
`updatedBy`	string	No	User or process that last updated the run.
`updatedAt`	string (date-time)	No	Date and time of the last status change, formatted `yyyy-MM-dd'T'HH:mm:ss`.

Error response schemas (GatewayError, ServiceError, SpringError, SimpleError, MissingFiltersError, RunStatusConflict, RiaError, SignedUrlError) are defined once under Error response schemas in the API overview and in components/schemas.

Response codes: 200, 400, 401, 403, 429, 500. Each response with a body includes worked examples; responses without a body say so.

Security

OneIdOAuth

Path

reportIdinteger, (int32)required

Identifier of the report to run.

Example:10021

Accept-Languagestring

Optional language for translated report names, labels and filter options, for example en or ja. Defaults to the user's profile language.

Example:en

Zuora-Track-Idstring

Optional correlation identifier (up to 64 characters) that you choose. The Zuora One gateway records it; quote it to Zuora Support when you report a problem.

Example:close-run-2026-09-001

Bodyapplication/jsonrequired

The layout to run and optional filter overrides.

layoutIdinteger, (int32)required

Identifier of the layout to run. Use a layout returned by List layouts for the same report.

Example:3105

filtersArray of objects or null(ReportFilterParam)

Filter conditions. Omit the property (or send null) to apply all saved layout defaults. Send a partial list to override some filters; layout defaults fill in the rest. Send [] to run with no filters at all (required filters are still enforced).

{
  "layoutId": 3105
}

Responses

Success. The run was accepted. Save id; it is the submissionId for status and download.

Bodyapplication/json

idinteger, (int64)

Submission identifier of the run. Use it as submissionId to poll status and download.

Example:482391

reportIdinteger, (int32)

Identifier of the report that was run.

Example:10021

layoutIdinteger, (int32)

Identifier of the layout that was run.

Example:3105

statusstring

Current run status. See Report run status values.

Enum:"Submitted""Upload Started""File Created""Available""Error""Terminated""Cancelled"

Example:"Available"

fileNamestring or null

Name of the output file. Populated once the file is produced.

Example:"WF_SUMMARY_482391.csv"

filterParametersstring or null

JSON text of the filters stored for the run, after defaults and period macros were resolved. Filters are stored with internal filter keys (key), operator (opr, omitted for =) and values (val1, val2). Treat the content as informational; its format can change.

Example:"{\"filters\":[{\"key\":\"A300\",\"val1\":\"SEP-2026\"},{\"key\":\"A101\",\"val1\":\"R\"}]}"

configstring or null

JSON text of output options: Show Filters (Y/N, print the filters in the file) and Enable Totals (Y/N, add total rows).

Example:"{\"Show Filters\":\"Y\",\"Enable Totals\":\"N\"}"

createdBystring or null

User that submitted the run.

Example:"INTEGRATION.USER"

runDatestring or null, (date-time)

Date and time the run was submitted, formatted yyyy-MM-dd'T'HH:mm:ss.

Example:"2026-10-09T07:15:02"

updatedBystring or null

User or process that last updated the run.

Example:"INTEGRATION.USER"

updatedAtstring or null, (date-time)

Date and time of the last status change, formatted yyyy-MM-dd'T'HH:mm:ss.

Example:"2026-10-09T07:16:40"

Response

{
  "id": 482391,
  "reportId": 10021,
  "layoutId": 3105,
  "status": "Submitted",
  "fileName": null,
  "filterParameters": "{\"filters\":[{\"key\":\"A300\",\"val1\":\"SEP-2026\"},{\"key\":\"A101\",\"val1\":\"R\"}]}",
  "config": "{\"Show Filters\":\"Y\",\"Enable Totals\":\"N\"}",
  "createdBy": "INTEGRATION.USER",
  "runDate": "2026-10-09T07:15:02",
  "updatedBy": "INTEGRATION.USER",
  "updatedAt": "2026-10-09T07:15:02"
}