Analytics Read API

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:

curl "https://dash.tinyanalytics.io/api/sites/1/overview?start_date=2026-07-01&end_date=2026-07-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

await fetch(
  "https://dash.tinyanalytics.io/api/sites/1/overview?start_date=2026-07-01&end_date=2026-07-15",
  {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  },
)

import requests

requests.get(
    "https://dash.tinyanalytics.io/api/sites/1/overview",
    params={"start_date": "2026-07-01", "end_date": "2026-07-15"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

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:

Parameter	Meaning
`compare=previous_weekday`	Equal-length previous period aligned to the same weekdays.
`compare=previous`	Equal-length period immediately before the current range.
`compare=year`	The same dates one year earlier.
`compare=custom`	An equal-length custom period supplied with `compare_start_date` and `compare_end_date`.

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.

Filter by user trait

The shared filters parameter accepts a templated trait dimension, trait:<key>, that scopes any analytics read to identified users by the current value of a trait. The filter matches identified users only — never anonymous traffic — and reads the value at query time, so a Q1 report filtered to plan = pro includes January activity of users who upgraded in March.

curl -G "https://dash.tinyanalytics.io/api/sites/1/overview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "start_date=2026-01-01" \
  --data-urlencode "end_date=2026-03-31" \
  --data-urlencode 'filters=[{"dimension":"trait:plan","op":"equals","value":["pro"]}]'

The trait ops are equals, not_equals, contains, not_contains, starts_with, ends_with, is_null, and is_not_null — regex is not available on trait dimensions, and not_equals also matches identified users with no such key at all. The UI’s “is set” / “is not set” labels map to is_not_null / is_null. Limits: at most 4 trait filters per query, a key of at most 200 characters, and a filter matching more than 10,000 identified users fails with 400 TRAIT_FILTER_TOO_BROAD (recover by composing is_not_null with a not_equals exclusion). Trait filters require a member session or a key with Users: Read; requests through a public site’s open dashboard, a share link, or an embed are refused with 400 rather than silently unfiltered results. See Analytics filters for the dashboard equivalent.

Core endpoints

Endpoint	Returns
`GET /api/sites/{id}/live`	`{ "count" }` — distinct sessions active in the last 5 minutes.
`GET /api/sites/{id}/overview`	`{ "current", "previous", "change" }` — the headline metrics, the previous equal-length period, and the percent change.
`GET /api/sites/{id}/timeseries`	`{ "data": [{ "time", "value" }] }` — one `metric` bucketed over the range, zero-filled.
`GET /api/sites/{id}/timeseries/by-dimension`	`{ "data": [{ "value", "series": [{ "time", "value" }] }] }` — sessions per `bucket`, one series per top value of one session `dimension` (`limit` values, default 100, max 1000), ranked by total sessions.
`GET /api/sites/{id}/breakdown`	`{ "data": [{ "value", "count", "percentage", "pageviews" }] }` — the top values of one `dimension`. Add `first_seen=true` to include each row’s `firstSeen`.
`GET /api/sites/{id}/sessions`	`{ "data": [ … ] }` — the paginated session list (`page`, `limit`), newest first.
`GET /api/sites/{id}/events`	`{ "data": [ … ] }` — the custom-event list, or one event’s property breakdown when you pass `event_name`.

breakdown accepts dimensions including pathname, hostname, entry_page, exit_page, referrer, channel, country, region, city, browser, os, device_type, utm_*, and event_name. breakdown?first_seen=true adds firstSeen to every row — a UTC datetime of the value’s all-time first appearance, unrestricted by the date range (for example, the day an AI assistant first sent you a session). It works for session dimensions only — hostname, referrer, channel, country, region, city, language, browser, operating_system, device_type, ai_assistant, and the utm_* dimensions; a page or event dimension such as pathname or event_name returns 400. timeseries/by-dimension is the per-value split of the sessions series: pass a required session dimension (the same list as first_seen), an optional bucket, and limit (default 100, max 1000) with the common date, time-zone, and filters parameters. It returns one series per top value, ranked by total sessions and not folded — there is no server-side “Other” row — and it does not accept compare. Series are not zero-filled: a bucket with no sessions for a value is simply absent from that value’s series. Both endpoints use the same API-key authentication and the analytics:read scope as every other read on this page. 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 applies q (search over event, URL, user, and session), event_types, event_names, and typed event_props property filters before returning results. 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 155 published endpoints across 30 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.

Heatmaps

Click, rage-click, and cumulative scroll-reach data.

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

Do I need an API key to read a public site?

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.

How do I find an endpoint's exact parameters and response?

For parameters, use the Endpoints section of this reference—155 published endpoints across 30 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.

Does TinyAnalytics have an API for goals, funnels, or feature flags?

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, heatmaps, sessions, users, user traits, bots, catalog, retention, journeys, uptime monitoring, and read-only workflow definitions, runs, and metrics. The generated reference publishes 155 playground-backed endpoints across 30 groups; workflow reads are not listed in the playground yet.

Can I compare a date range against the previous period?

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.

Start here

Browser APIs

Data API

Authentication & tools

Endpoint reference

Shared parameters

Filter by user trait

Core endpoints

Where are the rest of the endpoints?

Overview

Performance

Heatmaps

Feature flags

Uptime monitors

Who can read a site’s analytics?

Frequently asked questions

Scoped SQL query

API playground

API keys

Metric definitions

​Shared parameters

​Filter by user trait

​Core endpoints

​Where are the rest of the endpoints?

Overview

Performance

Heatmaps

Feature flags

Uptime monitors

​Who can read a site’s analytics?

​Frequently asked questions

​Related

Scoped SQL query

API playground

API keys

Metric definitions

Shared parameters

Filter by user trait

Core endpoints

Where are the rest of the endpoints?

Who can read a site’s analytics?

Frequently asked questions

Related