List custom dimensions

Operation ID: listCustomDimensions

Group: Base › Reporting Tags

GET /base/custom-dimensions

Read-only: Reads and returns; changes nothing.

Lists custom dimensions. A custom dimension is a reporting-tag category defined in your tenant, beyond the nine built-in ones such as department, region, and customer.

This endpoint does not follow the standard collection rules in Pagination and querying.

Page with pageSize (default 50, maximum 200) and cursor, not page[size] and page[cursor].
The response has the records in data.items and the next page's cursor in data.pagination.nextCursor.
It takes no filters.
There is no sort or fields.

This endpoint ignores any query parameter it does not declare, and returns no error. A request that follows the standard rules therefore gets the first page, unfiltered, every time.

To list the values inside one dimension, use GET base/custom-dimensions/:customDimensionUuid/values.

Parameters

Name	In	Type	Required	Description
`Api-Version`	header	string · v1	yes	The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`.
`pageSize`	query	number	no	The number of dimensions per page, between 1 and 200. Defaults to 50. A value above 200 is treated as 200, not rejected.
`cursor`	query	string	no	The cursor from the previous response's data.pagination.nextCursor. Omit on the first request.

Response

200 Success

Under data (listCustomDimensionsOutput):

Field	Type	Required	Description
`items`	array<object>	yes	The custom dimensions on this page, ordered by identifier. An empty array when the tenant has defined none.
`items[].customDimensionUuid`	string	yes	The unique identifier for the custom value dimension. It is the customDimensionUuid on a 'custom' row from POST base/reporting-tags/resolve.
`items[].name`	string	yes	The display name of the custom dimension.
`pagination`	object	yes	The pagination cursor for this page.
`pagination.nextCursor`	string	no	The cursor for the next page. Pass it as the cursor query parameter. Absent on the last page.
`pagination.hasMore`	boolean	yes	True when more dimensions remain beyond this page.

{
  "data": {
    "items": [
      {
        "customDimensionUuid": "<customDimensionUuid>",
        "name": "<name>"
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code	Status
`INVALID_CURSOR`	400

Statuses

400 — Invalid request or business failure. Codes: INVALID_CURSOR
401 — The request carries no valid access token.
403 — Not authorized
404 — Not found
429 — Too many requests from this client address. The response has no body and no Retry-After header.
500 — Internal server error