# Read API

Read everything the dashboard shows with an account API key: every report from traffic to uptime, the personal data permission, the errors and the limits.

Everything the dashboard shows can be read, and the numbers are the dashboard's own. Reading never changes anything.

## Authentication

Use an **account API key** (`pa_…`, from Developers), as a Bearer token. It acts as you, with your role, on the websites you can open. Website keys (`pk_…`) only send data, so a key kept on a server to report payments can't read anything.

```
curl https://supranalytics.app/api/v1/sites/example.com/overview?period=7d \
  -H "Authorization: Bearer pa_YOUR_KEY"
```

## Personal data

Reports marked below have visitors' names, emails, messages or sessions. They need a key made with **Include visitors' personal data**, and answer `403` otherwise. Keys start without it, and keys made before this existed don't have it. Without it, reports that can name someone leave them out, as a public dashboard does.

## Your websites

`GET /api/v1/sites?period=7d` lists every website you can open, with what its Home card shows: visitors, revenue, the period's figures, who's online, its uptime and site score. Each carries your `role` on it (`owner`, `member` or `viewer`); one shared with you through its [team](https://supranalytics.app/docs/team.md) also has `shared: true` and its `owner_email`. A key reads what its owner can open, with their role on each website, and nothing more: being removed from a team removes that website from the key at once.

## Reports

`GET /api/v1/sites/{id or domain}/{report}`. Take `period`, `from`, `to`, `filters` and `model` as the dashboard does; see [periods and dimensions](https://supranalytics.app/docs/mcp-tools.md).

### Traffic

| Report | What it answers | Takes |
| --- | --- | --- |
| `/` | The website: its id, name, domain, timezone and currency. | nothing |
| `/overview` | Visitors, sessions, pageviews, bounce rate, session time, revenue, customers and conversion rate, with the period before. | period, from, to, filters, model |
| `/timeseries` | Those metrics per hour, day, week or month. | period, from, to, filters, model, interval, types |
| `/breakdown` | Top values of a dimension: channel, referrer, campaign, page, country, device and more. With `previous` set to 1, the period before too, to compare. | period, from, to, filters, model, dim, limit, sort, search, previous |
| `/pages` | Every page viewed, with its numbers and trend. | period, from, to, filters, model, by, sort, dir, search, offset, limit |
| `/insights` | Which sources, pages and other segments convert better or worse than the website as a whole, for the period. | period, from, to |
| `/peak-hours` | The website's data as one week, hour by hour, in its time zone, for visits, goals, sales or revenue. All time unless `range` says less. | metric, range, filters, model |
| `/bots` | AI assistants, search engines and training crawlers requesting the website's pages. | period, from, to, category |
| `/search-console` | Google searches that brought people to the website, for a connected website, as last synced. | period, from, to |
| `/live-count` | How many people are on the website now. | nothing |
| `/live` | Who is on the website now and the latest events. Without people:read, nobody is named. | nothing |
| `/live/history` | The activity feed's recent events. Without people:read, nobody is named. | nothing |

### Conversions

| Report | What it answers | Takes |
| --- | --- | --- |
| `/goals` | Goal completions, conversion rates and revenue. | period, from, to, filters |
| `/goals/timeseries` | Each goal's completions over time. | period, from, to, filters |
| `/goals/sources` | Each goal's top traffic sources and pages. | period, from, to, filters |
| `/funnels` | The website's saved funnels. | nothing |
| `POST /funnels/report` | Visitors reaching each step of a funnel and where they drop off. POST `{ steps }`. | period, from, to, filters, detail, breakdowns |
| `/journeys` | The routes visitors take through the website. | period, from, to, filters, steps, start, goals |

### Site health

| Report | What it answers | Takes |
| --- | --- | --- |
| `/performance` | Real visitors' Core Web Vitals and the latest daily site audit with its history. | period, from, to, filters, model, device |
| `/performance/findings` | The latest site audit's scores and what needs fixing, worst first: what it found, what's expected, the first step, and a prompt to paste into an AI coding tool. | nothing |
| `/uptime` | Whether the website is up: its status, last check, last 24 hours, uptime over 7 to 365 days, response times, latest incidents, and domain and SSL expiry. | range |
| `/uptime/incidents` | Outages with their causes, newest first, a page at a time. | before |

### Behaviour

| Report | What it answers | Takes |
| --- | --- | --- |
| `/heatmap` | Where people click and how far they scroll on a page. | period, from, to, path, device |
| `/heatmap/pages` | The pages with heatmap data. | period, from, to, device |
| `/recordings/summary` | How many sessions were recorded in the period, and how many of each problem tag (rage clicks, errors, slow pages and so on). Nobody is identified. | period, from, to |

### People

| Report | What it answers | Takes |
| --- | --- | --- |
| `/retention` | Of the people who first came in a period, how many came back. Totals only. | every, cohort, return, mode, filters |
| `/visitors` | Visitors in the period, with their names and emails where known. **Personal.** | period, from, to, filters, type, search, limit, offset, activity, time |
| `/visitors/{id}` | One visitor's journey: every visit, page, goal and payment. **Personal.** | nothing |
| `/customers` | The people who paid in the period. **Personal.** | period, from, to, limit |
| `/ltv` | Lifetime value by source and by customer. **Personal.** | period, from, to, filters, dim, by |
| `/payments` | Individual payments with who made them. **Personal.** | period, from, to, model, limit |
| `/completions` | Who completed a goal, and when. **Personal.** | period, from, to, filters, goal, search, limit, offset |
| `/goals/properties` | The values sent with a goal. Personal because a goal's values are whatever your website sends, emails included. **Personal.** | period, from, to, filters, goal |

### Inbox

| Report | What it answers | Takes |
| --- | --- | --- |
| `/chats` | Live chat conversations. **Personal.** | nothing |
| `/chats/{id}` | One visitor's messages. **Personal.** | nothing |
| `/chats/{id}/log` | What the team did in one conversation. **Personal.** | nothing |
| `/chat-search` | Messages containing the words in `q`. **Personal.** | q |

### Recordings

| Report | What it answers | Takes |
| --- | --- | --- |
| `/recordings` | Recorded sessions in the period, with their pages and tags. **Personal.** | period, from, to, sort, order, tag, group, value, skip, before, country, device, min, path, visitor |
| `/recordings/{id}` | One recording's details. **Personal.** | nothing |
| `/recordings/{id}/chunks/{n}` | One piece of a recording's playback data (rrweb events, gzipped JSON). **Personal.** | nothing |
| `/heatmap/snapshot` | A copy of the page a heatmap is drawn on (gzipped JSON). Personal because a page can show what it shows to whoever was on it. **Personal.** | path, device |
| `/heatmap/confetti` | Each click on a page and who made it: their source and device. **Personal.** | period, from, to, path, device, by, sel |

### Notes

| Report | What it answers | Takes |
| --- | --- | --- |
| `/annotations` | What's marked on the chart: notes, chats and commits by time. **Personal.** | period, from, to |
| `/notes` | Notes the team made on the chart. | period, from, to |
| `/segments` | The team's saved filters. | nothing |

## Not available here

Settings and controls aren't part of this: team, alert setup, sounds, the proxy, chat replies and page alerts, and integration setup. The continuous live stream stays in the dashboard; poll `/live` instead.

## Errors and limits

| Status | Meaning |
| --- | --- |
| `401` | No key, or not an account key. |
| `402` | The website's account is blocked: code USAGE_LIMIT_REACHED (its monthly event limit), TRIAL_EXPIRED, SUBSCRIPTION_EXPIRED or PLAN_REQUIRED, with state and billing_url, and resets_at when a reset is due. |
| `403` | The report needs personal data this key wasn't given, or it's an Inbox report (conversations, their log, chat search) and you're a viewer on that website. |
| `404` | No such report, or a website you can't open. |
| `429` | Too many requests. Wait the number of seconds in the Retry-After header. |

3,000 requests a minute per key.

---

This page on the web: https://supranalytics.app/docs/api/read
Every documentation page: https://supranalytics.app/docs.md