How to use the Plausible Stats API v2

What is different about Stats API v2?

v1 was a family of GET endpoints: one for aggregate, one for timeseries, one for breakdowns, each with its own parameters. v2 is a single POST endpoint that takes a query object.

curl -s https://plausible.io/api/v2/query \
  -H 'Authorization: Bearer <api key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "site_id": "example.com",
    "metrics": ["visitors", "pageviews", "bounce_rate"],
    "date_range": ["2026-10-01", "2026-10-07"],
    "dimensions": ["time:day"]
  }'

One request, three metrics, bucketed daily. Under v1 that was three requests and three response shapes.

The response is rows, not objects

{
  "results": [
    { "metrics": [120, 340, 0.41], "dimensions": ["2026-10-01"] },
    { "metrics": [98, 250, 0.38], "dimensions": ["2026-10-02"] }
  ]
}

metrics is positional: it matches the order you asked for them in. There are no keys.

That is efficient and it is a trap. Reorder your request and every reader downstream silently reads the wrong column. Build a lookup from your own request rather than indexing by a hardcoded number:

const index = Object.fromEntries(query.metrics.map((m, i) => [m, i]));
const visitors = row.metrics[index.visitors];

site_id is the domain

Not a UUID, not a numeric id. example.com, exactly as it appears in your Plausible site list, without a scheme and without a trailing slash.

A site id that does not match returns an error rather than empty data, which is at least a clear failure.

Dimensions do the work

dimensions is where v2 gets its range.

Omit dimensions entirely and you get one row: the aggregate over the whole range. That is the equivalent of the old aggregate endpoint and it is the right call when you want a headline figure rather than a chart.

date_range accepts shorthand

Either an explicit pair of ISO dates, or a shorthand string:

"date_range": "7d"

"day", "7d", "30d", "month", "6mo", "12mo" and "all" are available. The shorthand is resolved in the site's timezone, which saves you computing the boundaries yourself and getting them wrong near midnight.

Realtime is still its own thing

Current visitors is not a v2 query. It remains:

curl -s 'https://plausible.io/api/v1/stats/realtime/visitors?site_id=example.com' \
  -H 'Authorization: Bearer <api key>'

A bare integer, no JSON wrapper.

Rate limits and keys

API keys are per user rather than per site, and one key reads every site you have access to. The limit is generous for dashboards and not for a tight polling loop. Cache anything you refresh more than once a minute.

Or read it off the notch

Notch Metrics queries the v2 endpoint and reports unique visitors, pageviews, sessions and bounce rate in the MacBook notch, bucketed in your Plausible site's own timezone.

One connection, a key that never reaches your Mac. Everything Plausible reports, or download Notch Metrics.