List layouts of a report

Revenue API

Request

Returns every layout of a report, sorted by layout name. Each layout includes its output columns (fields) and its filters with default values, required flags and allowed values.

Purpose: Choose the layoutId you will run and learn which filters you must or may supply, without a separate call per layout.

When to use: Before your first run of a report, or whenever a layout may have changed, to choose a layoutId and learn which filters are required and which values are allowed.

Notes:

If the report does not exist or has no layouts, the response is 200 with an empty layouts array and totalCount 0.
name is an exact, case-insensitive match on the layout name.

Request definition

Parameter	In	Type	Required	Description
`reportId`	path	integer	Yes	Identifier of the report.
`name`	query	string	No	Return only the layout with this exact name (case-insensitive).
`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: none.

Response definition

HTTP status	Content type	Response schema
`200`	`application/json`	LayoutList
`400`	`application/json`	SpringError
`401`	`application/json`	GatewayError
`403`	`application/json`	GatewayError
`429`	`application/json`	GatewayError
`500`	`application/json`	ServiceError

LayoutList: Wrapper returned by the list-layouts operation.

Field	Type	Required	Description
`layouts`	array of ReportLayout	No	Layouts of the report, sorted by layout name. Each layout includes its fields and filters.
`layouts[].id`	integer	No	Unique identifier of the layout. Send it as `layoutId` when you run the report.
`layouts[].reportId`	integer	No	Identifier of the report the layout belongs to.
`layouts[].name`	string	No	Layout name.
`layouts[].description`	string	No	Layout description.
`layouts[].filenamePrefix`	string	No	Prefix used for the generated output file name.
`layouts[].createdBy`	string	No	User name that created the layout.
`layouts[].createdAt`	string (date-time)	No	Creation date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`.
`layouts[].updatedBy`	string	No	User name that last changed the layout.
`layouts[].updatedAt`	string (date-time)	No	Last change date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`.
`layouts[].fields`	array of LayoutField	No	Output columns of the layout, in output order.
`layouts[].fields[].id`	integer	No	Unique identifier of this column assignment within the layout.
`layouts[].fields[].layoutId`	integer	No	Identifier of the layout the column belongs to.
`layouts[].fields[].fieldId`	integer	No	Identifier of the underlying report field (column definition).
`layouts[].fields[].seq`	integer	No	Position of the column in the output file. Lower numbers appear further left.
`layouts[].fields[].sortSeq`	integer	No	Sort priority of the column. `null` when the layout does not sort by this column.
`layouts[].fields[].fieldName`	string	No	Technical field name in lowerCamelCase. Use this value as `fieldName` when you filter a report run.
`layouts[].fields[].fieldLabel`	string	No	Column heading shown in the output file, translated to the caller's language when a translation exists.
`layouts[].fields[].fieldType`	string	No	Database data type of the column, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`.
`layouts[].filters`	array of LayoutFilter	No	Filters defined on the layout, with required flags and allowed values.
`layouts[].filters[].id`	integer	No	Unique identifier of the filter definition.
`layouts[].filters[].layoutId`	integer	No	Identifier of the layout the filter belongs to.
`layouts[].filters[].fieldId`	integer	No	Identifier of the report field the filter applies to.
`layouts[].filters[].fieldName`	string	No	Technical field name in lowerCamelCase. Send this as `fieldName` in a run request to override the filter.
`layouts[].filters[].fieldLabel`	string	No	Display label of the filter, translated when a translation exists.
`layouts[].filters[].fieldType`	string	No	Database data type of the filtered field, for example `VARCHAR2`, `NUMBER`, `DATE` or `DATE_TIME`.
`layouts[].filters[].type`	string	No	How the filter is presented and evaluated, for example `LOV` (pick from a list), `RANGE` (from/to) or `EQUALS` (single value).
`layouts[].filters[].valueFrom`	string	No	Saved default value, or the lower bound of a range filter.
`layouts[].filters[].valueTo`	string	No	Saved upper bound of a range filter. `null` for single-value filters.
`layouts[].filters[].createdBy`	string	No	User name that created the filter.
`layouts[].filters[].createdAt`	string (date-time)	No	Creation date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`.
`layouts[].filters[].updatedBy`	string	No	User name that last changed the filter.
`layouts[].filters[].updatedAt`	string (date-time)	No	Last change date and time, formatted `yyyy-MM-dd'T'HH:mm:ss`.
`layouts[].filters[].required`	boolean	No	`true` when the layout requires a value for this filter before a run is accepted; `null` when the filter is optional.
`layouts[].filters[].options`	array of FilterOption	No	Allowed values for an `LOV` filter. Always an array; empty for other filter types or when no list is configured.
`layouts[].filters[].options[].label`	string	No	Human-readable text of the option, already translated.
`layouts[].filters[].options[].value`	string	No	Value to send as the filter `value` when you select this option.
`totalCount`	integer	No	Number of layouts in `layouts`.

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.

Example:10021

Query

namestring

Return only the layout with this exact name (case-insensitive).

Example:name=Monthly Close - Summary

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

cURL

curl -i -X GET \
  'https://one.zuora.com/revenue/services/v1/reports/10021/layouts?name=Monthly%20Close%20-%20Summary' \
  -H 'Accept-Language: en' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Zuora-Track-Id: close-run-2026-09-001'

Responses

Success. The layouts of the report.

Bodyapplication/json

layoutsArray of objects(ReportLayout)

Layouts of the report, sorted by layout name. Each layout includes its fields and filters.

totalCountinteger, (int32)

Number of layouts in layouts.

Example:1

Response

{
  "layouts": [
    { … }
  ],
  "totalCount": 1
}