Analytics API and MCP
Every number on the Analytics pages is also available outside the dashboard. A script can read it from the REST API, and an AI assistant such as Claude can read it through the MCP server. All three read the same data through the same code. For the same filters and dates, the API, the MCP server, and the dashboard return the same numbers.
You can read everything and create saved reports. Editing and deleting saved reports stays in the dashboard.
Giving a key access
API keys need the Analytics read scope, analytics:read. Creating saved
reports needs the write scope, analytics:write. Add it when you
create or edit a key in Organization Settings
→ API Keys. Keys with Full read access or Full access already include
it.
The reader timeline includes a reader's name and email only when the key also
has audience-members:read. Without it, readers are identified by ID only.
MCP clients need no extra setup. Anyone who can view the Analytics pages can read analytics through the MCP server.
What you can read
The API is organized around the data rather than the pages. Each Analytics page
maps to these endpoints, all under /api/v1/analytics:
| In the dashboard | API endpoint | MCP tool |
|---|---|---|
| Event types, filters, properties | GET /schema | get-analytics-schema-tool |
| Pulse | GET /realtime | get-analytics-realtime-tool |
| Events → Page views | GET /traffic | get-analytics-view-tool with view: traffic |
| Events → Time on site | GET /time-on-site | get-analytics-view-tool with view: time-on-site |
| Events → Content gates | GET /gates | get-analytics-view-tool with view: gates |
| Events → Sign-ups, Logins, Purchases | GET /sign-ups, GET /logins, GET /purchases | get-analytics-view-tool with view: sign-ups, logins, or purchases |
| Event counts on the Events tabs | GET /event-counts | get-analytics-view-tool with view: event-counts |
| Events → All events chart and breakdown | GET /explore | get-analytics-view-tool with view: explore |
| Events → All events event list | GET /events | list-analytics-events-tool |
| A story's performance | GET /content?path=/news/story | get-content-analytics-tool |
| A reader's timeline | GET /readers/{id} | get-reader-analytics-tool |
| Reports list | GET /reports | list-analytics-reports-tool |
| A saved report and its result | GET /reports/{id}, GET /reports/{id}/results | get-analytics-report-tool |
| The report builder's preview | POST /query | query-analytics-tool |
Each built-in report in the reports list names the endpoint that returns its data. The API reference lists every parameter and response field for each endpoint.
Creating saved reports
A script can save a report with POST /api/v1/analytics/reports, and an
assistant can save one with create-analytics-report-tool. Either way, the
report takes a name, an optional description, whether it is pinned to the Pulse,
and a definition in the same shape POST /query runs. Use the same values the
report builder offers: measures, event types, filters, a breakdown, a time
bucket, a preset range, and a chart type. The new report appears under Saved
Reports for the whole team.
Through the API, any key with analytics:write can save a report. Through the
MCP server, saving a report requires the admin role. (Managing report email
subscriptions is the exception — see
Report email subscriptions.) A signed-in team
member is recorded as the report's creator. A report saved with an organization
key has no creator.
Report email subscriptions
An assistant can manage who gets a report by email, the same subscriptions the Subscribe dialog sets up in the dashboard. These are available over the MCP server only — the REST API does not expose them.
| MCP tool | What it does |
|---|---|
list-analytics-report-subscriptions-tool | Lists who gets a report and how often. |
subscribe-analytics-report-tool | Emails a report to an address, weekly or monthly. Subscribing an address that already gets it changes how often. |
unsubscribe-analytics-report-tool | Stops emailing a report to one address. Requires confirm: true. |
For list-analytics-report-subscriptions-tool and
subscribe-analytics-report-tool, name the report with report_id for a saved
report or built_in_report for a built-in one.
unsubscribe-analytics-report-tool instead takes the subscription's own id,
which list-analytics-report-subscriptions-tool returns. Permissions mirror the
dashboard: anyone who can view the report may subscribe their own address, while
admins and members may subscribe or remove others. See
Report emails for the dashboard side and the
schedule.
Filters
The endpoints and tools accept the same filters as the Analytics page header:
| Filter | What it does |
|---|---|
range | A preset window ending today: 7d, 30d (the default), 90d, or 1y. |
start, end | Custom dates (2026-10-01) in your organization's time zone. As in the dashboard, the end can't be later than today and the window is at most a year. |
property | Limits the data to one property. |
product | Limits purchase and conversion data to one product. |
include | Returns only some sections of a larger response, for example include=counts,spiking on the Pulse. |
Numbers are always compared with the previous window of the same length, as they are in the dashboard. Every response says which dates it covers, which window it was compared against, and when it was generated.
Saved reports run over their own date range unless you pass range or start
and end. With the API you can run a saved report over any dates, even though
the dashboard only offers its preset ranges.
Limits and errors
Each API key or MCP connection can make 60 analytics requests a minute. The API and the MCP server share cached results with the dashboard, so repeated requests for the same data come back quickly.
| Response | Meaning |
|---|---|
503 ANALYTICS_UNAVAILABLE | The analytics service didn't answer. Retry after the number of seconds in the Retry-After header (60). |
503 ANALYTICS_NOT_CONFIGURED | Analytics isn't set up for your organization. Retrying won't help. |
422 ANALYTICS_REJECTED_INPUT | The analytics service rejected the filters. Check them against GET /schema. |
422 validation error | A filter or section name isn't one of the allowed values. |
429 | Over the 60-a-minute limit. |
A story whose page hasn't been indexed yet isn't an error. It returns its
numbers with empty details, as the dashboard does.
To keep answers small enough for an assistant, MCP tools return at most 25 rows in each ranked list, such as top stories or referrers. Each list that was cut includes a note with the full count. Charts over time are always complete. Use the API when you need every row.