Docs
Browse the docs

Stats API endpoints

Query the aggregate, timeseries, breakdown and overview stats API endpoints (also MCP tools) with periods, comparisons and filters, and read example responses.

View as Markdown

All four accept the period, comparison and filter inputs and need the analytics.read permission.

Aggregate#

GET /sites/{site_id}/stats/aggregate.json · MCP stats_aggregate

sh 
curl "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json?period=30d&compare=previous_period" \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"
json 
{
  "data": {
    "period": { "from": "2026-08-31T00:00:00+02:00", "to": "2026-09-30T00:00:00+02:00" },
    "metrics": { "visitors": 8120, "visits": 10433, "pageviews": 24871, "views_per_visit": 2.38,
                 "bounce_rate": 38.9, "visit_duration": 52000, "revenue": 1254300 },
    "comparison_period": { "from": "2026-08-01T00:00:00+02:00", "to": "2026-08-31T00:00:00+02:00" },
    "comparison": { "visitors": 7410, "…": "…" },
    "change": { "visitors": 9.6, "visits": 7.1, "…": "…" }
  }
}
  • visit_duration is the median engaged time in milliseconds.
  • bounce_rate is a percentage.
  • revenue is in minor units of the site currency.
  • comparison_period, comparison and change are only present with a compare input.
  • change is the percentage change, or null when the previous value is zero.

Timeseries#

GET /sites/{site_id}/stats/timeseries.json · MCP stats_timeseries

Extra input: interval.

interval Bucket
auto (default) hour for a period of up to 1 day, day up to 92 days, week up to 366 days, month beyond that
minute Only for a period of up to 1 day
hour Only for a period of up to 14 days
day, week, month, quarter, year Any period. Weeks start on Monday

A minute or hour interval on a longer period falls back to auto. The response's interval says which bucket was used.

json 
{
  "data": {
    "period": { "from": "…", "to": "…" },
    "interval": "day",
    "series": [
      { "date": "2026-09-28T00:00:00Z", "visitors": 301, "visits": 377, "pageviews": 902,
        "views_per_visit": 2.39, "bounce_rate": 37.1, "visit_duration": 51000, "revenue": 0 }
    ],
    "comparison_series": [ … ]
  }
}

date is the start of each bucket as wall-clock time in the site's timezone (written with a Z suffix), so 2026-09-28T00:00:00Z means "September 28" in the site's timezone. Empty buckets are included with zeros. comparison_series is only present with a compare input.

Breakdown#

GET /sites/{site_id}/breakdown/{dimension}.json · MCP stats_breakdown

dimension is any key from Filters › Dimensions, including prop:<key>. Extra inputs:

Input What it does
limit Rows per page. Default 10, maximum 1,000
page Page of rows, from 1 (default)
sort visitors, visits, pageviews or revenue, always highest first. The default is visitors for visit dimensions, pageviews for page, and completions for event, goal and properties. On page, event and properties, visitors sorts by visits. Any other sort the dimension has no column for falls back to that default
sh 
curl "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/channel.json?period=7d" \
  -H "Authorization: Bearer $PRIVATUS_TOKEN"
json 
{
  "data": {
    "period": { "…": "…" }, "dimension": "channel", "label": "Channel",
    "page": 1, "limit": 10, "has_more": false,
    "rows": [
      { "value": "organic_search", "visitors": 912, "visits": 1104, "pageviews": 2710, "share": 41.2, "…": "…" },
      { "value": "direct", "visitors": 603, "…": "…", "share": 27.3 }
    ]
  }
}

has_more is true when another page of rows exists. share is the row's percentage of the whole period's total (visitors, pageviews or completions, depending on the dimension).

The columns depend on the dimension:

Dimension Columns in each row
Visit dimensions (channel, country, entry_page…) value, visitors, visits, pageviews, views_per_visit, bounce_rate, visit_duration, revenue
page value, pageviews, visits, time_on_page (median, milliseconds), scroll_depth (median, percent). The last two are null when there is no engagement data
event, prop:<key> value, completions, visits, revenue, conversion_rate (percent of all visits in the period)
goal value (the goal's name), goal_id, completions, conversions (visits that converted), conversion_rate, revenue

Swap .json for .csv to download the rows as CSV.

Overview#

GET /sites/{site_id}/overview.json · MCP stats_overview

Everything the Overview page shows in one request: the aggregate fields, the timeseries fields (interval, series, comparison_series), panels (the top 10 rows of each breakdown, keyed by dimension), notes (up to 100 notes in the period) and live_visitors.

Extra inputs: interval (as for the timeseries) and panels, a list of dimensions to include. The default is channel, referrer, page, entry_page, country, device, browser, os, utm_campaign, event and goal. Property dimensions (prop:<key>) aren't available as panels.