POST /api/v2/query
Permission: Stats / Sites. Up to 600 requests per key per hour.
Authentication
Send Authorization: Bearer $EVUMI_API_KEY from your server. Read the permission and rate-limit guide.
Request body
{
"type": "object",
"required": [
"site_id",
"metrics",
"date_range"
],
"properties": {
"site_id": {
"type": "string",
"description": "Site domain, not a teamId or site UUID"
},
"metrics": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"enum": [
"visitors",
"visits",
"pageviews",
"events",
"bounce_rate",
"visit_duration",
"views_per_visit",
"percentage",
"conversion_rate",
"group_conversion_rate",
"scroll_depth",
"time_on_page",
"total_revenue",
"average_revenue"
]
},
"description": "Revenue metrics currently return null. Time on page is also null when unavailable."
},
"date_range": {
"oneOf": [
{
"enum": [
"day",
"24h",
"7d",
"28d",
"30d",
"91d",
"month",
"6mo",
"12mo",
"year",
"all"
]
},
{
"type": "array",
"items": {
"type": "string"
},
"minItems": 2,
"maxItems": 2
}
],
"description": "Uses the site timezone. day is today so far; 7d and similar ranges exclude today. Custom date ranges include both endpoints."
},
"dimensions": {
"type": "array",
"maxItems": 9,
"items": {
"anyOf": [
{
"enum": [
"event:page",
"event:hostname",
"event:goal",
"event:name",
"visit:entry_page",
"visit:entry_page_hostname",
"visit:exit_page",
"visit:exit_page_hostname",
"visit:source",
"visit:referrer",
"visit:channel",
"visit:utm_source",
"visit:utm_medium",
"visit:utm_campaign",
"visit:utm_content",
"visit:utm_term",
"visit:device",
"visit:browser",
"visit:browser_version",
"visit:os",
"visit:os_version",
"visit:country",
"visit:region",
"visit:city",
"visit:country_name",
"visit:region_name",
"visit:city_name",
"time",
"time:minute",
"time:hour",
"time:day",
"time:week",
"time:month"
]
},
{
"type": "string",
"pattern": "^event:props:.+"
}
]
}
},
"filters": {
"type": "array",
"items": {
"type": "array"
},
"description": "Leaf: [is|is_not|contains|contains_not|matches|matches_not, dimension, [values]]. and/or take a child-node array; not/has_done/has_not_done take one node. Maximum 100 nodes and 8 levels."
},
"order_by": {
"type": "array",
"items": {
"type": "array",
"prefixItems": [
{
"type": "string"
},
{
"enum": [
"asc",
"desc"
]
}
],
"minItems": 2,
"maxItems": 2
}
},
"include": {
"type": "object",
"properties": {
"imports": {
"type": "boolean",
"default": false
},
"time_labels": {
"type": "boolean"
},
"total_rows": {
"type": "boolean"
}
},
"additionalProperties": false
},
"pagination": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 10000
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 1000000,
"default": 0
}
},
"additionalProperties": false
}
}
}
Today overview
{
"site_id": "example.com",
"metrics": [
"visitors",
"visits",
"pageviews"
],
"date_range": "day"
}
Countries
{
"site_id": "example.com",
"metrics": [
"visitors",
"pageviews"
],
"date_range": "7d",
"dimensions": [
"visit:country"
],
"include": {
"imports": true,
"total_rows": true
},
"pagination": {
"limit": 50,
"offset": 0
}
}
App, OS and version
{
"site_id": "example.com",
"metrics": [
"visitors"
],
"date_range": "day",
"dimensions": [
"visit:browser",
"visit:browser_version",
"visit:os"
],
"pagination": {
"limit": 100,
"offset": 0
}
}
Events and properties
{
"site_id": "example.com",
"metrics": [
"events",
"visitors"
],
"date_range": "day",
"dimensions": [
"event:name",
"event:props:plan"
],
"filters": [
[
"is",
"event:name",
[
"Signup"
]
]
],
"pagination": {
"limit": 100,
"offset": 0
}
}
Hourly trend
{
"site_id": "example.com",
"metrics": [
"visitors",
"pageviews"
],
"date_range": "day",
"dimensions": [
"time:hour"
],
"include": {
"time_labels": true
},
"order_by": [
[
"time:hour",
"asc"
]
]
}
Responses
| Status | Meaning |
|---|---|
| 200 | Success. v2 array order matches the requested metrics and dimensions. |
| 400 | Invalid parameters |
| 401 | Invalid API key |
| 403 | Insufficient permission |
| 404 | Site outside authorized scope |
| 429 | Too many requests |
Example response
{
"results": [
{
"dimensions": [],
"metrics": [
12,
15,
28
]
}
],
"query": {
"site_id": "example.com",
"metrics": [
"visitors",
"visits",
"pageviews"
],
"date_range": "day",
"dimensions": []
},
"meta": {}
}
Response schema
{
"type": "object",
"required": [
"results",
"query",
"meta"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimensions",
"metrics"
],
"properties": {
"dimensions": {
"type": "array",
"items": {
"type": [
"string",
"number",
"null"
]
}
},
"metrics": {
"type": "array",
"items": {
"type": [
"number",
"null"
]
}
}
}
}
},
"query": {
"type": "object",
"description": "Normalized query, including requested metrics and dimensions"
},
"meta": {
"type": "object",
"description": "Coverage, imported-history warnings, pagination and optional time labels"
}
}
}