Skip to navigation
Optimize

List Dimension Values

Lists the values seen for one dimension over a date range within one interval, with how often each appeared. Use a value in filter to narrow a report.

Values are sorted by eventCount, highest first. To get the next page, pass nextCursor as cursor. Counts can change between requests, so a value can move to a different page while you page through the list.

Optimize required
This endpoint requires a Webflow site with the Optimize add-on, or a non-Webflow site that uses Optimize.
Concurrency limit: 1 request at a time
Each access token can have one Optimize request in flight at a time, across all Optimize endpoints. Additional concurrent requests return 429 Too Many Requests. Wait for your in-flight request to finish, or for the Retry-After interval, then retry.

Required scope | sites:read

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

optimize_idstringRequired>=1 character

The Optimize ID, from List Optimize IDs.

optimization_idstringRequired1-128 characters

The optimization ID, from List Optimizations.

dimension_idstringRequired1-128 characters

The dimension id, from List Dimensions. URL-encode it, because dimension IDs can contain :, ., and spaces. Unlike groupBy, this accepts urlParameter.

Query parameters

intervalStartstringRequiredformat: "date-time"

Start of the date range. Must be a UTC timestamp ending in Z, such as 2026-09-01T00:00:00Z. Offsets and date-only values aren’t accepted. Seconds and milliseconds are optional. The date range must fall within a single interval of the optimization. A range that crosses from one interval into the next is rejected. Use an interval’s start and end from List Optimizations. Can’t be earlier than 18 months ago.

intervalEndstringRequiredformat: "date-time"

End of the date range. Must be a UTC timestamp ending in Z, such as 2026-09-15T00:00:00Z, and later than intervalStart. Offsets and date-only values aren’t accepted. Seconds and milliseconds are optional.

filtermap from strings to objectsOptional

Narrow the results to visitors who match dimension values. Use bracket notation with in or nin and indexed arrays, for example filter[country][in][0]=US&filter[country][in][1]=GB&filter[customAttribute:towel][nin][0]=forgotten.

Keys are dimension id values from List Dimensions, and values are raw value values from List Dimension Values. Separate dimensions combine with AND. Values within one dimension combine with OR. A filter can name at most 20 dimensions, with at most 50 values per operator and 500 values in total.

pageSizeintegerOptional1-200Defaults to 100

The maximum number of results to return. Defaults to 100, up to 200.

cursorstringOptional>=1 character

The nextCursor from a previous response, to get the next page. Send the same dimension, intervalStart, intervalEnd, and filter as the original request. Note that pageSize can differ between requests.

Response

A page of values seen for the dimension.
intervalStartstringformat: "date-time"
Start of the reported date range, in full form with milliseconds.
intervalEndstringformat: "date-time"
End of the reported date range, in full form with milliseconds.
dimensionobject
The dimension the values belong to.
valueslist of objects

The values on this page, sorted by eventCount, highest first. Empty if the dimension had no values in the date range.

filtermap from strings to objectsOptional

The request’s filter, keyed by dimension id, with each dimension’s display name. Present only when the request included a filter.

nextCursorstringOptional

Pass this value as cursor to get the next page. Omitted on the last page.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error