---
title: "List dimension values"
method: GET
path: "/api/v1/reports/dimension-values"
tags: ["reports"]
---

# List dimension values

`GET /api/v1/reports/dimension-values`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/reports/dimension-values`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

List the values one dimension can take in a report's scope, as the report's Filter offers them: pass the report definition as JSON text (`definition`, as reports_report_tables_get takes it) and a dimension its dataset filters by (`dimension`, as reports_datasets_list names it). Each value names its `key`, which a filter's `values` keeps, and its `label` as the product names it (a customer's name, a store's, a run's start day, an outcome). A dimension a report can group by lists the values the product's figures hold in the definition's campaign and dates, under its other filters, ordered by label; one a dataset only filters by (a store, a customer, a run) or a records field nothing groups by (an outcome) lists every value the product offers there in the product's own order, such as the customers and stores of the campaigns the report reads. The definition's own filter on the dimension narrows nothing. `search` keeps the values whose label contains it, any case, or whose key is it. A definition that does not fit its dataset, or a dimension its dataset does not filter by, is 400 INVALID_INPUT with `details.issues`; a campaign the organization has no such product campaign for is 404 RESOURCE_NOT_FOUND. Page with `limit` and `cursor`.

## Query parameters

- `limit` integer: Number of items to return (1–1000)
- `cursor` string: Opaque cursor returned as nextCursor by the previous page
- `definition` string, required: The report definition as JSON text: `{version: 1, grain: "aggregate", dataset, scope: {campaignId (null: every campaign of the product, pooled, where the dataset allows it), dateRange}, rows, columns, values: [{measure, showAs}], filters: [{dimension, values}], sort, compare, chart: {mark, orientation, x, y, topN, labels} | null}` or `{version: 1, grain: "records", dataset, scope, fields, filters, sort: {field, direction} | null}`, its keys the dataset's (reports.datasets.list.v1).
- `dimension` string, required: A dimension key the definition's dataset filters by.
- `search` string, nullable: Keep the values whose label contains this text, any case, or whose key is it; omit it for every value.

## Headers

- `Point11-Organization` string, uuid

## Response `200`

Success.

- ReportsDimensionValuesListResponse
  - `data` object[], required
    - `key` string, required: What a filter on the dimension keeps (its `values`).
    - `label` string, required: The value as the product names it.
  - `nextCursor` string, nullable, required

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/36a84c7aca11?raw)