# List custom dimensions

Operation ID: `listCustomDimensions`

Group: Base › Reporting Tags

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/listCustomDimensions)

`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. |

```json
{
  "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