Skip to main content
The analytics read API returns your reports as JSON, so you can pull metrics into your own systems. Every read is a site-scoped GET authenticated by an API key, and shares one date-window convention:

​
Shared parameters

The analytics reads share a UTC date window and time zone:
​
string
Start of the range (YYYY-MM-DD).
​
string
End of the range (YYYY-MM-DD).
​
string
IANA time zone for bucketing, e.g. America/New_York.
Endpoints that return a time series also take bucket=hour\|day\|week\|month, and breakdowns take a dimension. You can request a compare=previous baseline on timeseries and breakdown.

​
Core endpoints

breakdown accepts dimensions including pathname, hostname, entry_page, exit_page, referrer, channel, country, region, city, browser, os, device_type, utm_*, and event_name. Three composite dimensions group by host and path together, for sites serving one path from several hostnames: pathname_host, entry_page_host, and exit_page_host. Their rows carry hostname and pathname as separate fields alongside the standard value, count, percentage, and pageviews, so you can read either part without parsing value. Hostnames are lowercased when grouped. See Pages for the dashboard equivalent.

​
Where are the rest of the endpoints?

These six are the reads you’ll reach for most, but they’re a fraction of the API. The Endpoints section of this reference documents 133 endpoints across 29 groups — every one with its full path, method, and parameters:

Overview

Headline metrics, time series, and breakdowns.

Performance

Core Web Vitals over time and by dimension.

Feature flags

Manage flags and evaluate them for a user.

Uptime monitors

HTTP and TCP monitors and their history.
Goals, funnels, segments, cohorts, surveys, experiments, dashboards, alerts, annotations, errors, revenue, sessions, users, bots, retention, and journeys each have their own group in the sidebar.
Response bodies aren’t documented yet. Each endpoint page lists its parameters in full, but not the shape of what comes back. To see a real response, run the call in the built-in API playground against your own data.

​
Who can read a site’s analytics?

A read is authorized exactly like signing in: the API key resolves to its owner, and the owner must have access to the site (via organization membership, or a team that grants it). A public site’s reads are open; a private site’s reads require the key. An invalid key on a private site returns 401; a valid key without access returns 403.

​
Frequently asked questions

No. A public site’s reads are open. A private site’s reads require an API key sent as Authorization: Bearer <key> — an invalid key on a private site returns 401, and a valid key whose owner lacks access to the site returns 403.
For parameters, use the Endpoints section of this reference — 133 endpoints across 29 groups, each page listing its full path, method, and parameters. For the response shape, run the call in the built-in API playground against your own data; response bodies aren’t documented in the reference yet.
Yes. Beyond the six core analytics reads, the API covers goals, funnels, segments, cohorts, groups, surveys, feature flags, experiments, dashboards, alerts, annotations, scheduled reports, errors, revenue, performance, sessions, users, user traits, bots, catalog, retention, journeys, and uptime monitoring — 133 endpoints in total. Each has a page in the Endpoints section of this reference.
Yes, on timeseries and breakdown. Request compare=previous to get a baseline. The overview endpoint already returns { "current", "previous", "change" } — the headline metrics, the previous equal-length period, and the percent change.

Scoped SQL query

Run arbitrary read-only SQL instead of fixed reports.

API playground

Build and run any read against your data.

API keys

Create the key a read needs.

Metric definitions

What each metric and dimension means.

Related topics

SQL Analytics APIAPI Rate Limits and CORSIdentify Users API