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 Get event names in a custom date window Pagination: get the next page of values per field Bearer token for a project API key. This endpoint returns data for that project only.
Example: Bearer vem_abcdefghijklmnopqrstuvwxyz123456
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
Validation error details. code
Description
Machine-readable validation error code. message
Description
Human-readable validation summary. details
Description
Per-field validation issues.
Show nested properties (2)
field
Description
Path to the invalid request field. message
Description
Validation error message for the field. 401 Unauthorized - 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
code
Type
"PLAN_LIMIT_EXCEEDED"
429 Rate limit exceeded
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. Type
"INTERNAL_SERVER_ERROR"
message
Description
Human-readable error message.