Analytics API

An HTTP API for your site analytics. The org-key REST API is read-only and needs Pro or Business. Personal keys from login also work on Free for a reduced set of read routes and for creating sites and goals. Base URL:

https://api.satsu.pro/v1

Quickstart

Create a key under API keys in the dashboard sidebar, then read your overview:

bash

# list your sites
curl https://api.satsu.pro/v1/sites \
  -H "Authorization: Bearer satsu_live_..."
 
# overview for one site, last 30 days
curl "https://api.satsu.pro/v1/sites/{site_id}/overview" \
  -H "Authorization: Bearer satsu_live_..."

Authentication

Every request needs an API key in the Authorization header:

http

Authorization: Bearer satsu_live_xxxxxxxxxxxxxxxxxxxx

There are two kinds of keys:

Org keys are created per organization under API keys in the dashboard sidebar and shown once — store yours somewhere safe. An org key grants read access to every site in its organization and needs Pro or Business.
Personal keys come from satsu-analytics login (or init) and act as you: same workspaces, same role. They work on every plan. On Free they reach these routes: sites, overview, timeseries, goals, workspaces, install check, breakdowns by pages and referrers, and creating and updating sites and goals. Other routes answer 402 with an upgrade_url. The MCP tools use the same routes.

Revoke either kind any time under API keys; it stops working immediately.

Endpoints

This page covers the main read endpoints; More routes lists the rest. Site-scoped paths take a site_id (your site's public ID).

List sites

http

GET /v1/sites

json

{
  "sites": [
    { "id": "a1b2c3d4e5", "name": "acme.com", "domain": "acme.com" }
  ]
}

Overview

Headline totals for the range: visitors, pageviews, custom events, bounce rate, average visit duration.

http

GET /v1/sites/{site_id}/overview

json

{
  "visitors": 3878,
  "pageviews": 7179,
  "custom_events": 214,
  "bounce_rate": 0.56,
  "avg_duration_s": 166
}

Timeseries

Visitors and pageviews per bucket. Set ?interval=hour or ?interval=day.

http

GET /v1/sites/{site_id}/timeseries

Breakdown

Top values for a dimension — one of pages, referrers, campaigns, channels, countries, devices, browsers, operating-systems, events.

http

GET /v1/sites/{site_id}/breakdown/{dimension}

json

[
  { "value": "DE", "visitors": 877, "pageviews": 1614 },
  { "value": "US", "visitors": 633, "pageviews": 1190 }
]

Goal conversions

Conversion totals and rate for a goal. Add ?breakdown= to split by a dimension.

http

GET /v1/sites/{site_id}/goals/{goal_id}/conversions

More routes

The plan column applies to personal keys; org keys need Pro or Business for every route. Routes marked personal answer 403 user_key_required to an org key.

Route	Keys	Plan
`GET /v1/sites/{site_id}/live`	Org, personal	Pro
`GET /v1/sites/{site_id}/goals`	Org, personal	All
`GET /v1/sites/{site_id}/install-check`	Org, personal	All
`GET /v1/workspaces`	Personal	All
`GET /v1/sites/{site_id}/monitors`	Personal	Pro
`GET /v1/sites/{site_id}/audits`	Personal	Pro
`POST /v1/sites`, `PATCH /v1/sites/{site_id}`	Personal	All
`POST /v1/sites/{site_id}/goals`, `PATCH /v1/sites/{site_id}/goals/{goal_id}`	Personal	All
`POST /v1/sites/{site_id}/audits/{pillar}/run`	Personal	Pro
`POST /v1/sites/{site_id}/monitors`	Personal	Pro

Query parameters

Parameter	Values
`from`, `to`	RFC3339 or `YYYY-MM-DD`. Defaults to the last 30 days. Clamped to your plan's retention window.
`interval`	`hour` or `day` (timeseries).
Filters	`path`, `referrer`, `campaign`, `country`, `device`, `browser`, `os`, `event`, `channel`. One value each, combined with AND.

Rate limits

Requests are limited per key. Every response carries the current budget; a limited request returns 429 with Retry-After.

http

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1783768800

Errors

Errors are JSON with a stable code:

json

{ "error": { "code": "invalid_key", "message": "invalid or revoked API key" } }

Status	Meaning
`401`	Missing, invalid or revoked key.
`402`	`plan_required` — a personal key on Free called a Pro route. The body is `{ "error": "plan_required", "plan": "pro", "upgrade_url": "…" }`.
`403`	`plan_downgraded` — the org no longer includes API access.
`403`	`user_key_required` — the route needs a personal key (`satsu-analytics login`).
`404`	The site isn't in your organization (or doesn't exist).
`404`	`unknown_dimension` — the breakdown dimension doesn't exist.
`429`	Rate limited; retry after the window.
`502`	`upstream_unavailable` — the analytics backend is briefly unreachable; retry.

Service status

Live status, response times and 90-day uptime of the API and every other component are on status.satsu.pro. The same data is machine-readable at https://status.satsu.pro/api/status.json (no key, CORS open), and incidents are published as an Atom feed at https://status.satsu.pro/feed.xml.