Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vemetric/vemetric/llms.txt

Use this file to discover all available pages before exploring further.

​
Endpoint

POST https://api.vemetric.com/v1/analytics/query
Query analytics metrics with optional grouping, sorting, and filters. This endpoint provides flexible access to all your analytics data.

​
Authentication

Requires a valid API key in the Authorization header. See Authentication for details.

​
Request Body

​
date_range
string | [string, string]
required
Date range for the query. Can be either:
  • A preset string: "today", "yesterday", "7days", "30days", "90days", "12months", "mtd" (month to date), "ytd" (year to date), "all"
  • An array with two date strings [start, end] in either:
    • YYYY-MM-DD format (e.g., "2026-01-01")
    • UTC ISO-8601 format with second precision (e.g., "2026-01-01T12:00:00Z")
​
metrics
array<string>
default:"[\"users\", \"pageviews\", \"events\"]"
Metrics to calculate. If omitted, defaults to ["users", "pageviews", "events"].Available metrics:
  • "users" - Unique users count
  • "pageviews" - Pageview events count
  • "events" - Custom events count
  • "bounce_rate" - Bounce rate percentage (can be null for some groupings)
  • "visit_duration" - Average visit duration in seconds (can be null for some groupings)
​
group_by
array<string>
default:"[]"
Group results by a dimension. Currently supports grouping by one field only.Available grouping fields:
  • "interval:auto" - Group by time interval (automatically determined based on date range)
  • "country" - Group by country
  • "city" - Group by city
  • "page:origin" - Group by page origin (protocol + host)
  • "page:path" - Group by page path
  • "browser" - Group by browser name
  • "device_type" - Group by device type (desktop, mobile, tablet)
  • "os" - Group by operating system
  • "referrer" - Group by referrer name
  • "referrer_type" - Group by referrer type (search, social, email, etc.)
  • "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term" - Group by UTM parameters
  • "event:name" - Group by event name
  • "event:prop:<property_name>" - Group by custom event property (e.g., "event:prop:plan")
​
order_by
array<[string, 'asc' | 'desc']>
default:"[]"
Sort results by a field and direction. Currently supports one sort field.You can sort by:
  • Any metric in the metrics array
  • The grouping field (if group_by is specified)
  • "date" (when grouping by interval:auto)
​
limit
number
default:"100"
Maximum number of rows to return. Must be between 1 and 1000.
​
offset
number
default:"0"
Number of rows to skip from the start (for pagination).
​
filters
array<Filter>
Array of filters to apply to the query. Multiple filters can be combined using the filtersOperator.See the Filters section below for detailed filter types.
​
filtersOperator
'and' | 'or'
default:"'and'"
Operator to apply between multiple filters.
  • "and" - All filters must match
  • "or" - At least one filter must match

​
Response

​
period
object
Resolved query period.
​
query
object
Echo of the resolved query configuration.
​
pagination
object
Pagination metadata.
​
data
array<object>
Result rows for the query after grouping, sorting, and pagination.

​
Filters

Filters allow you to narrow down your analytics data based on various criteria. Multiple filters can be combined using the filtersOperator field.

​
String Operators

Used by most filter types that accept string values:
  • "any" - Matches any value (exists)
  • "eq" - Equals
  • "notEq" - Not equals
  • "contains" - Contains substring
  • "notContains" - Does not contain substring
  • "startsWith" - Starts with
  • "endsWith" - Ends with

​
List Operators

Used by filter types that accept arrays:
  • "oneOf" - Value is in the list
  • "noneOf" - Value is not in the list

​
Page Filter

Filter based on page view properties: 
{
  "type": "page",
  "origin": {
    "value": "https://example.com",
    "operator": "eq"
  },
  "path": {
    "value": "/blog",
    "operator": "startsWith"
  },
  "hash": {
    "value": "#section1",
    "operator": "eq"
  }
}
​
type
'page'
required
​
origin
{ value: string, operator: string }
Filter by page origin (protocol + host). Example: "https://example.com"
​
path
{ value: string, operator: string }
Filter by page path. Example: "/blog"
​
hash
{ value: string, operator: string }
Filter by page hash. Example: "#section1"

​
Event Filter

Filter by event name and/or event properties: 
{
  "type": "event",
  "name": {
    "operator": "eq",
    "value": "signup"
  },
  "properties": [
    {
      "property": "plan",
      "operator": "eq",
      "value": "pro"
    }
  ]
}
​
type
'event'
required
​
name
{ value: string, operator: string }
Filter by event name.
​
properties
array<{ property: string, value: string, operator: string }>
Filter by custom event properties.

​
User Filter

Filter for anonymous or identified users: 
{
  "type": "user",
  "anonymous": true
}
​
type
'user'
required
​
anonymous
boolean
required
true for anonymous users, false for identified users.

​
Location Filter

