Skip to content
Revenue API
/
/
List reports

List reports

Request

Returns the report definitions in your tenant's report catalog, sorted by report name. Each item identifies a report and describes what it contains. This operation does not run a report and returns no report data.

Purpose: Use it as the first call of a reporting integration to find the numeric id of the report you want to run. Filter by name or category to avoid paging through the whole catalog.

When to use: At the start of any reporting integration, when you know a report's name or category but not its numeric ID, or when you want to show users the reports they can run.

Notes:

  • name and category are exact matches that ignore letter case. name matches either the stored report name or its translated display name.
  • Pages are zero-based. The response is a plain JSON array; when it has fewer than size items you have reached the last page.

Request definition

ParameterInTypeRequiredDefaultDescription
idqueryintegerNoReturn only the report with this identifier.
namequerystringNoReturn only the report with this exact name (case-insensitive).
categoryquerystringNoReturn only reports in this category (case-insensitive).
pagequeryintegerNo0Zero-based page number.
sizequeryintegerNo20Number of reports per page. Must be 1 or greater.
Accept-LanguageheaderstringNoOptional language for translated report names, labels and filter options, for example en or ja. Defaults to the user's profile language.
Zuora-Track-IdheaderstringNoOptional 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.
AuthorizationheaderstringYesBearer <access_token> (Zuora OneID OAuth).

Request body: none.

Response definition

HTTP statusContent typeResponse schema
200application/jsonarray of Report
400application/jsonServiceError or SpringError
401application/jsonGatewayError
403application/jsonGatewayError
429application/jsonGatewayError
500application/jsonServiceError

Report: A report definition in the tenant's report catalog. A report describes a data set (for example revenue waterfall or deferred revenue balances). It does not contain row data.

FieldTypeRequiredDescription
idintegerNoUnique numeric identifier of the report definition. Use it as reportId in every other Reports call.
namestringNoDisplay name of the report. List reports returns the translated name when a translation exists for the caller's language; other operations return the stored name.
descriptionstringNoBusiness description of what the report contains.
categorystringNoCatalog grouping the report belongs to, as configured in Zuora Revenue.
sequenceintegerNoDisplay order of the report inside its category. Lower numbers are shown first.
createdBystringNoUser name that created the report definition.
createdAtstring (date-time)NoDate and time the report definition was created, formatted yyyy-MM-dd'T'HH:mm:ss.
updatedBystringNoUser name that last changed the report definition.
updatedAtstring (date-time)NoDate and time the report definition was last changed, 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
Query
idinteger, (int32)

Return only the report with this identifier.

Example:id=10021
namestring

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

Example:name=Revenue Waterfall Report
categorystring

Return only reports in this category (case-insensitive).

Example:category=Revenue
pageinteger, (int32), >= 0

Zero-based page number.

Default:0
Example:page=0
sizeinteger, (int32), >= 1

Number of reports per page. Must be 1 or greater.

Default:20
Example:size=20
Headers
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?id=10021&name=Revenue%20Waterfall%20Report&category=Revenue&page=0&size=20' \
  -H 'Accept-Language: en' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Zuora-Track-Id: close-run-2026-09-001'

Responses

Success. The matching reports (possibly an empty array).

Bodyapplication/json
Array [
idinteger, (int32)

Unique numeric identifier of the report definition. Use it as reportId in every other Reports call.

Example:10021
namestring

Display name of the report. List reports returns the translated name when a translation exists for the caller's language; other operations return the stored name.

Example:"Revenue Waterfall Report"
descriptionstring or null

Business description of what the report contains.

Example:"Recognized and scheduled revenue by period for each revenue contract line"
categorystring or null

Catalog grouping the report belongs to, as configured in Zuora Revenue.

Example:"Revenue"
sequenceinteger or null, (int32)

Display order of the report inside its category. Lower numbers are shown first.

Example:3
createdBystring or null

User name that created the report definition.

Example:"SYSADMIN"
createdAtstring or null, (date-time)

Date and time the report definition was created, formatted yyyy-MM-dd'T'HH:mm:ss.

Example:"2024-01-15T09:30:00"
updatedBystring or null

User name that last changed the report definition.

Example:"FIN.ADMIN"
updatedAtstring or null, (date-time)

Date and time the report definition was last changed, formatted yyyy-MM-dd'T'HH:mm:ss.

Example:"2026-08-02T14:05:11"
]
Response
[
  {
    "id": 10021,
    "name": "Revenue Waterfall Report",
    "description": "Recognized and scheduled revenue by period for each revenue contract line",
    "category": "Revenue",
    "sequence": 3,
    "createdBy": "SYSADMIN",
    "createdAt": "2024-01-15T09:30:00",
    "updatedBy": "FIN.ADMIN",
    "updatedAt": "2026-08-02T14:05:11"
  },
  {
    "id": 10034,
    "name": "Deferred Revenue Roll Forward",
    "description": "Opening balance, additions, recognition and closing deferred revenue by period",
    "category": "Revenue",
    "sequence": 5,
    "createdBy": "SYSADMIN",
    "createdAt": "2024-01-15T09:30:00",
    "updatedBy": "SYSADMIN",
    "updatedAt": "2025-11-20T08:00:00"
  }
]