Retrieve report metadata by ID or name

Revenue API

Retrieve report metadata by ID or name

Request

Returns a report's identity, whether it is a standard or custom report, every field it can output, and its layouts with the default layout flagged.

Purpose: Resolve a report from a name you already know (for example from configuration) and find its default layout in a single call.

When to use: When your configuration stores report names rather than IDs, or when you need the default layout of a report in a single call.

Notes:

reportIdentifier is treated as a report ID when it is numeric; otherwise it is matched to the report name exactly, ignoring case and surrounding spaces. A report whose name is only digits can therefore be found only by its ID.
metadata.parameters and metadata.filters are reserved and currently empty. Use the layout operations to read filters.

Request definition

Parameter	In	Type	Required	Description
`reportIdentifier`	path	string	Yes	Report ID (numeric) or exact report name. URL-encode spaces as `%20`.
`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`	ReportMetadata
`400`	`application/json`	SpringError
`401`	`application/json`	GatewayError
`403`	`application/json`	GatewayError
`404`	none	No body
`429`	`application/json`	GatewayError
`500`	`application/json`	ServiceError

ReportMetadata: Report metadata: identity, type, available columns and layouts.

Field	Type	Required	Description
`reportId`	integer	No	Identifier of the report.
`reportName`	string	No	Name of the report.
`reportType`	string	No	`STANDARD` for a report delivered by Zuora; `CUSTOM` for a report your organization created. Allowed: `STANDARD`, `CUSTOM`.
`metadata`	ReportMetadataInfo	No	Description, columns and reserved arrays.
`metadata.description`	string	No	Business description of the report.
`metadata.parameters`	array of object	No	Reserved for future use. Currently always an empty array.
`metadata.filters`	array of object	No	Reserved for future use. Currently always an empty array. Read filters from the layout operations instead.
`metadata.columns`	array of ReportMetadataColumn	No	All fields the report can output.
`metadata.columns[].id`	integer	No	Identifier of the report field.
`metadata.columns[].fieldName`	string	No	Technical field name as stored in the report definition (UPPER_SNAKE_CASE).
`metadata.columns[].alias`	string	No	Column alias used in the report output.
`metadata.columns[].fieldType`	string	No	Data type of the field.
`metadata.columns[].label`	string	No	Display label of the field.
`layouts`	array of ReportMetadataLayout	No	Layouts available for the report.
`layouts[].layoutId`	integer	No	Identifier of the layout.
`layouts[].layoutName`	string	No	Name of the layout.
`layouts[].isDefault`	boolean	No	`true` when this is the report's default layout.

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, 404, 429, 500. Each response with a body includes worked examples; responses without a body say so.

Security

OneIdOAuth

Path

reportIdentifierstringrequired

Report ID (numeric) or exact report name. URL-encode spaces as %20.

Example:Revenue Waterfall Report

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/Revenue Waterfall Report/metadata' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Zuora-Track-Id: close-run-2026-09-001'

Responses

Success. The report metadata.

Bodyapplication/json

reportIdinteger, (int32)

Identifier of the report.

Example:10021

reportNamestring

Name of the report.

Example:"Revenue Waterfall Report"

reportTypestring

STANDARD for a report delivered by Zuora; CUSTOM for a report your organization created.

Enum:"STANDARD""CUSTOM"

Example:"STANDARD"

metadataobject(ReportMetadataInfo)

Description, columns and reserved arrays.

layoutsArray of objects(ReportMetadataLayout)

Layouts available for the report.

Response

{
  "reportId": 10021,
  "reportName": "Revenue Waterfall Report",
  "reportType": "STANDARD",
  "metadata": {
    "description": "Recognized and scheduled revenue by period for each revenue contract line",
    "parameters": [],
    "filters": [],
    "columns": [ … ]
  },
  "layouts": [
    { … },
    { … }
  ]
}