Authorization
requiredBearer token for a project API key. This endpoint returns data for that project only.
Example: Bearer vem_abcdefghijklmnopqrstuvwxyz123456
Query analytics
Query analytics metrics with optional grouping, sorting and filters.
Method
POST
Path
/v1/analytics/query
Headers
Request Body (required)
application/json object
date_range
Description
Date range for the query. 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"]
metrics
Description
Metrics to calculate and include in the response. Type
array<"users" | "pageviews" | "events" | "bounce_rate" | "visit_duration">
Default
["users","pageviews","events"]
group_by
Description
Allowed values: "interval:auto", "country", "city", "browser", "device_type", "os", "referrer", "referrer_type", "utm_*", "event:name", or "event:prop:<property_name>". At the moment it's only possible to group by one field, please tell us if you need more. Type
array<"country" | "city" | "browser" | "device_type" | "os" | "referrer" | "referrer_type" | "utm_campaign" | "utm_content" | "utm_medium" | "utm_source" | "utm_term" | "event:name" | "interval:auto" | string<pattern:^event:prop:([^\r\n]+)$>>
Default
[]
Example
["country"]
order_by
Description
Gives you the ability to order multiple fields by different directions Type
array<array<"users" | "pageviews" | "events" | "bounce_rate" | "visit_duration" | "country" | "city" | "browser" | "device_type" | "os" | "referrer" | "referrer_type" | "utm_campaign" | "utm_content" | "utm_medium" | "utm_source" | "utm_term" | "event:name" | "date" | string<pattern:^event:prop:([^\r\n]+)$>, "asc" | "desc">>
Default
[]
Example
[["users","desc"]]
limit
Description
Limits the number of returned rows. Max value is 1000. Type
integer
Default
100
offset
Description
Number of rows to skip from the start of the result set, to implement pagination. Type
integer
Default
0
filters
Description
Ability to filter the results based on multiple criteria. Type
array<object>
Show nested properties (11)
type: page
Description
Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts. Type
object
Default
"page"
Example
{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}
Show nested properties (3)
origin
Description
Filter based on the page origin (protocol + host). For example, "https://example.com". Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
path
Description
Filter based on the page path. For example, "/blog". Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
hash
Description
Filter based on the page hash. For example, "#section1". Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: event
Description
Filter by event name and/or event property values. Type
object
Default
"event"
Example
{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}
Show nested properties (2)
name
Description
Filter by event name. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
properties
Description
Filter by one or more custom event properties. Type
array<object>
Show nested properties (3)
property
Description
Event property key inside custom event data. Type
string
Example
"plan"
value
Description
Event property value to compare against. Type
string
Example
"pro"
operator
Description
String matching operator for `value`. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"eq"
type: user
Description
Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior). Type
object
Default
"user"
Example
{"type":"user","anonymous":true}
Show nested properties (1)
anonymous
Description
Filter for anonymous (`true`) or identified (`false`) users. Type
boolean
Example
true
type: location
Description
Filter by geographic location fields. Type
object
Default
"location"
Example
{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}
Show nested properties (2)
country
Description
Filter by one or more country codes (ISO-3166 alpha-2, e.g. "US"). Type
object
Show nested properties (2)
value
Description
List of values to filter by Type
array<string>
operator
Description
Operator to apply for the list filter. The "any" operator means that any value is accepted and effectively disables the filter. Type
"any" | "oneOf" | "noneOf"
city
Description
Filter by one or more city names. Type
object
Example
{"value":["Berlin","New York"],"operator":"oneOf"}
Show nested properties (2)
value
Description
List of values to filter by Type
array<string>
operator
Description
Operator to apply for the list filter. The "any" operator means that any value is accepted and effectively disables the filter. Type
"any" | "oneOf" | "noneOf"
type: referrer
Description
Filter by referrer name. Type
object
Default
"referrer"
Example
{"type":"referrer","operator":"eq","value":"Google"}
Show nested properties (2)
value
Description
Referrer value to match. Empty string represents direct/none referrer. Type
string
Example
"Google"
operator
Description
String matching operator for `value`. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"eq"
type: referrer_url
Description
Filter by referrer URL. Type
object
Default
"referrer_url"
Example
{"type":"referrer_url","operator":"contains","value":"google.com"}
Show nested properties (2)
value
Description
Referrer URL value to match. Type
string
Example
"https://google.com"
operator
Description
String matching operator for `value`. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"contains"
type: referrer_type
Description
Filter by referrer category/type. Type
object
Default
"referrer_type"
Example
{"type":"referrer_type","operator":"oneOf","value":["search"]}
Show nested properties (2)
value
Description
List of referrer types to match (for example: `search`, `social`, `email`, `direct`). Type
array<string>
Example
["search","social"]
operator
Description
List matching operator for `value`. Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"
type: utm_tags
Description
Filter by one or more UTM parameters. Type
object
Default
"utm_tags"
Example
{"type":"utm_tags","utm_source":{"operator":"eq","value":"google"},"utm_medium":{"operator":"eq","value":"cpc"}}
Show nested properties (5)
utm_campaign
Description
Filter by UTM campaign. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utm_content
Description
Filter by UTM content. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utm_medium
Description
Filter by UTM medium. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utm_source
Description
Filter by UTM source. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utm_term
Description
Filter by UTM term. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: browser
Description
Filter by browser. Type
object
Default
"browser"
Example
{"type":"browser","operator":"oneOf","value":["Chrome"]}
Show nested properties (2)
value
Description
List of browser names to match. Type
array<string>
Example
["Chrome","Safari"]
operator
Description
List matching operator for `value`. Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"
type: device
Description
Filter by device type. Type
object
Default
"device"
Example
{"type":"device","operator":"oneOf","value":["desktop"]}
Show nested properties (2)
value
Description
List of device types to match. Type
array<string>
Example
["desktop","mobile"]
operator
Description
List matching operator for `value`. Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"
type: os
Description
Filter by operating system. Type
object
Default
"os"
Example
{"type":"os","operator":"oneOf","value":["macOS"]}
Show nested properties (2)
value
Description
List of operating system names to match. Type
array<string>
Example
["macOS","Windows"]
operator
Description
List matching operator for `value`. Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"
filtersOperator
Description
Operator to apply between multiple filters. Can be either "and" or "or". Type
"and" | "or"
Default
"and"
Responses
200 Success application/json
period
Description
Resolved query period. 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
Resolved query configuration used for this response. Type
object
date_range
Description
Echo of the incoming `date_range` 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"]
group_by
Description
Echo of the incoming `group_by` request field. Type
array<"country" | "city" | "browser" | "device_type" | "os" | "referrer" | "referrer_type" | "utm_campaign" | "utm_content" | "utm_medium" | "utm_source" | "utm_term" | "event:name" | "interval:auto" | string<pattern:^event:prop:([^\r\n]+)$>>
metrics
Description
Resolved list of metrics used in the query. Type
array<"users" | "pageviews" | "events" | "bounce_rate" | "visit_duration">
order_by
Description
Echo of the incoming `order_by` request field. Type
array<array<"users" | "pageviews" | "events" | "bounce_rate" | "visit_duration" | "country" | "city" | "browser" | "device_type" | "os" | "referrer" | "referrer_type" | "utm_campaign" | "utm_content" | "utm_medium" | "utm_source" | "utm_term" | "event:name" | "date" | string<pattern:^event:prop:([^\r\n]+)$>, "asc" | "desc">>
limit
Description
Echo of the incoming `limit` request field. Type
integer
offset
Description
Echo of the incoming `offset` request field. Type
integer
filters
Description
Echo of the incoming `filters` request field. Type
array<object>
Show nested properties (11)
type: page
Description
Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts. Type
object
Default
"page"
Example
{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}
Show nested properties (3)
origin
Description
Filter based on the page origin (protocol + host). For example, "https://example.com". Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
path
Description
Filter based on the page path. For example, "/blog". Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
hash
Description
Filter based on the page hash. For example, "#section1". Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: event
Description
Filter by event name and/or event property values. Type
object
Default
"event"
Example
{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}
Show nested properties (2)
name
Description
Filter by event name. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
properties
Description
Filter by one or more custom event properties. Type
array<object>
Show nested properties (3)
property
Description
Event property key inside custom event data. Type
string
Example
"plan"
value
Description
Event property value to compare against. Type
string
Example
"pro"
operator
Description
String matching operator for `value`. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"eq"
type: user
Description
Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior). Type
object
Default
"user"
Example
{"type":"user","anonymous":true}
Show nested properties (1)
anonymous
Description
Filter for anonymous (`true`) or identified (`false`) users. Type
boolean
Example
true
type: location
Description
Filter by geographic location fields. Type
object
Default
"location"
Example
{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}
Show nested properties (2)
country
Description
Filter by one or more country codes (ISO-3166 alpha-2, e.g. "US"). Type
object
Show nested properties (2)
value
Description
List of values to filter by Type
array<string>
operator
Description
Operator to apply for the list filter. The "any" operator means that any value is accepted and effectively disables the filter. Type
"any" | "oneOf" | "noneOf"
city
Description
Filter by one or more city names. Type
object
Example
{"value":["Berlin","New York"],"operator":"oneOf"}
Show nested properties (2)
value
Description
List of values to filter by Type
array<string>
operator
Description
Operator to apply for the list filter. The "any" operator means that any value is accepted and effectively disables the filter. Type
"any" | "oneOf" | "noneOf"
type: referrer
Description
Filter by referrer name. Type
object
Default
"referrer"
Example
{"type":"referrer","operator":"eq","value":"Google"}
Show nested properties (2)
value
Description
Referrer value to match. Empty string represents direct/none referrer. Type
string
Example
"Google"
operator
Description
String matching operator for `value`. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"eq"
type: referrer_url
Description
Filter by referrer URL. Type
object
Default
"referrer_url"
Example
{"type":"referrer_url","operator":"contains","value":"google.com"}
Show nested properties (2)
value
Description
Referrer URL value to match. Type
string
Example
"https://google.com"
operator
Description
String matching operator for `value`. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"contains"
type: referrer_type
Description
Filter by referrer category/type. Type
object
Default
"referrer_type"
Example
{"type":"referrer_type","operator":"oneOf","value":["search"]}
Show nested properties (2)
value
Description
List of referrer types to match (for example: `search`, `social`, `email`, `direct`). Type
array<string>
Example
["search","social"]
operator
Description
List matching operator for `value`. Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"
type: utm_tags
Description
Filter by one or more UTM parameters. Type
object
Default
"utm_tags"
Example
{"type":"utm_tags","utm_source":{"operator":"eq","value":"google"},"utm_medium":{"operator":"eq","value":"cpc"}}
Show nested properties (5)
utm_campaign
Description
Filter by UTM campaign. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utm_content
Description
Filter by UTM content. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utm_medium
Description
Filter by UTM medium. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utm_source
Description
Filter by UTM source. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utm_term
Description
Filter by UTM term. Type
object
Show nested properties (2)
value
Description
Value to filter by Type
string
operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: browser
Description
Filter by browser. Type
object
Default
"browser"
Example
{"type":"browser","operator":"oneOf","value":["Chrome"]}
Show nested properties (2)
value
Description
List of browser names to match. Type
array<string>
Example
["Chrome","Safari"]
operator
Description
List matching operator for `value`. Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"
type: device
Description
Filter by device type. Type
object
Default
"device"
Example
{"type":"device","operator":"oneOf","value":["desktop"]}
Show nested properties (2)
value
Description
List of device types to match. Type
array<string>
Example
["desktop","mobile"]
operator
Description
List matching operator for `value`. Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"
type: os
Description
Filter by operating system. Type
object
Default
"os"
Example
{"type":"os","operator":"oneOf","value":["macOS"]}
Show nested properties (2)
value
Description
List of operating system names to match. Type
array<string>
Example
["macOS","Windows"]
operator
Description
List matching operator for `value`. Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"
filtersOperator
Description
Echo of the incoming `filtersOperator` request field. Type
"and" | "or"
pagination
Description
Pagination metadata for the response. Type
object
limit
Description
Applied row limit after internal normalization. Type
integer
offset
Description
Applied row offset after internal normalization. Type
integer
returned
Description
Number of rows returned in `data`. Can be used to determine if there are more rows available for pagination (when `returned` is equal to `limit`, there might be more rows available on the next page). Type
integer
data
Description
Result rows for the query after grouping, sorting, and pagination. Type
array<object>
group
Description
Group values for this row. Empty object for aggregate queries. Type
object
Example
{"date":"2026-01-18T00:00:00Z"}
metrics
Description
Calculated metric values for the row. Only requested metrics are returned. Type
object
Show nested properties (5)
users
Description
Unique users count for this row. Type
number
Example
412
pageviews
Description
Pageview events count for this row. Type
number
Example
1736
events
Description
Custom events count for this row. Type
number
Example
43
bounce_rate
Description
Bounce rate percentage for this row. Can be `null` when not applicable for the selected grouping. Type
number | null
Example
34.12
visit_duration
Description
Average visit duration in seconds for this row. Can be `null` when not applicable for the selected grouping. Type
number | null
Example
1222.45
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
"group_by.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