Satsu documentation, full text. Canonical: https://satsu.pro/llms-full.txt · Index and fact sheet: https://satsu.pro/llms.txt
---
# Introduction
Source: https://satsu.pro/docs
## Satsu documentation
Satsu is **cookieless, privacy-first web analytics**, built for GDPR. You add one
script tag and watch your traffic live — no consent banner needed, no Google.
It works because Satsu never stores a cookie or a persistent visitor ID. Each
visitor is a hash derived fresh from `sha256(site + ip + user-agent + day + salt)`
that **changes at 00:00 UTC and cannot be linked across days**. No cookies and no
persistent identifiers, so in our assessment no consent banner is needed; check
with your own counsel for your site. See
[How it's private](/docs/privacy) for the full mechanism.
### Install in one line
```html
```
Drop that into your `
`, replacing `YOUR_ID` with your site's ID from the
dashboard. Pageviews start flowing in seconds. Full guide:
[Install the tracker](/docs/install).
### What you get
- **Pageviews, referrers, countries, devices** — the essentials, in real time.
- **Custom events and goals** — track signups, clicks, revenue moments.
- **Automatic engagement tracking** — outbound links, downloads and scroll depth,
with zero extra code.
- **An API** — pull your numbers into scripts, dashboards and reports. Org keys
are read-only on Pro and Business; personal keys also work on Free and can
create sites and goals.
### Where to go next
- [Install the tracker](/docs/install) — the snippet, per framework.
- [Verify it works](/docs/verify) — confirm your first data.
- [Custom events](/docs/events) — `window.satsu("signup")`.
- [Goals & conversions](/docs/goals) — turn events and paths into conversions.
- [What we track](/docs/what-we-track) — every signal, and what we refuse to collect.
- [How it's private](/docs/privacy) — the cookieless design, in detail.
- [Analytics API](/docs/api) — the REST API, org and personal keys.
Building with an AI assistant? Point it here — these docs are public and
copy-paste ready.
---
# Install the tracker
Source: https://satsu.pro/docs/install
## Install the tracker
The Satsu tracker is a single `
```
Replace `YOUR_ID` with your site's ID (find it in the dashboard under **Sites →
your site → install**). That's the entire integration — everything below is just
where to put it in your framework.
### Attributes
| Attribute | Required | What it does |
|---|---|---|
| `data-site` | Yes | Your site ID. Without it the tracker does nothing. |
| `data-api` | No | Override the ingest endpoint. Defaults to the script's own origin + `/e`, so you normally never set this. |
| `data-track-paths` | No | Comma-separated path prefixes to limit tracking to (e.g. `/,/docs,/blog`). Only paths at or under one of them are tracked; everything else is ignored, even across client-side navigation. Omit to track every path. See [Single-page apps](#single-page-apps). |
### Pick your stack
### Single-page apps
The tracker handles client-side routing automatically. It hooks `pushState`,
`replaceState` and `popstate`, so **every route change is counted as a pageview**
— no router integration or manual calls needed. Repeated navigations to the same
path are de-duplicated.
#### Tracking only some paths
Because the tracker follows client-side navigation, a script that loads on one
page stays active as the user moves through your app. If your marketing site and
your signed-in app live on the **same domain** — say `/` and `/pricing` are
public but `/app` and `/dashboard` are behind a login — you usually don't want to
count the logged-in pages.
Use `data-track-paths` to scope tracking to a list of path prefixes:
```html
```
Now only `/`, `/pricing`, `/docs`, `/blog` and anything beneath them (like
`/docs/install`) are tracked. A visit to `/dashboard` — or any route not in the
list — is ignored, and the tracker stays silent there even after the visitor
navigated in from a tracked page. Matching is on a path boundary, so `/docs`
covers `/docs` and `/docs/install` but not `/docs-archive`; list `/` on its own
to match the home page exactly, not the whole site.
Omit the attribute entirely to track every path (the default).
### Building with an AI assistant?
Paste the script tag into your layout's ``. No package needed;
`npx satsu-analytics init` can do it for you.
### What's tracked automatically
Once installed, with no extra code, Satsu records pageviews, SPA route changes,
outbound link clicks, file downloads and scroll depth. See
[What we track](/docs/what-we-track) for the full list, or
[Custom events](/docs/events) to track your own.
Next: [Verify it works →](/docs/verify)
---
# Verify it works
Source: https://satsu.pro/docs/verify
## Verify it works
Once the [script tag](/docs/install) is on your site, here's how to confirm data
is flowing.
### 1. Load a page
Open your site in a browser and visit a page or two. The tracker fires a pageview
on load and on every route change.
### 2. Check the network request
Open your browser's DevTools → **Network** tab and filter for `/e`. You should
see a `POST` to `https://track.satsu.pro/e` on each pageview, returning `202
Accepted`. That's the event reaching Satsu.
If you don't see it, check that:
- `data-site` is present and matches your site ID.
- The script isn't blocked by a content blocker (some block anything named
`tracker.js` — rare, but worth ruling out on your own machine).
- You haven't set the opt-out flag (see below).
### 3. Watch the live view
In the dashboard, open your site and look at the **Live** count — it updates from
presence heartbeats within a few seconds of you loading a page. Seeing yourself
there is the fastest confirmation it works.
Full pageview and event numbers appear on the dashboard within moments; the live
count is the real-time signal.
### Excluding your own visits
To stop the tracker counting your own traffic (e.g. while developing), set a flag
in the browser's console:
```js
localStorage.setItem("satsu_ignore", "true");
```
The tracker checks this on load and does nothing when it's set. Remove it with:
```js
localStorage.removeItem("satsu_ignore");
```
### Still nothing?
- Confirm the site ID is correct — a wrong or unknown ID is silently dropped.
- Make sure the tag is in the served HTML (check "View Source", not just your
source files — a build step might be stripping it).
- Reach out at [hello@satsu.pro](mailto:hello@satsu.pro) and we'll help.
Next: [Custom events →](/docs/events)
---
# Install Satsu on Next.js
Source: https://satsu.pro/docs/frameworks/nextjs
## Next.js
The `` component from `satsu-analytics/next` loads the tracker once, counts client-side route changes and does nothing on the server. It supports the App Router and the Pages Router.
### Setup
Skip to **Verify it works** if init finished. To do it by hand, continue with the next steps.
#### Or install the package yourself
#### Set the site ID
Create a site in the dashboard (**Sites → your site → install**) and put its ID into `.env.local`:
```sh
NEXT_PUBLIC_SATSU_SITE=YOUR_ID
```
The component reads `NEXT_PUBLIC_SATSU_SITE` when you don't pass `site`, so staging and production can use different sites without code changes.
#### Add the component
App Router, in `app/layout.tsx`:
```tsx
import { Satsu } from "satsu-analytics/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
Pages Router, in `pages/_app.tsx`:
```tsx
import type { AppProps } from "next/app";
import { Satsu } from "satsu-analytics/next";
export default function App({ Component, pageProps }: AppProps) {
return (
<>
>
);
}
```
#### Verify it works
Start your app with `npm run dev`. On localhost the tracker itself is not loaded; the component sends one dev ping per page load so the install check can confirm the setup, and it is never counted or shown in your stats. After you deploy, follow [Verify it works](/docs/verify) to see the first real visit.
Next: [track custom events](/docs/package#track) and [type them from your goals](/docs/cli#types). Prefer no package? The [script tag](/docs/install) works too.
---
# Install Satsu on React (Vite)
Source: https://satsu.pro/docs/frameworks/react
## React (Vite)
The `` component from `satsu-analytics/react` injects the tracker once after mount. It renders nothing and follows client-side navigation on its own.
### Setup
Skip to **Verify it works** if init finished. To do it by hand, continue with the next steps.
#### Or install the package yourself
#### Set the site ID
Create a site in the dashboard (**Sites → your site → install**) and put its ID into `.env.local`:
```sh
VITE_SATSU_SITE=YOUR_ID
```
The component falls back to `VITE_SATSU_SITE` when you don't pass `site`.
#### Add the component
In `src/main.tsx`:
```tsx
import { createRoot } from "react-dom/client";
import { Satsu } from "satsu-analytics/react";
import App from "./App";
createRoot(document.getElementById("root")!).render(
<>
>,
);
```
#### Verify it works
Run `npm run dev`. On localhost the tracker itself is not loaded; the component sends one dev ping per page load so the install check can confirm the setup, and it is never counted or shown in your stats. After you deploy, follow [Verify it works](/docs/verify) to see the first real visit.
Next: [track custom events](/docs/package#track) and [type them from your goals](/docs/cli#types). Prefer no package? Put the [script tag](/docs/install) in `index.html`.
---
# Install Satsu on Vue and Nuxt
Source: https://satsu.pro/docs/frameworks/vue-nuxt
## Vue and Nuxt
Nuxt gets a module that registers a client-only plugin. Plain Vue 3 (Vite) gets a component that renders nothing. Both load the tracker once and follow client-side navigation.
### Setup
Skip to **Verify it works** if init finished. To do it by hand, continue with the next steps.
#### Or install the package yourself
#### Set the site ID
Create a site in the dashboard (**Sites → your site → install**) and put its ID into your env file.
#### Add the module or component
```
### Verify it works
Run your dev server. On localhost the tracker itself is not loaded; the component sends one dev ping per page load so the install check can confirm the setup, and it is never counted or shown in your stats. After you deploy, follow [Verify it works](/docs/verify) to see the first real visit.
Next: [track custom events](/docs/package#track) and [type them from your goals](/docs/cli#types). Prefer no package? The [script tag](/docs/install) works too.
---
# Install Satsu on Astro
Source: https://satsu.pro/docs/frameworks/astro
## Astro
The `Satsu.astro` component from `satsu-analytics/astro` adds the tracker to the pages that render it. Put it in your base layout and every page is covered.
### Setup
Skip to **Verify it works** if init finished. To do it by hand, continue with the next steps.
#### Or install the package yourself
#### Set the site ID
Create a site in the dashboard (**Sites → your site → install**) and put its ID into `.env`:
```sh
PUBLIC_SATSU_SITE=YOUR_ID
```
The component falls back to `PUBLIC_SATSU_SITE` when you don't pass `site`.
#### Add the component
In your base layout, for example `src/layouts/Layout.astro`:
```astro
---
import Satsu from "satsu-analytics/astro";
---
```
#### Verify it works
Run `npm run dev`. On localhost the tracker itself is not loaded; the component sends one dev ping per page load so the install check can confirm the setup, and it is never counted or shown in your stats. After you deploy, follow [Verify it works](/docs/verify) to see the first real visit.
Next: [track custom events](/docs/package#track) and [type them from your goals](/docs/cli#types). Prefer no package? Put the [script tag](/docs/install) in your layout's ``.
---
# Install Satsu on SvelteKit
Source: https://satsu.pro/docs/frameworks/sveltekit
## SvelteKit
The `Satsu` component from `satsu-analytics/svelte` starts the tracker on mount. Render it once in the root layout and it follows client-side navigation.
### Setup
Skip to **Verify it works** if init finished. To do it by hand, continue with the next steps.
#### Or install the package yourself
#### Set the site ID
Create a site in the dashboard (**Sites → your site → install**) and put its ID into `.env`:
```sh
PUBLIC_SATSU_SITE=YOUR_ID
```
The component falls back to `PUBLIC_SATSU_SITE` when you don't pass `site`.
#### Add the component
In `src/routes/+layout.svelte`:
```svelte
{@render children()}
```
#### Verify it works
Run `npm run dev`. On localhost the tracker itself is not loaded; the component sends one dev ping per page load so the install check can confirm the setup, and it is never counted or shown in your stats. After you deploy, follow [Verify it works](/docs/verify) to see the first real visit.
Next: [track custom events](/docs/package#track) and [type them from your goals](/docs/cli#types). Prefer no package? Put the [script tag](/docs/install) in `src/app.html`.
---
# Install Satsu on Remix and React Router
Source: https://satsu.pro/docs/frameworks/remix
## Remix and React Router
The `` component from `satsu-analytics/remix` loads the tracker once from the browser and follows client-side navigation. It renders nothing, so it is safe during server rendering.
### Setup
Skip to **Verify it works** if init finished. To do it by hand, continue with the next steps.
#### Or install the package yourself
#### Set the site ID
Create a site in the dashboard (**Sites → your site → install**) and put its ID into `.env`:
```sh
VITE_SATSU_SITE=YOUR_ID
```
The component falls back to `VITE_SATSU_SITE` when you don't pass `site`.
#### Add the component
In `app/root.tsx`:
```tsx
import { Outlet } from "@remix-run/react";
import { Satsu } from "satsu-analytics/remix";
export default function App() {
return (
<>
>
);
}
```
On React Router v7, import `Outlet` from `react-router` instead.
#### Verify it works
Run `npm run dev`. On localhost the tracker itself is not loaded; the component sends one dev ping per page load so the install check can confirm the setup, and it is never counted or shown in your stats. After you deploy, follow [Verify it works](/docs/verify) to see the first real visit.
Next: [track custom events](/docs/package#track) and [type them from your goals](/docs/cli#types). Prefer no package? The [script tag](/docs/install) works too.
---
# Install Satsu on plain HTML
Source: https://satsu.pro/docs/frameworks/html
## Plain HTML
One script tag, no build step. Works for static sites and any server-rendered template.
### Setup
---
# Install Satsu on WordPress
Source: https://satsu.pro/docs/frameworks/wordpress
## WordPress
There is no Satsu plugin: the tracker is one script tag, and WordPress can inject it in two ways.
### Setup
---
# Install Satsu on Shopify
Source: https://satsu.pro/docs/frameworks/shopify
## Shopify
Paste the tracker into your theme's `theme.liquid` so it loads on every storefront page.
### Setup
---
# The satsu-analytics package
Source: https://satsu.pro/docs/package
## The satsu-analytics package
`satsu-analytics` is the MIT-licensed npm package that installs Satsu in your code: a component per framework, a typed `track()` for custom events, and the CLI that sets it all up. Sessions are derived from a daily-rotating fingerprint that cannot be linked across days; raw IP addresses and user agents are never written to the analytics database and pass through our message queue only until they are processed, at most 24 hours; no cookies, no persistent visitor IDs.
Or let [`init`](/docs/cli#init) do it. Per-framework walkthroughs start at [Install the tracker](/docs/install).
### Components
Each component loads the tracker once, follows client-side navigation and renders nothing. Props: `site` (the site ID) and `debug` (log instead of loading the tracker).
| Framework | Import | Guide |
|---|---|---|
| Next.js | `import { Satsu } from "satsu-analytics/next"` | [Next.js](/docs/frameworks/nextjs) |
| React (Vite) | `import { Satsu } from "satsu-analytics/react"` | [React](/docs/frameworks/react) |
| Vue 3 | `import { Satsu } from "satsu-analytics/vue"` | [Vue and Nuxt](/docs/frameworks/vue-nuxt) |
| Nuxt | `modules: ["satsu-analytics/nuxt"]` | [Vue and Nuxt](/docs/frameworks/vue-nuxt) |
| Astro | `import Satsu from "satsu-analytics/astro"` | [Astro](/docs/frameworks/astro) |
| SvelteKit | `import Satsu from "satsu-analytics/svelte"` | [SvelteKit](/docs/frameworks/sveltekit) |
| Remix / React Router | `import { Satsu } from "satsu-analytics/remix"` | [Remix](/docs/frameworks/remix) |
### Environment variables
When you don't pass `site`, the component reads the site ID from the variable of your framework:
| Framework | Variable | File |
|---|---|---|
| Next.js | `NEXT_PUBLIC_SATSU_SITE` | `.env.local` |
| React (Vite), Vue (Vite) | `VITE_SATSU_SITE` | `.env.local` |
| Remix / React Router | `VITE_SATSU_SITE` | `.env` |
| Nuxt | `NUXT_PUBLIC_SATSU_SITE` | `.env` |
| Astro, SvelteKit | `PUBLIC_SATSU_SITE` | `.env` |
The ID is public (it ends up in the page HTML). Using one variable per environment lets staging and production report to different sites without code changes.
On localhost the tracker is not loaded. The component sends one dev ping per page load so `init` can confirm the setup. It carries only the site ID and the local origin and path, and is never written to the analytics database, counted, billed or shown in your stats.
### track
`track(name, props?)` sends a [custom event](/docs/events). It queues until the tracker has loaded and is a no-op on the server. On localhost and with `debug` it only logs to the console.
```ts
import { track } from "satsu-analytics";
track("signup", { plan: "pro" });
```
Props are flat: strings, numbers and booleans.
### Typed events
Declare your event names once and `track` only accepts those, with the props you declared:
```ts
// satsu-events.d.ts
import "satsu-analytics";
declare module "satsu-analytics" {
interface Events {
signup: { plan: string };
newsletter: undefined;
}
}
```
```ts
track("signup", { plan: "pro" }); // ok
track("signup"); // type error: props missing
track("singup", { plan: "pro" }); // type error: unknown event
```
Don't want to write it by hand? [`satsu-analytics types`](/docs/cli#types) generates the file from your goals.
### Badges
Show a live uptime, accessibility or security badge that links to its public verification page. Get the slug from the badge section of your monitor or site settings.
```tsx
import { SatsuBadge } from "satsu-analytics/react";
;
```
Props: `slug`, `type` (`uptime`, `a11y` or `security`), `theme` (`light`, `dark`), `style` (`flat`, `flat-square`), `brand` (`false` hides the wordmark where your plan allows it) and `className`. For Vue, Svelte, Astro or plain HTML use the helpers, which have no DOM or framework dependency:
```ts
import { badgeUrl, badgeVerifyUrl } from "satsu-analytics";
const img = badgeUrl({ slug, type: "a11y" }); // https://satsu.pro/badge/.svg?type=a11y
const link = badgeVerifyUrl({ slug, type: "a11y" }); // https://satsu.pro/b/?type=a11y
```
Both accept `origin` to point at another host. Render the image at its fixed size: `uptime` 232, `a11y` 218, `security` 196 px wide, 22 px high.
### Related
- [CLI](/docs/cli): `init`, `login`, `logout`, `types`.
- [MCP server](/docs/mcp): ask your coding agent about your traffic.
---
# The satsu-analytics CLI
Source: https://satsu.pro/docs/cli
## The satsu-analytics CLI
The CLI ships inside the [`satsu-analytics` package](/docs/package). Run it with `npx`, `pnpm dlx`, `yarn dlx` or `bunx`; there is nothing to install globally.
### init
Detects your framework, signs you in, picks one of your sites or creates one, and wires Satsu into the project.
1. Reads `package.json` and finds your framework (Next.js, React with Vite, Vue, Nuxt, Astro, SvelteKit, Remix or React Router). For anything else it offers to pick or create a site, prints the script tag for your `` and links the matching [docs page](/docs/install).
2. Signs you in through your browser with a code shown in the terminal. Sign in or create an account in the browser.
3. Lists the sites you already have and preselects the one whose domain matches the project. Pick it, or create a new site: then it asks for the workspace (when you have several) and the production domain. The domain can stay empty and be set later; the dashboard suggests it once traffic arrives.
4. Shows the file changes and asks before writing them: the site ID goes into your env file and the component into your layout. It never overwrites an existing value without asking, and offers to replace a hand-written Satsu script tag.
5. Offers to install the package with your package manager (in a monorepo, the one whose lockfile sits at the workspace root), then waits for the local dev ping to confirm the setup.
6. Asks whether to connect your coding agent. On yes it writes the [MCP](/docs/mcp) config for Claude Code, Cursor, VS Code or Windsurf at the repository root, and prints the config for any other editor; the server uses the personal key from your sign-in.
Set the printed variable in your hosting provider's environment too; the env file stays on your machine.
If a file can't be changed safely, init prints the manual steps from your framework guide instead.
### login
```sh
npx satsu-analytics login
```
Signs you in through the browser and stores a personal key in a file in your user config directory (`~/.config/satsu-analytics/credentials.json`, under `$XDG_CONFIG_HOME` when set, or `%APPDATA%` on Windows) with owner-only permissions. The key acts as you: same workspaces, same role. Nothing secret is written into your project.
### logout
```sh
npx satsu-analytics logout
```
Removes the stored credentials from this machine. The key itself stays valid until you [revoke it](/docs/mcp#revoke-a-key).
### types
```sh
npx satsu-analytics types --site YOUR_ID
```
Writes `satsu-events.d.ts` with the names of your custom-event [goals](/docs/goals), so `track()` autocompletes and rejects typos. `--site` is optional inside a project where init saved the site ID. Props are typed as `Record`. Run it again after you add a goal. Requires `login`.
### mcp
Runs the [MCP server](/docs/mcp) over stdio. You normally don't call it yourself; your editor does.
### Environment
| Variable | Effect |
|---|---|
| `SATSU_API_URL` | Overrides the API base URL (default `https://api.satsu.pro`). |
Sessions are derived from a daily-rotating fingerprint that cannot be linked across days; raw IP addresses and user agents are never written to the analytics database and pass through our message queue only until they are processed, at most 24 hours; no cookies, no persistent visitor IDs. The sign-in sends your computer's hostname as the key's label; later calls send the site and goal data you ask for.
---
# The Satsu MCP server
Source: https://satsu.pro/docs/mcp
## The Satsu MCP server
The MCP server lets Claude Code, Cursor, VS Code, Windsurf and other MCP clients read your Satsu numbers and take a few safe actions. It runs locally through the package and talks to the [public API](/docs/api) with your personal key.
The analytics tools return aggregated numbers only, never data about individual visitors. Sessions are derived from a daily-rotating fingerprint that cannot be linked across days; raw IP addresses and user agents are never written to the analytics database and pass through our message queue only until they are processed, at most 24 hours; no cookies, no persistent visitor IDs.
### Setup
The easiest way: run [`init`](/docs/cli#init) and answer yes to "Connect your coding agent?". Or sign in and add the server yourself.
#### Add the server to your editor
The entry runs `npx -y satsu-analytics mcp`. The key is read from your user config, so the file is safe to commit and a teammate signs in on their own machine.
Any other MCP client takes the same command: `npx -y satsu-analytics mcp`.
#### Ask
Restart the editor, then try "How many visitors did my site have last week?".
### Tools per plan
The MCP is on every plan. A tool your plan doesn't include answers "available on Pro" with an upgrade link instead of failing.
| Tool | What it does | Plan |
|---|---|---|
| `list_sites` | Your sites with ID, name and domain | All |
| `traffic_summary` | Visitors and pageviews over a period (Free: within your plan's retention, 3 months) | All |
| `top_pages`, `top_sources` | Most viewed pages and top referrers | All |
| `breakdown` | One dimension at a time; pages and referrers on every plan, the rest on Pro | All / Pro |
| `goals` | Goals with IDs, names and rules | All |
| `ai_traffic` | Visits from AI assistants such as ChatGPT or Perplexity | Pro |
| `goal_conversions` | Conversions of one goal | Pro |
| `live_visitors` | Visitors on the site right now, as a count | Pro |
| `uptime_status` | Monitors with status and TLS state | Pro |
| `audit_results` | Latest result per audit pillar | Pro |
### Actions
Actions run immediately, within your plan limits and your own role in the workspace. A read-only member can read but not act. There are no deletes, archives or billing actions.
Everything an agent creates is marked "created by agent" in the site, goal and monitor lists, and each key lists its latest actions under **API keys** in the dashboard.
| Tool | What it does | Plan |
|---|---|---|
| `create_site` | Create a site in a workspace | All |
| `set_site_domain` | Set the production domain; audits and monitors need it | All |
| `create_goal` | Create a `custom_event` or `path` goal | All |
| `update_goal` | Rename a goal or change its rule | All |
| `start_audit` | Start an audit now (the site needs a domain) | Pro |
| `create_monitor` | Create an uptime monitor | Pro |
### Revoke a key
Keys act as the user who created them. To cut an agent off, open **API keys** in the dashboard, find the key and revoke it. The next request from that machine fails until you run `login` again. `logout` only removes the key from your machine; revoke it in the dashboard to invalidate it.
---
# Custom events
Source: https://satsu.pro/docs/events
## Custom events
Beyond pageviews, you can record any action that matters — a signup, a checkout,
a button click. The tracker exposes one global function:
```js
window.satsu(name, props?);
```
- **`name`** — a string naming the event (e.g. `"signup"`). Truncated to 128
characters.
- **`props`** *(optional)* — a flat object of extra data. Values may be strings,
numbers or booleans.
### Examples
A simple event:
```js
window.satsu("signup");
```
An event with properties:
```js
window.satsu("signup", { plan: "pro", referrer: "changelog" });
```
Wire it to a click:
```html
```
Or in a framework, call it from your handler:
```tsx
function CheckoutButton() {
return (
);
}
```
### TypeScript
The tracker attaches `satsu` to `window` at runtime. Declare it once so
TypeScript knows the signature:
```ts
// satsu.d.ts
declare global {
interface Window {
satsu: (name: string, props?: Record) => void;
}
}
export {};
```
### Rules and limits
- **Keep props flat.** Nested objects and arrays aren't supported — one level of
string / number / boolean values. The whole props payload is capped at ~2 KB.
- **Never put personal data in props.** No emails, names, user IDs or anything
that identifies a person. Satsu does not scan or filter props, so anything you
send is stored. Use props for context (`plan`, `variant`, `source`), not
identity.
- **Events count toward your plan's monthly event limit** — pageviews, custom
events and the automatic Outbound Link, File Download and Scroll Depth events
count; heartbeats and Web Vitals never do. The limit is soft: nothing is
dropped.
- **Calls before the tracker loads are safe to guard.** If you might fire an event
before the script has run, check first: `window.satsu?.("event")`.
### Turning events into conversions
A custom event on its own is a raw signal. To measure it as a conversion — with a
conversion rate and breakdowns — create a goal that matches its name. See
[Goals & conversions](/docs/goals).
### Reserved events
Four event names are produced automatically by the tracker: **Outbound Link**,
**File Download**, **Scroll Depth** and **Web Vitals**. You don't fire these
yourself — they appear in your dashboard without any code. Avoid
reusing these exact names for your own events.
Next: [Goals & conversions →](/docs/goals)
---
# Goals & conversions
Source: https://satsu.pro/docs/goals
## Goals & conversions
A goal turns a raw signal — a custom event or a pageview on a specific path —
into a measured **conversion**, with a conversion rate and breakdowns by source,
country, device and more.
Goals are created per site in the dashboard (**your site → Goals**). Each goal has
a **name**, a **type**, and a **matcher**.
### Goal types
There are two types.
#### Custom-event goals
Match a [custom event](/docs/events) by its exact name. Fire the event once from
your code, then create a goal whose matcher is that name.
| Field | Value |
|---|---|
| Type | `custom_event` |
| Matcher | The event name, e.g. `signup` |
A session that fires `window.satsu("signup")` at least once counts as one
conversion.
#### Path goals
Match a **pageview** by its path — no code required. Useful for "reached the
thank-you page" style goals.
| Field | Value |
|---|---|
| Type | `path` |
| Matcher | A path starting with `/`, e.g. `/welcome` |
Path matchers support a single trailing wildcard: `/blog/*` matches any path that
starts with `/blog/`. There are no other patterns — no regex, no mid-string
globs. A matcher without a `*` must match the path exactly.
### How conversions are counted
- A **conversion** is a unique session that satisfies the goal **at least once**.
Firing the same event twice in a session is still one conversion.
- The **conversion rate** is converting sessions ÷ total sessions in the selected
period.
- **Breakdowns** attribute each converting session to its **first-touch** value —
the source, campaign, country or device the session started with. This matches
how channel attribution works elsewhere in Satsu.
Rename a goal or change its matcher at any time in the dashboard, the iOS app or through your agent; past conversions are recomputed because goals are evaluated at query time.
Goals are evaluated at query time against your existing events. Creating a goal
works retroactively: it measures conversions from data you've already collected,
not just from the moment you add it.
### Plan limits
The number of goals per site depends on your plan. When you hit the limit,
upgrade for more (or unlimited on higher tiers). Deleting a goal frees a slot.
Next: [What we track →](/docs/what-we-track)
---
# What we track
Source: https://satsu.pro/docs/what-we-track
## What we track
Satsu is built to answer "how is my site doing?" without answering "who is this
person?". This page is the exact list of what's collected, what's derived, and
what we refuse to touch. It doubles as the source for our privacy documentation.
### Collected by the tracker (client-side)
The tracker ships only raw signals; all intelligence lives server-side. It sends:
- **Pageviews** — the path, the referrer, and your screen width. The page path is
stored without its query string, and only the origin and path of the referrer
are stored; UTM parameters are extracted server-side.
- **Custom events** — the name and flat props you pass to
[`window.satsu()`](/docs/events). Don't put personal data in props: Satsu does
not scan or filter them, so anything you send is stored.
- **Presence heartbeats** — a lightweight "still here" ping while the tab is
visible. Used only for the live count. **Never stored, never billed.**
- **Local dev ping** — on localhost the [package components](/docs/package) send
one ping per page load (site ID and local page path) so the install check can
confirm setup. It is never written to the analytics database, counted or billed.
- **UTM parameters** — `utm_source`, `utm_medium`, `utm_campaign`, parsed from the
URL server-side.
- **Ad click-id presence** — the *name* of a click-id parameter (e.g. `gclid`,
`fbclid`) if present. The **value is never stored** — only that one was there.
- **SPA route changes** — automatic pageviews on client-side navigation.
- **Outbound link clicks** — the destination URL, with query and hash stripped.
- **File downloads** — clicks on common file types or `download` links.
- **Scroll depth** — how far down a page a visit reached (25 / 50 / 75 / 100 %),
once per pageview.
- **Web Vitals** — LCP, CLS, INP and TTFB once per page load (not billed).
With each request the server also records the browser's **fetch-site header**:
whether the visit came from the same site, another site or none (used to spot
stripped referrers).
### Derived server-side
From those raw signals, Satsu derives the following at processing or query time;
none of it is linked to a person or carried across days:
- **Country** — from the IP, at country level only. The IP is not stored in the
analytics database; it passes through our message queue only until the event is
processed, at most 24 hours.
- **Browser, OS and device class** — from the user-agent string.
- **Bot filtering** — obvious bots are dropped. Known AI crawlers that fetch the
tracker are counted separately (bot name and site only, no IP).
- **Session metrics** — bounce rate, visit duration, pages per visit — computed
from the daily-rotating fingerprint.
- **Channel** — Direct, Organic Search, Social, Referral, Paid, Email or AI —
classified at query time, not stored.
- **Goal conversions** — matched at query time against your goals.
The session key that ties a visit together is a **daily fingerprint**, not a
cookie. The session ID stored with each event is a one-way hash that changes
every UTC day. See [How it's private](/docs/privacy) for exactly how
it works.
### Deliberately not tracked
The following are refused by design — not a roadmap gap, a decision:
- **Session recordings**, mouse movement, or individual heatmaps.
- **Persistent identifiers of any kind** — no cookies, no localStorage IDs, no
cross-day fingerprints.
- **Reverse-IP company lookup** ("which company visited").
- **Anything that, in our assessment, would require a consent banner.**
### By design: what Satsu can't tell you
Because the fingerprint changes at 00:00 UTC, Satsu **cannot** track a returning
visitor across days, build a retention cohort, or follow one person's journey
over time. That limit is the point — it's why, in our assessment, no consent
banner is needed. Geography is country-level only, for the same reason.
Next: [How it's private →](/docs/privacy)
---
# How it's private
Source: https://satsu.pro/docs/privacy
## How it's private
Most analytics tools need a consent banner because they set a cookie or store a
persistent identifier on the visitor's device. Satsu does neither. This page
explains the mechanism behind "no cookie banner", including where it has edges.
### No cookies, no stored IDs
Satsu never writes a cookie, never uses `localStorage` for identity, and never
assigns a persistent visitor ID. Satsu sets nothing on the device and stores no
identifier there; the only read is the optional `satsu_ignore`
[opt-out flag](/docs/verify). The session ID stored with each event is a one-way
hash that changes every UTC day.
### Sessions are derived from a daily fingerprint
To group a visit's pageviews together — to know that three pageviews came from the
same session — Satsu derives a short-lived fingerprint on the server:
```
session = sha256(site · ip · user-agent · day · salt)
```
The components are hashed together (NUL-separated) into a single opaque value:
```
sha256("site_id" | "203.0.113.7" | "Mozilla/5.0 …" | "2026-07-14" | secret_salt)
→ 9f2c... (a one-way hash)
```
A few things make this safe:
- **It's one-way.** SHA-256 can't be reversed. The stored value can't be turned
back into an IP or user-agent.
- **The raw IP and user-agent are never written to the analytics database.** They
pass through our message queue only until they are processed, at most 24 hours.
- **It includes the day.** Because `day` (`YYYY-MM-DD`, UTC) is part of the input,
the fingerprint **changes at 00:00 UTC**. Tomorrow the same visitor produces a
completely different hash — there's no way to connect the two.
- **The secret rotates daily, too.** The `salt` is 32 random bytes created fresh
for every UTC day. It is kept in a short-lived cache only — never in the
analytics database or in logs — and is **deleted after about 48 hours**. From
then on nobody, including us, can recompute that day's fingerprints, even with
a known IP address and user-agent.
### Why the daily rotation matters
The daily rotation is the core design decision. It means Satsu **cannot** build a
profile that follows someone across days or sites. No retention cohorts, no
cross-day journeys, no "returning visitor" tracking spanning weeks. That's a
deliberate limit, and it's why, in our assessment, Satsu works without a consent
banner: there's no durable identifier to consent to.
### Heartbeats are presence-only
The live visitor count comes from presence entries: a session hash and the
current path, kept in a short-lived cache. A visitor counts as live for 60
seconds after their last pageview, event or heartbeat, and the entries expire
within ten minutes. Heartbeats are never written to the analytics store and never
counted against your plan; they exist only to power the real-time "who's here
now" number.
### What this means for compliance
Built for GDPR. No cookies and no persistent identifiers, so in our assessment no
consent banner is needed; check with your own counsel for your site.
- **Analytics database** — no IP addresses, no user-agents, no identifiers that
survive the day. The IP address is processed briefly on our servers to derive
the daily fingerprint and the country.
- **Visitor's device** — Satsu sets nothing on the device and stores no identifier
there; the only read is the optional `satsu_ignore` opt-out flag.
We're happy to provide a Data Processing Agreement (DPA) for business customers —
email [hello@satsu.pro](mailto:hello@satsu.pro).
### The site check
{CHECK_RETENTION_SENTENCE}
While you try the check, the domain you entered stays in your own browser tab
(`sessionStorage`) only until the site is created after signup. It is never sent
to us for storage, and "no `localStorage` IDs" still holds.
Two more per-tab `sessionStorage` entries sit next to `satsu.check.domain`:
`satsu.check.via` (which page linked you to the check) and `satsu.check.ran`
(a check finished in this tab). Neither holds an identifier, and the only values
ever sent are from a closed list of page names, never an address. When you
register, `satsu.check.ran` is read once to send `signup_completed` with a
yes/no `after_check` flag, and nothing else.
### The honest caveats
We'd rather tell you the edges than oversell:
- The daily secret exists for **about 48 hours**, not 24: events that arrive
shortly after midnight still need the secret of the day they belong to. Until
it is deleted, someone holding both the secret and a visitor's exact IP address
and user-agent could recompute that day's fingerprint. The IP and user-agent are
never written to the analytics database; they pass through our message queue
only until they are processed, at most 24 hours.
- Country is derived from the IP at the **country level** only. The derivation
reads the IP from the queued event; the analytics database stores the country,
never the IP.
None of this changes the core design: no cookies, no persistent IDs, no
identifier that survives the day.
See also: [What we track](/docs/what-we-track) for the full field-by-field list.
---
# Performance audit
Source: https://satsu.pro/docs/audits/performance
## Performance audit
Satsu measures site speed twice, because the two answers are different questions:
- **The performance audit** runs [Lighthouse](/docs/glossary#lighthouse) against your pages in a
controlled lab environment, on a schedule. Same device profile, same network, every run —
so two runs are comparable and a fix is provable.
- **Web Vitals** collects [field data](/docs/glossary#field-data) from your real visitors,
anonymously and cookieless. That's the experience search rankings are judged on.
Rule of thumb: diagnose and verify fixes in the lab; judge reality in the field.
### The score
The [Lighthouse score](/docs/glossary#lighthouse-score) condenses the lab metrics into one
weighted 0–100 number — the same grade Chrome DevTools and PageSpeed Insights report.
90+ counts as fast, 50–89 needs work, below 50 is slow. A failing Core Web Vital forces the
grade down regardless of the score: a site that misses the thresholds real rankings use
should not look healthy.
### The metrics
The three [Core Web Vitals](/docs/glossary#web-vitals) carry the most weight:
- [LCP — Largest Contentful Paint](/docs/glossary#lcp): how long until the main content is
visible. Good under 2.5 s.
- [CLS — Cumulative Layout Shift](/docs/glossary#cls): how much the layout jumps while
loading. Good under 0.1.
- [INP — Interaction to Next Paint](/docs/glossary#inp): how fast the page reacts to input.
Good under 200 ms. In the lab, [TBT](/docs/glossary#tbt) stands in for it, since a lab run
has no real interactions.
The remaining lab diagnostics — [FCP](/docs/glossary#fcp), [Speed Index](/docs/glossary#speed_index),
[TTI](/docs/glossary#tti), [TTFB](/docs/glossary#ttfb) — locate *where* the time goes:
server, render path, or JavaScript.
### Reading the opportunity list
Findings are ranked by estimated savings, worst first. The estimates come from Lighthouse's
own model — treat them as direction, not promise. The audit report is Markdown on purpose:
copy it into an AI coding assistant and it can act on every finding directly.
### Why field numbers differ from lab numbers
Lab runs use a fixed mid-range device on a throttled connection. Your real audience might be
faster (desktop-heavy B2B) or slower (mobile-heavy consumer traffic) — so the field
[p75](/docs/glossary#p75) can sit well above or below the lab value for the same page. Both
are true; they answer different questions.
---
# Accessibility audit
Source: https://satsu.pro/docs/audits/accessibility
## Accessibility audit
Satsu renders your pages in a real browser and checks each one with
[axe-core](/docs/glossary#axe-core), the engine behind most accessibility tooling. The result
leads with the verdict that matters legally: does the page pass or fail
[WCAG 2.1 AA](/docs/glossary#wcag-aa)?
### Why AA, and why now
The Web Content Accessibility Guidelines define three conformance levels — A, AA, AAA.
**Level AA is the bar laws reference**: the European Accessibility Act, implemented in Germany
as the BFSG, has applied to most consumer-facing digital services since June 2025. An
inaccessible shop or booking flow is no longer just bad UX — it's a compliance issue with
warning-letter exposure.
### The four principles
WCAG groups every criterion under four principles; the audit scores each separately so you
see where the weight is:
- [Perceivable](/docs/glossary#perceivable) — can everyone perceive the content? Alt text,
contrast, captions.
- [Operable](/docs/glossary#operable) — does everything work without a mouse? Keyboard
access, visible focus.
- [Understandable](/docs/glossary#understandable) — labeled forms, declared language, clear
errors.
- [Robust](/docs/glossary#robust) — valid markup that assistive technology can interpret.
### What automated checks can and cannot prove
axe-core is conservative by design: what it flags is virtually always a real defect, and
every finding carries the WCAG criterion, the CSS selector and a code snippet — enough for
an AI assistant to fix the exact element. But roughly half of WCAG's criteria need human
judgment (is the alt text *meaningful*? does the focus order make *sense*?). A green
automated run is necessary, not sufficient; treat it as the floor, and sample critical flows
manually.
### Reading the result
Any violated A or AA rule fails the verdict; critical and serious ones also cap the grade at
poor. The severity groups order the work:
fix critical and serious first — they block real users — then work down. Scores are per
page and aggregate; a single inaccessible template usually accounts for most instances, so
one fix often clears dozens of findings.
---
# GDPR audit
Source: https://satsu.pro/docs/audits/gdpr
## GDPR audit
Satsu renders your pages the way a first-time visitor sees them — **without touching any
consent banner** — and records what actually happens: which scripts load, which cookies get
set, where requests go. That's the standard regulators and warning-letter firms apply, and
it routinely contradicts what site owners *believe* their consent setup does.
Everything below is guidance, not legal advice.
### What the categories mean
- **[Trackers](/docs/glossary#trackers)** — third-party scripts (ad pixels, analytics,
social embeds) that process visitor data. Under the GDPR they need informed consent
*before* they load. A tracker firing pre-consent is the classic violation.
- **[Cookies](/docs/glossary#cookies)** — § 25 TDDDG (the German implementation of the
ePrivacy rules, formerly § 25 TTDSG) requires consent for any non-essential access to the
visitor's device. The audit lists every non-essential cookie set before consent.
- **[Fonts](/docs/glossary#fonts)** — webfonts loaded from third-party servers send every
visitor's IP address there. The Munich Regional Court (LG München I, 3 O 17493/20) ruled
in 2022 that a Google Fonts load from US servers is an actionable violation — and awarded
damages. Self-hosting closes the issue mechanically.
- **[Data transfer](/docs/glossary#data-transfer)** — since the CJEU's *Schrems II* judgment
(C-311/18), transfers to US servers need a valid legal basis; the successor framework
remains under legal challenge. The audit flags requests to servers in the USA so you know
your exposure.
- **[Transparency](/docs/glossary#transparency)** — a reachable privacy policy is a GDPR
requirement; German-market sites additionally need an imprint (Impressum, § 5 DDG,
formerly TMG). Both are trivially machine-detectable, which makes missing ones a favorite
target for automated warning letters.
### How to read the risk rating
Critical findings are pre-consent cookies, external Google Fonts and a missing imprint;
third-party trackers are reported as warnings. Fix the critical ones first — each finding carries a concrete fix,
and most are config-level: self-host the font, gate the script behind consent, add the
missing legal page.
### Where Satsu itself stands
Satsu's own tracking is cookieless by design — [sessions](/docs/glossary#sessions) derive
from a fingerprint that changes at 00:00 UTC and cannot be linked across days, and Satsu sets
nothing on the device and stores no identifier there (the only read is the optional
`satsu_ignore` opt-out flag). In our assessment Satsu needs no consent banner entry; check
with your own counsel for your site. The full story is in
[How it's private](/docs/privacy).
---
# Security audit
Source: https://satsu.pro/docs/audits/security
## Security audit
Satsu checks the security posture a browser can see — the same surface attackers scan
first, because it's fully automated and reveals soft targets. Everything the audit finds is
**config-level fixable**: headers, flags, and serving rules, not code rewrites.
### The categories
- **[Headers](/docs/glossary#security-headers)** — response headers that switch on
browser-side protections. The ones that matter most:
`Content-Security-Policy` (the main defense against XSS and injected scripts),
`X-Frame-Options` / `frame-ancestors` (clickjacking),
`X-Content-Type-Options: nosniff` (MIME confusion),
`Referrer-Policy` and `Permissions-Policy` (data and capability leakage).
- **[Transport](/docs/glossary#transport-security)** — HTTPS done right: every page
encrypted, `http://` redirecting, and `Strict-Transport-Security` (HSTS) so browsers never
try plain HTTP again. Without HSTS, a visitor's *first* request on hostile Wi-Fi can be
intercepted before the redirect happens — one header closes that window.
- **[Cookies](/docs/glossary#cookie-security)** — session cookies need three flags:
`Secure` (never sent over plain HTTP), `HttpOnly` (invisible to JavaScript, so XSS can't
steal sessions), `SameSite` (limits cross-site sending, the CSRF vector). Missing flags
are added in one line of server config.
- **[Content](/docs/glossary#mixed-content)** — mixed content: an HTTPS page loading some
resource over plain `http://`. Browsers block the worst cases and quietly downgrade trust
for the rest; anything unencrypted can be tampered with in transit.
- **[Disclosure](/docs/glossary#disclosure)** — version numbers in the `Server` header and an
`X-Powered-By` header. Not exploits themselves, but they tell attackers exactly which known
vulnerabilities to try. Strip them.
### How to read the score
Critical findings (no HTTPS redirect, missing HSTS, invalid TLS chain) are the ones worth
same-day fixes. The warning tier is dominated by absent headers — each finding names the
exact header and value to add, so the report pastes straight into a server config or an AI
assistant.
---
# SEO audit
Source: https://satsu.pro/docs/audits/seo
## SEO audit
Satsu crawls your site the way a search engine does — following links, reading robots rules
and sitemaps — and checks the pages it reaches, up to your plan's page limit (50 on Pro, 250
on Business). The audit covers the machine-checkable
layer of SEO: the structural problems that silently cost rankings no matter how good the
content is.
### The categories
- **[On-page](/docs/glossary#on-page)** — the signals each page sends: unique titles and
meta descriptions, exactly one H1, canonical URLs, structured data. Fully under your
control and the cheapest wins in SEO.
- **[Crawlability](/docs/glossary#crawlability)** — everything that decides whether a page
gets reached and indexed at all: robots.txt rules, sitemap coverage, redirect chains,
stray `noindex` flags. A page that can't be crawled can't rank, and nothing about that is
visible in the browser.
- **[Links](/docs/glossary#link-health)** — broken internal links (critical: they leak
ranking signal and strand visitors), dead external references, and long redirect chains
that burn crawl budget.
- **[Performance](/docs/glossary#seo-performance)** — the page-weight basics search engines
factor in: oversized HTML, missing compression, render-blocking assets. For how fast pages
*actually load*, see the [performance audit](/docs/audits/performance) — this category
catches the structural part.
### How to read the result
The same issue on many pages collapses into one finding with the affected URLs underneath —
a 250-page crawl produces a to-do list, not 250 rows. Critical findings first: they're the
ones with direct ranking impact. The report is Markdown built for pasting into an AI
assistant; "add a canonical to /docs" is something it can just do.
### Rankings are moving into AI answers
Classic SEO gets you into search results; increasingly the same structural quality decides
whether AI assistants can read, quote and recommend you. That side has its own tooling in
Satsu — see [the AI suite](/docs/ai-suite).
---
# The AI suite
Source: https://satsu.pro/docs/ai-suite
## The AI suite
People increasingly find products by asking an assistant, not by searching. The AI suite
measures that funnel end to end: whether AI systems **read** your site, whether they
**recommend** it, and whether they **send** you actual visitors.
### AI traffic — the visits
[AI traffic](/docs/glossary#ai-traffic) counts arrivals from AI assistants, per assistant.
Two derived numbers add context:
- **[AI-influenced](/docs/glossary#ai-influenced)** — the share of sessions with at least
one AI arrival, including visits that started elsewhere. Reach, not attribution.
- **[Hidden external](/docs/glossary#hidden-external)** — arrivals from another site whose
referrer the browser stripped. The `Sec-Fetch-Site` header still proves a cross-site
arrival, so Satsu surfaces these server-side instead of burying them in Direct. A large
share is typically stripped AI referrals.
### AI crawlers — the reads
[AI crawlers](/docs/glossary#ai-crawlers) records AI bots observed loading your tracker,
split by intent: [live fetches](/docs/glossary#live-fetches) (a human asked, the assistant
pulled the page to answer — the strongest signal) and
[bulk crawlers](/docs/glossary#bulk-crawlers) (training and index sweeps).
This is deliberately framed as a **sampled signal**: AI bots don't execute scripts and fetch
inconsistently, so the true crawl volume is higher and a zero proves nothing. An honest
undercount beats a precise-looking number nobody can stand behind.
### AI citations — the recommendations
[Citation monitoring](/docs/glossary#ai-citations) asks the assistants the questions your
customers would ask and records the verdict per prompt: **cited** (your URL linked),
**mentioned** (named, not linked), or **absent** — plus who was named instead. Positive
verdicts store the assistant's actual wording as a receipt.
[Visibility](/docs/glossary#visibility-score) is the trend number: the share of checks that
name you at all.
### Why this loops back to your content
Assistants cite sources that are crawlable, well-structured and quotable — the same
qualities the [SEO audit](/docs/audits/seo) checks. These docs practice what they preach:
every term on this page has a stable, self-contained definition in the
[glossary](/docs/glossary) that an assistant can lift verbatim.
---
# Glossary
Source: https://satsu.pro/docs/glossary
## Web analytics
### Sessions
A session groups the pageviews of one visit. Instead of a cookie or stored ID, Satsu derives a fingerprint on the server from the site, the visitor's IP, their browser, and the day — and that fingerprint changes at 00:00 UTC. Nothing identifying is ever stored on the device, and a returning visitor tomorrow is a new visitor by design. This is why, in our assessment, Satsu needs no cookie banner.
### Visitors
Visitors counts unique daily fingerprints, an approximation of unique people, derived from the same fingerprint as sessions. Within one day, repeat visits from the same network and browser count once; because the fingerprint changes at 00:00 UTC, the same person tomorrow counts as new. Slightly higher visitor counts than cookie-based tools are expected — that's the privacy trade, not a bug.
### Pageviews
Pageviews count every page load, including repeat views of the same page. The ratio of pageviews to visitors is a quick read on depth: close to 1 means people leave after one page; higher means they move through the site.
### Bounce rate
The share of sessions with exactly one pageview. A high bounce rate isn't automatically bad — a blog post can answer the question on the first page — but on landing and product pages it usually means the page didn't match what the visitor came for.
### Visit duration
The average time between the first and last signal of each session. It's measured from real activity, not an idle timer — a tab left open in the background doesn't inflate it. Single-page visits with no further signals contribute zero, so this number reads best together with bounce rate.
### Custom events
Custom events are the actions you decide to measure — signups, purchases, plan upgrades — fired with a single call to the tracker. They carry a name and optional properties. Don't put personal data in them. Goals build on them: define a goal on an event name and conversion tracking comes for free.
### Sources
Sources shows where visits come from, two ways. Channels group arrivals by kind — search engines, AI assistants, social, referral links, and Direct for visits with no referrer information at all. Referrers name the exact sites that linked to you. AI is its own channel because assistant traffic behaves differently — and clicking any row filters the whole dashboard.
### Live
Live shows visitors active in the last minute, based on lightweight heartbeats the tracker sends while a page is open. Presence is held in Redis and drops out after 60 seconds without a heartbeat — it is never written to the analytics store and never counts against your event quota.
### Engagement
Engagement captures the click signals the tracker sees on the way out: outbound clicks on links to other sites, and downloads of files like PDFs or archives. Both are ranked by target so you see which external links and files actually get used — no setup required.
### Scroll depth
Scroll depth shows the share of pageviews that reached 25, 50, 75 and 100% of the page. It's the honest counterpart to visit duration: time on page can't tell whether anyone read past the fold. A steep drop before 50% on a long page usually means the opening doesn't carry.
## AI suite
### AI traffic
AI traffic measures how AI assistants send people to your site: which assistants (ChatGPT, Claude, Perplexity, …) referred how many visitors, what share of all sessions had at least one AI touch, and the external clicks whose source the browser hid. Assistant answers are becoming a first-class acquisition channel — this tile is where you see whether that's happening to you.
### AI-influenced
A session counts as AI-influenced when at least one of its arrivals came from an AI assistant — including visits that started elsewhere and returned via an assistant later. It's a reach measure, deliberately wider than the AI channel's first-source count: it answers how much of your traffic AI touches at all.
### Hidden external
Some visits arrive from another site but carry no referrer, because the browser or the linking app stripped it. The browser's Sec-Fetch headers still prove a cross-site arrival, so Satsu counts these server-side instead of burying them in Direct. A large share here is typically stripped AI-assistant referrals.
### AI crawlers
Counts AI bots observed loading your tracker: live fetches, where an assistant pulls a page because a human just asked, and bulk crawlers sweeping for training or search indexes. It's deliberately framed as a sampled signal — AI bots don't execute scripts and fetch inconsistently, so real crawling is higher and a zero proves nothing.
### Live fetches
Live fetches come from the assistants' user-triggered bots (ChatGPT-User, Claude-User, …): a real person asked something and the assistant fetched your page to answer. That makes them the most valuable crawl signal — your content is being read into live AI answers, moments before a human sees them.
### Crawlers
Bulk crawlers (GPTBot, ClaudeBot, PerplexityBot, …) sweep sites to build training data and assistant search indexes. They don't mean a human saw your content — but being crawled is the precondition for showing up in AI answers later. Robots.txt controls which of them you allow.
### AI citations
Citation monitoring asks the assistants the questions your customers would ask, then records the verdict per prompt: cited (your URL linked), mentioned (named but not linked), or absent. Each positive verdict stores the assistant's actual wording as proof. Ranking in AI answers is the new page one — this tells you whether you're on it.
### Visibility
Visibility is the share of all citation checks in which an assistant names your site, whether cited with a link or merely mentioned. It's the one-number trend to watch: rising visibility means assistants increasingly carry you in their answers; the per-prompt verdicts below show exactly where you're absent.
## Performance & Core Web Vitals
### Core Web Vitals
Core Web Vitals are the industry-standard metrics for real-user experience: LCP for loading, INP for responsiveness, and CLS for visual stability. Search engines use the field data — real visitors, not lab tests — as a ranking signal. Satsu collects them anonymously from your actual traffic. These approximate the Core Web Vitals search engines judge; Satsu measures CLS and INP in a simplified way, so values can differ from Google's.
### Performance audit
Runs Lighthouse, the open-source page-speed tool, against your pages in a controlled lab environment and grades speed on a 0–100 score, with the biggest fix opportunities ranked by estimated savings. Lab conditions are reproducible, which makes them ideal for before/after comparisons — the Web Vitals tab shows what real visitors experience. 90 and above counts as fast.
### Lighthouse
Lighthouse is the open-source auditing engine that powers most page-speed tools, including Chrome DevTools and PageSpeed Insights. It loads each page in a controlled browser, measures the lab metrics, and turns them into the 0–100 performance score. Satsu runs it against your pages on a schedule so regressions surface without anyone remembering to test.
### Lighthouse score
The Lighthouse performance score condenses lab metrics — LCP, TBT, CLS, FCP and Speed Index among them — into one weighted 0–100 number, the same grade Chrome DevTools and PageSpeed Insights report. 90 and above counts as fast, 50–89 as needs work, below 50 as slow. Treat it as a compass, not a target: fixing the listed opportunities is what moves it.
### Lab data
Lab data comes from loading your pages in a controlled environment with a fixed device and network profile. Because conditions never change, two runs are comparable — perfect for checking whether a fix worked. What it can't tell you is how real visitors experience the site; that's field data, on the Web Vitals tab.
### Field data
Field data is collected from real visits: actual devices, networks, and behavior. It's the ground truth for user experience and the data search rankings judge Core Web Vitals on. The trade-off is noise — traffic mix shifts move the numbers — which is why lab data exists for controlled comparisons. Satsu collects field data anonymously, without cookies.
### p75
A p75 value means 75% of visits were at least this fast — the same statistic Core Web Vitals ratings are based on. It is deliberately stricter than an average: a handful of fast visits can't mask many slow ones, and a single outlier can't ruin the number either.
### Largest Contentful Paint (LCP)
Largest Contentful Paint measures how long the biggest visible element — usually a hero image or headline — takes to appear after navigation. It is one of the Core Web Vitals and a search ranking signal: under 2.5 s counts as good, above 4 s as poor. Slow LCP usually points to a slow server, render-blocking assets, or oversized images.
### Interaction to Next Paint (INP)
Interaction to Next Paint measures the delay between a user interaction — a click, tap, or key press — and the next visual update. It replaced First Input Delay as a Core Web Vital in 2024: under 200 ms counts as good, above 500 ms as poor. High INP means long JavaScript tasks block the main thread; in lab audits, where no real interactions exist, TBT stands in for it.
### Cumulative Layout Shift (CLS)
Cumulative Layout Shift scores how much visible content unexpectedly moves while the page loads — the effect that makes you click the wrong button. It is a Core Web Vital: under 0.1 counts as good, above 0.25 as poor. Common causes are images without dimensions, injected banners, and late-loading fonts.
### Time to First Byte (TTFB)
Time to First Byte measures the time from requesting a page to the first byte of the response arriving — network plus server processing. It caps every other speed metric, since nothing can render before the first byte. Under 800 ms counts as good, above 1.8 s as poor; high TTFB points to a slow backend, missing caching, or distant servers.
### Total Blocking Time (TBT)
Total Blocking Time sums every stretch during load in which JavaScript occupies the main thread long enough (50 ms or more) that the page can't respond to input. It is the lab proxy for real-user responsiveness (INP), because a lab run has no real interactions. Splitting bundles and deferring non-critical scripts brings it down.
### First Contentful Paint (FCP)
First Contentful Paint measures when the first text or image renders — the moment the visitor sees the page is alive. It usually moves together with LCP; a large gap between the two means the shell renders fast but the main content lags. Render-blocking CSS and slow servers are the usual suspects.
### Speed Index
Speed Index scores how quickly the visible part of the page becomes complete during load, computed from a video capture of the render. Unlike single-moment metrics such as FCP or LCP it captures the whole loading progression: content that pops in late anywhere above the fold pushes it up. Lower is better.
### Time to Interactive (TTI)
Time to Interactive marks the point at which the page has rendered its main content and the main thread has been quiet long enough to reliably handle input. A large gap between FCP and TTI means visitors see a page that looks ready but doesn't respond yet — usually the cost of heavy JavaScript.
## Accessibility
### Accessibility audit
Renders your pages in a real browser and runs the axe-core engine against each one, checking the machine-testable WCAG 2.1 AA criteria — the standard accessibility laws like the European Accessibility Act (BFSG) reference. The verdict is the legal headline; the issue list tells you exactly which elements to fix. Automated checks cover a large share of real-world barriers, but full conformance also needs manual review.
### WCAG 2.1 AA
The Web Content Accessibility Guidelines define how websites must work for people with disabilities; level AA is the bar referenced by most accessibility laws, including the European Accessibility Act (in Germany: BFSG), in force since June 2025. Satsu checks the machine-testable AA criteria with the axe-core engine. A pass covers the automatable part — full conformance also needs manual review.
### axe-core
axe-core is the most widely used open-source accessibility testing engine; browser devtools and most a11y tools build on it. It inspects the rendered page — not just the HTML source — and reports violations mapped to WCAG criteria with the exact element selector. Its results are conservative by design: what it flags is virtually always a real defect.
### Perceivable
One of the four WCAG principles: information must be presentable in ways all users can perceive. Typical failures are images without alt text, low-contrast text, and media without captions — barriers for visitors using screen readers or with low vision.
### Operable
One of the four WCAG principles: every function must work without a mouse. Typical failures are controls that can't be reached by keyboard, missing focus indicators, and content that traps focus — barriers for visitors with motor impairments, and an annoyance for power users.
### Understandable
One of the four WCAG principles: content and controls must behave predictably. Typical failures are form fields without labels, a missing page language (screen readers mispronounce everything), and error messages that don't say what went wrong or how to fix it.
### Robust
One of the four WCAG principles: markup must be sound enough for assistive technologies to interpret. Typical failures are invalid ARIA attributes, duplicate IDs, and custom widgets that don't expose a name, role, or value to screen readers.
## Audit changes
### Since last scan
Each audit is compared with the run before it. The score change is the difference between the two scores; a finding is new when it wasn't in the previous run and fixed when it was there but is gone now. A finding counts as the same when its check and page match. If the check catalogue changed between the runs, some differences come from new or retired checks rather than from your site.
## SEO
### SEO audit
Crawls your site the way a search engine does — following links, reading robots rules and sitemaps — and checks every page for on-page basics, crawlability blockers, broken links, and page-weight problems. Findings are ranked by severity so the critical, ranking-relevant issues surface first. Re-runs on a schedule, so regressions show up before they cost traffic.
### On-page SEO
On-page factors are the signals each individual page sends to search engines: unique titles and meta descriptions, one clear H1, canonical URLs, and structured data. They are the cheapest SEO wins — fully under your control, machine-checkable, and fixable without touching content strategy.
### Crawlability
Crawlability covers everything that decides whether a search engine reaches and indexes your pages: robots.txt rules, sitemaps, redirect chains, noindex flags, and broken links. A page that can't be crawled can't rank — crawl issues silently cost traffic you never see.
### Link health
Checks every internal and external link the crawl finds: broken targets, dead external references, and redirect chains. Broken internal links are critical — they leak ranking signal and strand visitors — while long redirect chains slow navigation and burn crawl budget. External links breaking over time is normal; this catches it before visitors do.
### Performance (SEO)
The SEO-relevant slice of page speed: oversized HTML, missing compression, and render-blocking scripts or styles. These are cheap, structural fixes — distinct from the full Performance audit, which measures how fast pages actually load. Slow, heavy pages get crawled less and rank worse, so this category catches the basics first.
## Privacy & GDPR
### GDPR audit
Renders your pages and captures what they really do: third-party trackers, cookies set before consent, externally-loaded fonts, requests to servers in the USA, and missing legal pages. These are the violations behind most GDPR warning letters and fines. Each finding comes with a concrete fix; guidance only, not legal advice.
### Trackers
Trackers are third-party scripts — ad pixels, analytics, social embeds — that process visitor data and typically share it with their provider. Under the GDPR they need informed consent before they load; a tracker firing before the consent banner is the classic violation. Fewer trackers also means less consent UI and a faster page.
### Cookies
Non-essential cookies — analytics, advertising, embeds — may only be set after the visitor consents. The audit loads your pages without interacting with any consent banner and records which cookies appear anyway: those are pre-consent violations, the single most common GDPR finding. Strictly necessary cookies (sessions, carts) are fine without consent.
### Fonts
When a page loads webfonts from a third-party server, every visitor's IP address is sent there before any consent can happen. German courts have ruled exactly this — a font loaded from US servers — an actionable GDPR violation. The fix is mechanical: download the font files and serve them from your own domain.
### Data transfer
When a site loads resources from third-party servers — fonts, CDNs, embeds — visitor IP addresses travel there too. Transfers to countries outside the EU need a legal basis under the GDPR; German courts have treated even a Google Fonts load from US servers as an actionable violation. Self-hosting third-party assets closes the issue.
### Transparency
The GDPR requires visitors to be told what data is processed and by whom — in practice: a reachable privacy policy. German-market sites additionally need an imprint (Impressum). Missing or unreachable legal pages are trivially detectable, which makes them a favorite target for automated warning letters.
## Security
### Security audit
Checks the security posture a browser can see: response headers, TLS configuration, cookie flags, mixed content, and information disclosure. These are the same checks attackers run first — they're fully automated and reveal soft targets. Everything found is config-level fixable, no code rewrite required.
### Security headers
Security headers are instructions the server sends with every response — Content-Security-Policy, Strict-Transport-Security, X-Frame-Options and friends — that activate browser-side protections against script injection, clickjacking, and protocol downgrades. They are one-line server config with outsized effect, which is why every security scanner checks them first.
### Transport
Covers how traffic is encrypted in transit: every page served over HTTPS, http:// requests redirected, and HSTS telling browsers to never try plain HTTP again. Without HSTS, a first visit over an untrusted network can be intercepted before the redirect happens — one header closes that window.
### Cookies
Cookie security is about flags: `Secure` keeps a cookie off plain HTTP, `HttpOnly` hides it from JavaScript (so XSS can't steal sessions), and `SameSite` limits cross-site sending (CSRF). A session cookie missing these is a soft target — and the fix is adding attributes, not changing logic.
### Content
Mixed content means an HTTPS page loads some resources — scripts, images, styles — over plain http://. Browsers block the most dangerous cases and mark the page as not fully secure for the rest; an attacker on the network can tamper with anything unencrypted. The fix is serving every resource over https.
### Disclosure
Information disclosure covers what your responses reveal about the stack: the version number in the `Server` header and an `X-Powered-By` header. None of it is an exploit by itself, but it tells attackers exactly which known vulnerabilities to try. Suppressing the headers costs one config line.
---
# Analytics API
Source: https://satsu.pro/docs/api
## 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`](/docs/cli#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](/docs/mcp#tools-per-plan) 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](#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](https://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`.
---
## Free tools
- [Site check](https://satsu.pro/check): Free site check: paste a URL and get six plain answers (consent, SEO, accessibility, security, performance, which analytics) from a real browser render. No signup; the address is never stored.
- [Google Fonts checker](https://satsu.pro/tools/google-fonts-checker): Free check whether a website loads Google Fonts from Google's servers (a GDPR risk), with the exact references found.
- [Site check: Cookie banner](https://satsu.pro/check/cookie-banner): A site needs a cookie banner when it sets non-essential cookies or loads third-party trackers before the visitor agrees, and this free check lists exactly what your page loads on arrival, from a real browser, with no signup and nothing stored.
- [Site check: SEO](https://satsu.pro/check/seo): This free one-page SEO check reads your page the way a visitor's browser does and reports the title, meta description, headings, canonical link, broken links, robots.txt and sitemap, with no signup and nothing stored.
- [Site check: Accessibility](https://satsu.pro/check/accessibility): This free accessibility checker renders your page in a real browser, runs the axe-core rules against it and reports the WCAG A and AA violations it finds, with no signup and nothing stored.
- [Site check: Security headers](https://satsu.pro/check/security-headers): This free check reads the response headers your page sends, the HTTPS setup and the TLS certificate, and reports missing security headers, an expiring certificate and outdated TLS, with no signup and nothing stored.
- [Site check: Page weight](https://satsu.pro/check/page-weight): This free check loads your page in a real browser and reports its transfer size, its number of requests and its time to first byte, with no signup and nothing stored.
- [Site check: Analytics](https://satsu.pro/check/analytics): This free check opens a page in a real browser, lists the analytics tools it loads, such as Google Analytics, Matomo, Plausible or Satsu, and says whether each one typically needs a consent banner, with no signup and nothing stored.