--- title: "POST /v1/filters/values | Documentation - Vemetric" description: "Get filter values" url: https://vemetric.com/docs/api/endpoints/post-v1-filters-values --- # Get filter values Returns available filter values for one or more fields with pagination. * * * Method POST Path /v1/filters/values This endpoint returns available values for one or more filter fields, scoped to a date range. It helps you to see which values you use in the `filters` field of other endpoints like [/v1/analytics/query](https://vemetric.com/docs/api/endpoints/post-v1-analytics-query) or [/v1/users/events](https://vemetric.com/docs/api/endpoints/post-v1-users-events). ## Examples Below you can see several examples of how to use this endpoint to retrieve filterable values. Further down this page, you can find a [detailed reference](#request-body) of all the available options you can pass. Copy the JSON body of any of these examples, and use it in a `POST` request to `https://api.vemetric.com/v1/filters/values` with your API key. ```json { "dateRange": "30days", "fields": ["referrer", "country"] } ``` ```json { "dateRange": ["2026-01-01", "2026-01-31"], "fields": ["event:name"] } ``` ```json { "dateRange": "7days", "fields": ["utmSource", "utmMedium", "utmCampaign"] } ``` ```json { "dateRange": "30days", "fields": ["referrerType", "browser"], "limit": 100, "offset": 100 } ``` ## Headers Authorization required Project API key (starts with `vem_`), created in the project settings on the API tab. Requests only return data of that key's project. Example: `Bearer vem_xxxxxxxxxxxx` ## Request Body (required) application/json object `dateRange` \* required Description Can be either one of the preset strings below, or an array with two date strings \[start, end\]. Date strings can be either in YYYY-MM-DD format or UTC ISO-8601 format with second precision. Type "live" | "1hr" | "24hrs" | "7days" | "30days" | "3months" | "6months" | "1year" | array Example \["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"\] * * * `fields` \* required Description Field tokens to retrieve values for. Type array<"country" | "city" | "page:origin" | "page:path" | "browser" | "deviceType" | "os" | "referrer" | "referrerType" | "utmCampaign" | "utmContent" | "utmMedium" | "utmSource" | "utmTerm" | "event:name"> Example \["referrer","country","event:name"\] * * * `limit` Description Limits the number of returned values per field. Type integer Default 100 * * * `offset` Description Number of values to skip per field from the start of the result set. Type integer Default 0 * * * ## Responses 200 Success application/json `period` Description Type object `from` Description Resolved UTC start timestamp for the query window. Type string Example "2026-01-19T12:30:00Z" * * * `to` Description Resolved UTC end timestamp for the query window. Type string Example "2026-01-19T12:30:00Z" * * * * * * `query` Description Type object `dateRange` Description Echo of the incoming `dateRange` request field. Type "live" | "1hr" | "24hrs" | "7days" | "30days" | "3months" | "6months" | "1year" | array Example \["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"\] * * * `fields` Description Echo of the incoming `fields` request field. Type array<"country" | "city" | "page:origin" | "page:path" | "browser" | "deviceType" | "os" | "referrer" | "referrerType" | "utmCampaign" | "utmContent" | "utmMedium" | "utmSource" | "utmTerm" | "event:name"> * * * `limit` Description Echo of the incoming `limit` request field. Type integer * * * `offset` Description Echo of the incoming `offset` request field. Type integer * * * * * * `data` Description One value list per requested field. Type array `field` Description Field token this value list belongs to. Type "country" | "city" | "page:origin" | "page:path" | "browser" | "deviceType" | "os" | "referrer" | "referrerType" | "utmCampaign" | "utmContent" | "utmMedium" | "utmSource" | "utmTerm" | "event:name" Example "referrer" * * * `pagination` Description Type object Show nested properties (3) `limit` Description Applied page size for this field. Type integer * * * `offset` Description Applied page offset for this field. Type integer * * * `returned` Description Number of values returned for this field. Type integer * * * * * * `values` Description Paginated values for this field. Type array Example \["Google","Newsletter","Bing"\] * * * * * * 400 Bad request - invalid request payload or parameters application/json `error` Description Error details. Type object `code` Description Machine-readable error code. `HTTP_ERROR` is returned for a malformed JSON body. Type "VALIDATION\_ERROR" | "HTTP\_ERROR" * * * `message` Description Human-readable error message. Type string * * * `details` Description Per-field validation issues. Only present for `VALIDATION_ERROR`. Type array Show nested properties (2) `field` Description Path to the invalid request field. Type string Example "groupBy.0" * * * `message` Description Validation error message for the field. Type string * * * * * * * * * 401 Unauthorized - missing, malformed, invalid or revoked API key application/json `error` Description Error details. Type object `code` Description Machine-readable error code. Type "UNAUTHORIZED" * * * `message` Description Human-readable error message. Type string * * * * * * 403 Requested date range is not allowed for the current plan application/json `error` Description Error details. Type object `code` Description Machine-readable error code. Type "PLAN\_LIMIT\_EXCEEDED" * * * `message` Description Human-readable error message. Type string * * * * * * 429 Rate limit exceeded - retry after the number of seconds in the Retry-After header application/json `error` Description Error details. Type object `code` Description Machine-readable error code. Type "RATE\_LIMIT\_EXCEEDED" * * * `message` Description Human-readable error message. Type string * * * * * * 500 Unexpected internal error application/json `error` Description Error details. Type object `code` Description Machine-readable error code. Type "INTERNAL\_ERROR" * * * `message` Description Human-readable error message. Type string * * * * * *