# List Custom Dimension Values

`GET /base/custom-dimensions/{customDimensionUuid}/values`

Group: Base › Reporting Tags · Operation ID: `listCustomDimensionValues`

Returns the tag values defined within one custom value dimension, identified by its identifier in the path. Each row carries the modelUuid that POST base/reporting-tags/resolve accepts. Use GET base/custom-dimensions first to learn which dimension identifiers exist. Inactive values are excluded unless includeInactive is true.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=listCustomDimensionValues)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"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`. |
| `customDimensionUuid` | path | string | yes | The unique identifier for the custom value dimension whose values to return. Take it from the customDimensionUuid of a GET base/custom-dimensions row. |
| `includeInactive` | query | boolean | no | Whether to include values that are no longer active. Defaults to false. |
| `pageSize` | query | number | no | The number of values 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 pagination.nextCursor. Omit on the first request. |

## Response

`200` Success

Under `data` (listCustomDimensionValuesOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The values on this page. An empty array when the dimension holds none. A dimension identifier that matches nothing fails with NOT_FOUND instead. |
| `items[].dimensionCode` | string | yes | The dimension this value belongs to. Always 'custom' on this endpoint. |
| `items[].modelId` | number | yes | The numeric id of the value record, stored internally on a journal entry's allocation line. |
| `items[].modelUuid` | string | yes | The unique identifier for the value record. Pass it as modelUuid to POST base/reporting-tags/resolve, paired with dimensionCode 'custom'. |
| `items[].name` | string | yes | The display name of the value. |
| `items[].isActive` | boolean | yes | Whether the value is currently active and can be assigned to new transactions. |
| `items[].customDimensionUuid` | string | no | The unique identifier for the custom dimension this value belongs to. It is the same identifier given in the path. |
| `items[].dimensionName` | string | no | The display name of the parent 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 values remain beyond this page. |

## Errors

| Code | Status |
| --- | --- |
| `NOT_FOUND` | 400 |
| `INVALID_CURSOR` | 400 |

## Statuses

- `400` — Invalid request or business failure. Codes: NOT_FOUND, INVALID_CURSOR
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error