query_site_analytics

It answers what the fixed shape of get_site_analytics cannot, and it is the tool for top pages, traffic sources, countries, browsers, operating systems and devices. The site is filled in for you, so there is no site_id to send, and anything passed for it is overwritten.

Pick metrics from visitors, visits, pageviews, views_per_visit, bounce_rate and visit_duration. Set date_range to a named period such as 7d or 30d, or to a two element list of ISO dates, where a custom range longer than 3,660 days is refused. Add dimensions to break the numbers down: event:page for top pages, visit:source for traffic sources, visit:country, visit:browser, visit:os, visit:device, or time:day, time:hour or time:month for a series over time.

pagination.limit caps the rows at 1,000, a larger value is lowered to 1,000, and leaving it out returns up to that many. Pagination only applies when you break down by a dimension, and the product itself uses 8 for its breakdown cards. time:minute is not available, and time:hour needs day, 7d, 30d, month or a custom range of at most 31 days.

The response carries provisioned, the analytics domain, the results rows and the query meta. A query the analytics backend rejects fails with its reason, so an empty results list really means no matching traffic.

Each call costs 1 of the 1,200 analytics lookups access tokens share per site per hour, as Rate limits and result size explains, and nothing when the answer is already cached. Unlike the tools that read fixed numbers, it spends that lookup even on a site that was never published. Over that limit it fails with Access tokens, through MCP clients or the API, used their 1,200 analytics lookups for this site this hour. Wait and try again! See Breakdowns.

Inputs

Input	Type	Required	Description
projectId	string	Yes	The site id.
query	object	Yes	The Plausible Stats v2 query, with the fields metrics, date_range, dimensions, filters (for example [["is", "visit:country", ["DE"]]]), order_by, pagination with its limit and offset, and include, such as time_labels true for a labeled series. site_id is set for you, and anything passed for it is overwritten.