Stats API

A read-only key is enough for everything on this page. Create a key under Account settings → Security (API keys) and send it as Authorization: Bearer …. The query format follows Plausible's Stats API v1 for the common subset.

GET /api/v1/stats/realtime/visitors?site_id=example.com
GET /api/v1/stats/aggregate?site_id=example.com&period=30d&metrics=visitors,pageviews,bounce_rate
GET /api/v1/stats/timeseries?site_id=example.com&period=30d&metrics=visitors
GET /api/v1/stats/breakdown?site_id=example.com&period=30d&property=visit:source&limit=10
GET /api/v1/stats/goals?site_id=example.com&period=30d
GET /api/v1/stats/funnels?site_id=example.com
GET /api/v1/stats/funnels/{id}?site_id=example.com&period=30d
GET /api/v1/stats/annotations?site_id=example.com&period=30d

Parameters

Days begin and end in the site's timezone.

Responses

{ "results": { "visitors": { "value": 1423 }, "pageviews": { "value": 3320 } } }

timeseries returns results as a list of { "date": …, "visitors": … } rows. breakdown returns a list of rows keyed by the property name, for example { "source": "Google", "visitors": 310 }. realtime/visitors returns a number.

Filters

Join clauses with ;. Separate alternative values with |.

filters=visit:country==DE|FR;event:page==/blog/*

Dimensions: event:page, event:goal, event:props:NAME, visit:entry_page, visit:exit_page, visit:source, visit:referrer, visit:channel, visit:utm_medium, visit:utm_source, visit:utm_campaign, visit:utm_content, visit:utm_term, visit:country, visit:region, visit:city, visit:browser, visit:os, visit:device.

Breakdown properties

Any dimension above except event:goal and event:props:* works as property.

Goals, funnels and notes

These take site_id, period, date and filters like the others.

• goals returns results, one row per goal with visitors (unique conversions), events (total), conversion_rate and, for revenue goals, revenue, average_revenue and currency.
• funnels lists the site's funnels (id, name, steps); funnels/{id} returns the visitors reaching each step with drop-off and conversion rates. Funnels come with Pro on Tidemark Cloud.
• annotations returns the notes on the graph for the period that the key's owner may see (date, note, visibility).

OpenAPI

Every endpoint on this page, the Events API and the MCP endpoint are described in an OpenAPI 3.1 document at /api/v1/openapi.json on your installation. It needs no key and works with any API client or code generator.

Errors