Date ranges
Ranges use the site timezone. day is today until now; 7d, 28d, 30d, and 91d cover past complete days and exclude today. An explicit pair of calendar dates includes both dates. Timestamp pairs describe the supplied time interval. Daylight-saving transitions are handled using the site timezone.
{
"site_id": "example.com",
"metrics": ["visitors", "pageviews"],
"date_range": "7d",
"dimensions": ["visit:country"],
"include": {"imports": true, "total_rows": true},
"pagination": {"limit": 50, "offset": 0}
}
Dimensions and filters
Use up to nine dimensions. Custom properties use event:props:NAME. A leaf filter is ["is", "visit:country", ["CN"]]. Operators include is, is_not, contains, contains_not, matches, and matches_not. Logical groups use and/or with child filter arrays; not, has_done, and has_not_done wrap one filter. Queries accept up to 100 filter nodes and eight levels.
Conversion metrics need a goal constraint; page engagement metrics need a page constraint. Unsupported combinations return 400, not misleading zeroes. Revenue metrics are currently unavailable (null).
Pagination and totals
V2 accepts limit 1–10,000 and offset up to 1,000,000; request include.total_rows for a count. Sites lists use cursor pagination, limit 1–100, and meta.after/meta.before (only one cursor per request).
Unique visitors in separate rows, dates, or dimensions cannot generally be added to obtain overall unique visitors. Query a total without that dimension when you need an overall count.
Imported history
include.imports defaults to false. Imported aggregates cannot recreate individual events, arbitrary filter combinations, or funnels. Check response metadata for unsupported dimensions and incomplete coverage. Historical summary replacement windows can take precedence over live totals while retaining raw events for funnels.
Realtime
GET /api/v1/stats/realtime/visitors counts distinct visitors in the last five minutes. The realtime page's map and activity view cover thirty minutes. These are deliberately different windows.