Get filter values Returns available filter values for one or more fields with pagination.
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 or /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 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.
Get referrer and country values for the last 30 days Copy
Copied! {
" dateRange " : "30days" ,
" fields " : [ "referrer" , "country" ]
} Get event names in a custom date window Copy
Copied! {
" dateRange " : [ "2026-01-01" , "2026-01-31" ],
" fields " : [ "event:name" ]
} Fetch UTM filter values Copy
Copied! {
" dateRange " : "7days" ,
" fields " : [ "utmSource" , "utmMedium" , "utmCampaign" ]
} Pagination: get the next page of values per field Copy
Copied! {
" dateRange " : "30days" ,
" fields " : [ "referrerType" , "browser" ],
" limit " : 100 ,
" offset " : 100
} 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<string, string>
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. offset
Description
Number of values to skip per field from the start of the result set. Responses 200 Success
application/json period
from
Description
Resolved UTC start timestamp for the query window. Type
string<pattern:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$>
Example
"2026-01-19T12:30:00Z"
to
Description
Resolved UTC end timestamp for the query window. Type
string<pattern:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$>
Example
"2026-01-19T12:30:00Z"
query
dateRange
Description
Echo of the incoming dateRange request field. Type
"live" | "1hr" | "24hrs" | "7days" | "30days" | "3months" | "6months" | "1year" | array<string, string>
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. offset
Description
Echo of the incoming offset request field. data
Description
One value list per requested field. 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"
pagination
Show nested properties (3)
limit
Description
Applied page size for this field. offset
Description
Applied page offset for this field. returned
Description
Number of values returned for this field. values
Description
Paginated values for this field. Example
["Google","Newsletter","Bing"]
400 Bad request - invalid request payload or parameters
application/json error
Description
Error details. 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. details
Description
Per-field validation issues. Only present for VALIDATION_ERROR.
Show nested properties (2)
field
Description
Path to the invalid request field. message
Description
Validation error message for the field. 401 Unauthorized - missing, malformed, invalid or revoked API key
application/json error
Description
Error details. code
Description
Machine-readable error code. message
Description
Human-readable error message. 403 Requested date range is not allowed for the current plan
application/json error
Description
Error details. code
Description
Machine-readable error code. Type
"PLAN_LIMIT_EXCEEDED"
message
Description
Human-readable error message. 429 Rate limit exceeded - retry after the number of seconds in the Retry-After header
application/json error
Description
Error details. code
Description
Machine-readable error code. Type
"RATE_LIMIT_EXCEEDED"
message
Description
Human-readable error message. 500 Unexpected internal error
application/json error
Description
Error details. code
Description
Machine-readable error code. message
Description
Human-readable error message.