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 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.

{
  "dateRange": "30days",
  "fields": ["referrer", "country"]
}

{
  "dateRange": ["2026-01-01", "2026-01-31"],
  "fields": ["event:name"]
}

{
  "dateRange": "7days",
  "fields": ["utmSource", "utmMedium", "utmCampaign"]
}

{
  "dateRange": "30days",
  "fields": ["referrerType", "browser"],
  "limit": 100,
  "offset": 100
}

Headers

Authorization

required

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.
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<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

Description
Type
object

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.
Type
integer

offset

Description
Echo of the incoming offset request field.
Type
integer


data

Description
One value list per requested field.
Type
array<object>

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<string>
Example
["Google","Newsletter","Bing"]


400 Bad request - invalid request payload or parameters
application/json

error

Description
Validation error details.
Type
object

code

Description
Machine-readable validation error code.
Type
"VALIDATION_ERROR"

message

Description
Human-readable validation summary.
Type
string

details

Description
Per-field validation issues.
Type
array<object>
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 - 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
Type
object

code

Description
Type
"PLAN_LIMIT_EXCEEDED"

message

Description
Type
string


429 Rate limit exceeded
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_SERVER_ERROR"

message

Description
Human-readable error message.
Type
string


Ready to understand your users?

Start tracking
Pricing About Documentation Customers Changelog Blog