Filter by geographic location: 
{
  "type": "location",
  "country": {
    "operator": "oneOf",
    "value": ["US", "DE"]
  },
  "city": {
    "operator": "oneOf",
    "value": ["Berlin"]
  }
}
​
type
'location'
required
​
country
{ value: array<string>, operator: 'oneOf' | 'noneOf' }
Filter by country codes (ISO-3166 alpha-2, e.g., "US").
​
city
{ value: array<string>, operator: 'oneOf' | 'noneOf' }
Filter by city names.

​
Referrer Filter

Filter by referrer name: 
{
  "type": "referrer",
  "operator": "eq",
  "value": "Google"
}
​
type
'referrer'
required
​
value
string
required
Referrer value to match. Empty string represents direct/none referrer.
​
operator
string
required
String matching operator.

​
Referrer URL Filter

Filter by referrer URL: 
{
  "type": "referrer_url",
  "operator": "contains",
  "value": "google.com"
}
​
type
'referrer_url'
required
​
value
string
required
​
operator
string
required

​
Referrer Type Filter

Filter by referrer category: 
{
  "type": "referrer_type",
  "operator": "oneOf",
  "value": ["search", "social"]
}
​
type
'referrer_type'
required
​
value
array<string>
required
Referrer types: "search", "social", "email", "direct", etc.
​
operator
'oneOf' | 'noneOf'
required

​
UTM Tags Filter

Filter by UTM parameters: 
{
  "type": "utm_tags",
  "utm_source": {
    "operator": "eq",
    "value": "google"
  },
  "utm_medium": {
    "operator": "eq",
    "value": "cpc"
  }
}
​
type
'utm_tags'
required
​
utm_campaign
{ value: string, operator: string }
​
utm_content
{ value: string, operator: string }
​
utm_medium
{ value: string, operator: string }
​
utm_source
{ value: string, operator: string }
​
utm_term
{ value: string, operator: string }

​
Browser Filter

Filter by browser: 
{
  "type": "browser",
  "operator": "oneOf",
  "value": ["Chrome", "Safari"]
}
​
type
'browser'
required
​
value
array<string>
required
​
operator
'oneOf' | 'noneOf'
required

​
Device Filter

Filter by device type: 
{
  "type": "device",
  "operator": "oneOf",
  "value": ["desktop", "mobile"]
}
​
type
'device'
required
​
value
array<string>
required
Device types: "desktop", "mobile", "tablet"
​
operator
'oneOf' | 'noneOf'
required

​
OS Filter

Filter by operating system: 
{
  "type": "os",
  "operator": "oneOf",
  "value": ["macOS", "Windows"]
}
​
type
'os'
required
​
value
array<string>
required
​
operator
'oneOf' | 'noneOf'
required

​
Examples

​
Aggregate Query

Get total metrics for the last 30 days: 
curl -X POST 'https://api.vemetric.com/v1/analytics/query' \
  -H 'Authorization: Bearer vem_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": "30days"
  }'

​
Group by Country

Get top countries by user count:
cURL
curl -X POST 'https://api.vemetric.com/v1/analytics/query' \
  -H 'Authorization: Bearer vem_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": "30days",
    "group_by": ["country"],
    "order_by": [["users", "desc"]],
    "limit": 10
  }'

​
Time Series Data

Get daily metrics:
cURL
curl -X POST 'https://api.vemetric.com/v1/analytics/query' \
  -H 'Authorization: Bearer vem_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": "7days",
    "group_by": ["interval:auto"],
    "metrics": ["users", "pageviews"],
    "order_by": [["date", "asc"]]
  }'

​
With Filters

Get metrics for mobile users from the US:
cURL
curl -X POST 'https://api.vemetric.com/v1/analytics/query' \
  -H 'Authorization: Bearer vem_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": "30days",
    "filters": [
      {
        "type": "location",
        "country": {
          "operator": "oneOf",
          "value": ["US"]
        }
      },
      {
        "type": "device",
        "operator": "oneOf",
        "value": ["mobile"]
      }
    ],
    "filtersOperator": "and"
  }'

​
Custom Event Properties

Group by a custom event property:
cURL
curl -X POST 'https://api.vemetric.com/v1/analytics/query' \
  -H 'Authorization: Bearer vem_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "date_range": "30days",
    "group_by": ["event:prop:plan"],
    "metrics": ["users", "events"],
    "filters": [
      {
        "type": "event",
        "name": {
          "operator": "eq",
          "value": "signup"
        }
      }
    ]
  }'

​
Plan Restrictions

Free plans have retention limits on historical data. If you request a date range beyond your plan’s retention period, you’ll receive a 403 error: 
{
  "error": {
    "code": "PLAN_LIMIT_EXCEEDED",
    "message": "Your current plan limits data retention to 90 days. Please upgrade to access historical data beyond this period."
  }
}
See the Errors page for more details.