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. Comparison-capable reads accept one of these baseline modes: Custom comparison dates must be historical, non-overlapping, and equal in length to the current window. none is a dashboard URL value, not an API comparison mode; omit compare when you do not want a baseline on timeseries or breakdown reads.

​
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. For raw events, GET /api/sites/{id}/events/log returns individual events with a { data, cursor } envelope. It paginates with an opaque composite cursor (pass the previous response’s nextCursor), accepts direction=older|newer and order=newest|oldest, and filters server-side with q (search over event, URL, user, and session), event_types, event_names, and typed event_props property filters. GET /api/sites/{id}/events/log/{eventId} returns one event by its event ID. Both are documented with full parameters in the Endpoints section.

​
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 149 published 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—149 published 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, uptime monitoring, and read-only workflow definitions, runs, and metrics. The generated reference publishes 149 playground-backed endpoints across 29 groups; workflow reads are not listed in the playground yet.
Yes. Comparison-capable reads accept previous_weekday, previous, year, or custom. A custom baseline also needs compare_start_date and compare_end_date, with the same duration as the current window and no overlap. For response compatibility, overview still returns { "current", "previous", "change" }; when you request a mode, its resolved baseline fills the previous and change fields.

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

TinyAnalytics Account SettingsWebsite and API Uptime MonitoringEvent-Triggered Analytics Workflows