# Run misomoon in your Cloudflare account

This guide deploys misomoon to your own Cloudflare account. Then it walks you through
claiming your instance and tracking your first site. misomoon runs as one Worker with
D1 databases and a queue. You have no server or container to manage.

There are two ways to deploy:

- [With the Deploy to Cloudflare button](#deploy-with-the-button). This takes about
  5 minutes and needs only a browser.
- [From the command line](#deploy-from-the-command-line). Use this to change the code,
  to run more shards, or to deploy from your own CI.

## Before you start

You need a Cloudflare account. The Workers Free plan works for small sites. The Free
plan's queue allows 10,000 operations a day, and each event uses about 3, so it
handles about 3,000 events a day. For more traffic, use the Workers Paid plan. See
[Workers pricing](https://developers.cloudflare.com/workers/platform/pricing/),
[D1 pricing](https://developers.cloudflare.com/d1/platform/pricing/), and
[Queues pricing](https://developers.cloudflare.com/queues/platform/pricing/).

misomoon creates these resources in your account:

| Resource | Name | What it is for |
| --- | --- | --- |
| Worker | `misomoon` or `misomoon-api` | The API, the tracker, and the dashboard |
| D1 database | `misomoon-control` | Accounts, sites, goals, and keys |
| D1 databases | `misomoon-shard-0`, `misomoon-shard-1` | Events and visits |
| Queues | `misomoon-events`, `misomoon-events-dlq` | Event buffering, and failed batches |
| Cron trigger | Every 5 minutes | Reports, alerts, and retention |

## Deploy with the button

1. Select the button:

   [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/jackzard/misomoon/tree/deploy/misomoon)

2. Sign in to Cloudflare, and connect your GitHub or GitLab account. Cloudflare copies
   the deploy bundle into a new repository that you own.
3. Keep the default names for the databases and the queues, or change them. The
   migrations use binding names, so any names work.
4. Select **Create and deploy**. The build creates the databases and the queues, applies
   the migrations, and deploys the Worker.
5. When the deploy is done, open the Worker's URL. It looks like
   `https://misomoon.<your-subdomain>.workers.dev`.

Continue with [claim your instance](#claim-your-instance).

The button deploys the bundle that CI builds from `main` and publishes to the `deploy`
branch. It sets `SIGNUPS` to `invite`, so only the first person can sign up.

## Deploy from the command line

You need Node.js 22.5 or later, pnpm 10, and git.

1. Clone the repository and install the dependencies:

   ```sh
   git clone https://github.com/jackzard/misomoon.git
   cd misomoon
   pnpm install
   ```

2. Sign in to Cloudflare:

   ```sh
   pnpm --filter @misomoon/api exec wrangler login
   ```

3. Close open sign-up. In `apps/api/wrangler.jsonc`, set `SIGNUPS` in `vars` to
   `invite`. Change the line if `vars` already has one, so the key appears once:

   ```jsonc
   "SIGNUPS": "invite"
   ```

   The first account can still sign up. Everyone after that needs an invitation.

4. Deploy:

   ```sh
   pnpm --filter @misomoon/api run deploy
   ```

   The command builds the tracker and the dashboard. On the first run, it also creates
   the three D1 databases and the two queues, and writes the database ids into
   `apps/api/wrangler.jsonc`. Then it applies the migrations and deploys the Worker.
   Commit the changed `wrangler.jsonc`, so that the next deploy uses the same databases.

5. Open the URL that the deploy prints.

To keep the data in the EU, set `D1_JURISDICTION=eu` on the first deploy. D1 then runs
and stores the databases only in the EU. Cloudflare sets a database's jurisdiction when
it is created and never changes it, so set it before the first deploy, and on every run
that adds shards. [D1 data location](https://developers.cloudflare.com/d1/configuration/data-location/)
has the details.

To start with more shards, set `SHARD_COUNT`, for example
`SHARD_COUNT=4 pnpm --filter @misomoon/api run deploy`. [Scale the shards](upgrading.md#scale-the-shards)
explains when you need more.

## Claim your instance

1. Open your misomoon URL, and select **Create an account**.
2. Enter your email, name, and password. This account owns the instance.

After this, the sign-up link is gone. To add people, open **Settings**, and invite them
to your team.

Claim the instance right after the deploy. Until the first account exists, anyone who
knows the URL can sign up.

## Track your first site

1. In **Settings**, add your site's domain.
2. Copy the snippet, and paste it into the `<head>` of every page:

   ```html
   <script defer src="https://misomoon.example.workers.dev/m.js?s=your-site"></script>
   ```

3. Open your site. You appear in **Live** within a few seconds.

The [tracking guide](tracking.md) covers custom events, revenue, and goals.

## Use your own domain

To use a domain such as `analytics.example.com`:

1. Add the domain to Cloudflare as a zone, if it isn't one already.
2. In the Cloudflare dashboard, open **Workers & Pages**, and select the misomoon
   Worker.
3. Open **Settings** > **Domains & Routes**, and select **Add** > **Custom domain**.
4. Enter `analytics.example.com`, and save.
5. Set the `PUBLIC_URL` variable to `https://analytics.example.com`. Then the links in
   email reports point to the right place.

Update the snippet on your sites to use the new domain.

## Turn on optional features

Each feature needs a secret or a variable. In the Cloudflare dashboard, open the Worker,
then **Settings** > **Variables and Secrets**. From the command line, run
`wrangler secret put <NAME>` in `apps/api`.

| Feature | What to set |
| --- | --- |
| Emails: invitations, password resets, reports, and alerts | One provider, and the variable `EMAIL_FROM` with an address on a domain that the provider verified. For [Cloudflare Email Service](https://developers.cloudflare.com/email-service/), add `"send_email": [{ "name": "EMAIL" }]` to `wrangler.jsonc`. For Amazon SES, set the variable `AWS_SES_REGION` and the secrets `AWS_SES_ACCESS_KEY_ID` and `AWS_SES_SECRET_ACCESS_KEY`. |
| Email reports with the right links | The variable `PUBLIC_URL` |
| Google Analytics import and Search Console | The secrets `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` |
| A managed proxy subdomain for each site | The secret `CF_API_TOKEN`, and the variables `CF_ZONE_ID` and `PROXY_CNAME_TARGET` |
| Deleting old data | The variable `RETENTION_DAYS` |
| A limit on events per site per day | The variable `INGEST_DAILY_CAP` |

The [configuration reference](configuration.md) explains each one.

Without an email provider, invitations still work. The dashboard shows the invitation
link, and you send it yourself.

A variable that you set in the Cloudflare dashboard is replaced by the next deploy from
the repository. To keep a variable, put it in `vars` in `wrangler.jsonc`. Secrets are
not affected.

## Next steps

- [Connect Claude, Cursor, or another MCP client](mcp.md).
- [Serve the tracker from your own domain](PROXY.md) so that ad blockers don't drop
  events.
- [Upgrade to a new version](upgrading.md).
- [Fix common problems](troubleshooting.md).

---

# Track your site

This guide adds the misomoon tracker to a website and sends custom events and revenue.
It assumes you already run misomoon, either on your own Cloudflare account
([self-hosting](self-hosting.md)) or locally.

The core tracker is `m.js`, under 1 KB gzipped. Each feature you tick in the site settings adds
its own code to the same file ([Choose what to track](#choose-what-to-track)). It sets no cookies and stores nothing on the
visitor's device. Each visitor gets an id that is a hash of a daily salt, the site, the
IP address, and the user agent. The salt changes every day at 00:00 UTC, and the IP
address is never stored. [Architecture](ARCHITECTURE.md#ingest) explains the details.

## Add the script

1. In the dashboard, add your site's domain. A new account sees the form on its first
   screen; later sites go in **Settings** > **Sites**. The dashboard then opens the
   install snippet, which carries the site id.
2. Paste the snippet into the `<head>` of every page:

   ```html
   <script defer src="https://analytics.example.com/m.js?s=your-site"></script>
   ```

3. Open your site in a browser. Within a few seconds, you appear in **Live** in the
   dashboard.

The server counts a page only on the site's domain or one of its subdomains, so visits on
`localhost` are left out. A browser the tracker doesn't count says why in its console, for
example `misomoon skipped: bot`.

Single-page apps need nothing extra. The tracker listens to `pushState` and `popstate`
and counts each route change as a pageview. For a router that uses `#/routes`, add
`data-hash`. Each route is then its own page, such as `/#/pricing`, without any query
string inside the route.

## Send custom events

Call `misomoon()` with an event name:

```js
misomoon('Signup')
misomoon('Signup', { props: { plan: 'pro', source: 'pricing' } })
```

To send events from HTML without JavaScript, tick **Tagged events** in the
[settings](#choose-what-to-track) and put `data-misomoon-event` on an element. A click
sends the event. On a form, the submit sends it.

```html
<button data-misomoon-event="Start trial" data-misomoon-prop-plan="pro">Start trial</button>
<a href="/checkout" data-misomoon-event="Buy" data-misomoon-revenue-amount="19" data-misomoon-revenue-currency="USD">Buy</a>
```

Each `data-misomoon-prop-<name>` attribute adds the property `<name>` to the event.
`data-misomoon-revenue-amount` and `data-misomoon-revenue-currency` add revenue, as the
`revenue` option of `misomoon()` does.

An event name can be up to 120 characters of any text except `;` and `|`, which separate
filters in the dashboard and the API.

To count an event without letting it end a bounce, pass `interactive: false`. Use it for
events that fire without a real action from the visitor, such as a video that plays by
itself:

```js
misomoon('Autoplay started', { interactive: false })
```

To run code after the event is sent, for example before a navigation, pass `callback`:

```js
misomoon('Download', { props: { file: 'report.pdf' }, callback: () => (location.href = '/report.pdf') })
```

Calls made before `m.js` loads are lost unless you queue them. Add this line before the
script tag. `m.js` sends the queued calls after its first pageview:

```html
<script>window.misomoon = window.misomoon || function () { (misomoon.q = misomoon.q || []).push(arguments) }</script>
```

## Track revenue

Pass the amount and an ISO 4217 currency code:

```js
misomoon('Purchase', { revenue: { amount: 49.9, currency: 'EUR' }, props: { plan: 'yearly' } })
```

Each site has one reporting currency. The dashboard guesses it from your timezone when
you add the site, and USD is the fallback. To change it, open **Settings** > **Sites**,
or send `PATCH /api/v1/sites/<site>` with `{"currency": "EUR"}`
([API reference](api.md#sites)). Revenue totals include events in that currency and events sent without a currency. Events in other
currencies are stored but left out of the totals, so the dashboard never adds euros to
dollars.

To count payments from Stripe, Polar, Lemon Squeezy, or Dodo Payments without calling
`misomoon()`, connect the provider's webhook: [Connect payments](revenue.md).

## Turn goals into conversions

In **Settings**, add a goal for an event name (`Signup`) or a page path (`/thank-you`,
or `/docs*` for a prefix). The **What they did** panel then shows each goal's visitors,
conversion rate, and revenue. Goals work on data you already collected.

## What the tracker sends by itself

| Event | When | Turn off with |
| --- | --- | --- |
| `pageview` | On load, on each route change, and when the back button shows a page from the browser's cache | `data-manual` (send them yourself with `misomoon('pageview')`) |
| `engagement` | When the page is hidden or the route changes: engaged time, which counts only while the page has focus, and the share of the page scrolled, plus what the ticked features collected | |

The [configuration reference](configuration.md#tracker-attributes) lists every attribute
the script tag accepts.

## Choose what to track

Everything else is a checkbox under **Settings** > **Install** > **What to track**. A new
site has every feature on. Three presets set the boxes for you:

| Preset | Features | `m.js`, gzipped |
| --- | --- | --- |
| Everything (the default) | All of the table below | 4.8 KB |
| Light | Outbound links, downloads, form submits, and tagged events | 1.8 KB |
| Pageviews only | None | 998 bytes |

The id in brackets is the name that `data-disable` on the script tag and the API's
`features` field take.

| Feature | What it collects | Adds, gzipped |
| --- | --- | --- |
| Outbound links (`outbound`) | An `Outbound link` event for a click or middle click on a link to another host, without its query string | 0.2 KB |
| Downloads (`downloads`) | A `Download` event for a click or middle click on a link to a file such as `.pdf` or `.zip`, or on a link with a `download` attribute, without its query string; `data-download-ext="sketch,fig"` on the script tag adds extensions | 0.4 KB |
| Form submits (`forms`) | A `Form sent` event for each form, named by its `id` or `name` | 0.2 KB |
| Tagged events (`events`) | Clicks and submits on elements with `data-misomoon-event`, with props and revenue ([custom events](#send-custom-events)) | 0.3 KB |
| Payments (`payments`) | Tags payment links and hands out `misomoon.ref()`, so a checkout finds its visit ([Connect payments](revenue.md)). Connecting a provider ticks it | 0.5 KB |
| Web Vitals (`vitals`) | LCP, INP, CLS, FCP, and TTFB from real visits | 0.6 KB |
| Clicks (`clicks`) | Each clicked element, with rage and dead clicks | 1.0 KB |
| JavaScript errors (`errors`) | Uncaught errors and rejected promises. A script from another origin reports only `Script error.` unless its tag has `crossorigin`, and those are left out | 0.4 KB |
| Form fields (`fields`) | The fields a visit used and the one it left a form at | 0.4 KB, plus 0.3 KB shared |
| Video and audio (`media`) | Plays of `<video>` and `<audio>`, and how far they got | 0.3 KB, plus 0.3 KB shared |
| Content blocks (`content`) | Views and clicks on elements with `data-misomoon-content` | 0.3 KB, plus 0.3 KB shared |
| Site search (`search`) | The search term in the page URL | nothing: the server reads it |

Sizes were measured on 2026-10-24 as the growth of the gzipped file. Form fields, media,
and content share 0.3 KB of code, so ticking all three costs it once. `m.js` with every
feature is 4.8 KB.

The script tag loads `m.js?s=<site id>`. The server answers with the core tracker and the
code for the ticked features in one file, so a feature costs no extra request. A change
in the settings reaches visitors within about six minutes: the server caches site settings
for a minute, and browsers cache `m.js` for five.

`data-disable` on the script tag turns a ticked feature off on the pages that carry it,
for example `data-disable="clicks,errors"` on a checkout page.

The server does some work so the tracker doesn't have to:

- **Site search.** The server reads the term from the page URL it already receives, from
  the first of `q`, `s`, `search`, `query` and `keyword` that has a value. If your search
  uses another parameter, list it under **Search parameters**.
- **Path rules.** **Only count these paths** and **Never count these paths** take
  comma-separated paths, where `*` matches within one part of the path and `**` across
  parts. A page they leave out counts neither its view nor its time; custom events on it
  still count.
- **Checkout ids.** With Payments ticked, the server reads the checkout id that Stripe,
  Polar or Dodo Payments puts on the success page's URL.
- **Language.** The server reads the visitor's language from the request.

The API takes all of these settings: see [`PATCH /api/v1/sites/{id}`](api.md).

## See what people do on a page

The dashboard's **Behavior** view reports what people did on a page, from counts the
engagement beacon carries. Each report needs its feature ticked, except scroll depth,
which is always on. It never records a session or what anyone types.

| Report | What it counts |
| --- | --- |
| Clicks | Clicks per element, rage clicks (the third click on one element within a second), and dead clicks (nothing on the page changed for a second after a click on something that looks clickable) |
| Scroll | The share of visits that scrolled past each tenth of the page |
| Forms | Starts, submissions, and the field where people stopped |
| Search | Site search terms, read from the page URL |
| Errors | JavaScript errors, grouped by message and file, without the query string |
| Media | Plays of `<video>` and `<audio>`, and the share that reached 25, 50, 75% and the end |
| Content | How often tagged content was on screen and clicked |

**Show on your site** opens the page in a new tab with `#misomoon-overlay` on its URL. The
tracker then sends nothing for that tab and loads `overlay.js` from next to itself, which
draws the clicks and the scroll depth over the page. The dashboard tab answers only that
tab, and only when it is on the site's domain. A site that sends a
`Cross-Origin-Opener-Policy` header cuts the link between the two tabs, and the overlay
says so.

Attributes on your page's elements shape the reports:

| Attribute | Example | What it does |
| --- | --- | --- |
| `data-misomoon-content` | `<section data-misomoon-content="Hero banner">` | Counts the element in the Content report: seen once half of it is on screen, and clicked |
| `data-misomoon-media` | `<video data-misomoon-media="Product tour">` | Names a video or audio element. Without it the report uses its `title` or file name |
| `data-misomoon-id` | `<button data-misomoon-id="buy">` | A stable name for a clicked element, so a redesign doesn't split its clicks |
| `data-misomoon-mask` | `<div data-misomoon-mask>` | Sends no text for clicks inside, such as a name in a menu |
| `data-misomoon-ignore` | `<form data-misomoon-ignore>` | Leaves a form out of the Forms report and the `Form sent` event |

The tracker never sends a field's value. A clicked field's label is its `name` or type, and
the server replaces email addresses and runs of six or more digits in a search term
before it stores it.

These reports keep counts per page and element, never the path of one visit through the
site. Whether you need consent still depends on your setup and your country. This guide is
not legal advice.

## Stop ad blockers from dropping events

Some blockers drop requests to analytics hosts. Serve the tracker from your own domain
instead. [Serve the tracker from your own domain](PROXY.md) shows a managed subdomain, one-click proxy deploys, and snippets for
Cloudflare Workers, Next.js, Vercel, Netlify, Nginx, Caddy, and SvelteKit.

## Exclude yourself

To leave out a whole office or your own servers, add their IP addresses under
**Settings** > **Install** > **Privacy** > **Never count these IP addresses**
([privacy settings](compliance.md#privacy-settings)). To leave out one browser, run this
once in the browser console on your site:

```js
localStorage.setItem('misomoon_ignore', 'true')
```

To count your visits again, remove the key. The
[opt-out button](compliance.md#let-visitors-opt-out) lets your visitors do the same.

---

# Install the tracker on your platform

Every setup on this page adds the same script tag to the `<head>` of each page. Copy
yours from **Settings** > **Install** in the dashboard. It carries your site id:

```html
<script defer src="https://analytics.example.com/m.js?s=your-site"></script>
```

After you publish, open your site in a browser. You appear in **Live** within a few
seconds. If you don't, the browser console says why, for example `misomoon skipped: bot`,
and [troubleshooting](troubleshooting.md) lists the other causes.

To count visitors whose ad blocker drops analytics requests, serve the tracker from your
own domain and use that address in the tag ([First-party proxy](PROXY.md)).

## Website builders

### WordPress

Install the misomoon plugin. It adds the tag, leaves out your own visits, can serve the
tracker from your domain, and sends WooCommerce orders to misomoon
([Track a WordPress site and WooCommerce store](wordpress.md)).

Without the plugin, add the tag from your theme. In a child theme's `functions.php`, or
in a code snippets plugin, add:

```php
add_action('wp_head', function () {
	echo '<script defer src="https://analytics.example.com/m.js?s=your-site"></script>';
});
```

A theme update replaces the parent theme's `functions.php`, so don't edit that file.

### Shopify

1. Open **Online Store** > **Themes**.
2. On your current theme, click **...** > **Edit code**.
3. Open `layout/theme.liquid` and paste the tag before `</head>`.
4. Click **Save**.

Shopify's checkout doesn't load your theme's code, so the tracker doesn't count checkout
pages. To count orders, post them to the custom webhook from your own code
([Send payments from your own server](revenue.md#send-payments-from-your-own-server)).

### Webflow

1. Open **Site settings** > **Custom code**.
2. Paste the tag into **Head code**.
3. Save, then publish the site. Custom code runs only on the published site.

### Framer

1. Open **Site Settings** > **General** > **Custom Code**.
2. Paste the tag into the field for the end of the `<head>` tag.
3. Publish the site.

### Wix

1. Open **Settings** > **Custom code** in the **Advanced** section.
2. Click **Add Custom Code** and paste the tag.
3. Choose **All pages** and place the code in **Head**.
4. Click **Apply**.

Wix runs custom code only on a premium plan with a connected domain.

### Squarespace

1. Open **Settings** > **Advanced** > **Code Injection**.
2. Paste the tag into **Header**.
3. Click **Save**.

Code injection needs a plan that includes it.

### Ghost

1. Open **Settings** > **Code injection**.
2. Paste the tag into **Site header**.
3. Click **Save**.

### Carrd

Add an **Embed** element, set its type to **Code** and its placement to **Head**, and
paste the tag. Embeds need a Pro plan.

### Google Tag Manager

1. Create a tag of type **Custom HTML** and paste the script tag.
2. Set its trigger to **All Pages**.
3. Submit and publish the container.

A blocker that stops Google Tag Manager also stops every tag inside it. To count those
visitors, add the script tag to your pages directly, through a proxy.

## Frameworks

Single-page apps need nothing extra: the tracker counts each `pushState` route change as
a pageview. For a router that uses `#/routes`, add `data-hash` to the tag.

### React, Next.js, and React Router

Use the `<Misomoon>` component from `@misomoon/sdk/react` in your root layout. In Next.js,
`withMisomoon()` from `@misomoon/sdk/next` also sets up the proxy. The
[SDK guide](sdk.md#add-the-tracker-to-a-react-or-nextjs-app) shows both.

### Vue and Vite apps

Paste the tag into the `<head>` of `index.html`. To send events from components, call `init()` from
`@misomoon/sdk/web` instead of adding the tag:

```ts
// main.ts
import { init } from '@misomoon/sdk/web'

init({ site: 'your-site', host: 'https://analytics.example.com' })
```

Then call `track('Signup')` from any component. Use either the tag or `init()`, not
both: a tag in `index.html` and a call to `init()` add the tracker twice.

### Nuxt

Add the tag to `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
	app: {
		head: {
			script: [{ src: 'https://analytics.example.com/m.js?s=your-site', defer: true }],
		},
	},
})
```

### SvelteKit

Paste the tag into the `<head>` of `src/app.html`, before `%sveltekit.head%`. To send
events, import `track` from `@misomoon/sdk/web`. It does nothing during server
rendering, so you can call it from any component.

### Astro

Add the tag to the `<head>` of your base layout. `is:inline` tells Astro to leave the
tag as it is:

```html
<script is:inline defer src="https://analytics.example.com/m.js?s=your-site"></script>
```

### Angular

Paste the tag into the `<head>` of `src/index.html`.

### Server-rendered apps

In Laravel, Django, Rails, Phoenix, and other frameworks that render pages from
templates, paste the tag into the `<head>` of the layout that every page extends. For
example, use `resources/views/layouts/app.blade.php` in Laravel or
`app/views/layouts/application.html.erb` in Rails. To send events from your server, such
as a signup, use the Node SDK or call `/api/event`
([Send events from your server](sdk.md#send-events-from-your-server)).

### Static site generators

In Hugo, Jekyll, Eleventy, and similar tools, paste the tag into the partial or layout
that holds the `<head>`.

## AI app builders

In Lovable, Bolt, v0, Replit, and other tools that write the app for you, ask the agent
to add the tag:

> Add this script tag to the `<head>` of every page, exactly as written:
> `<script defer src="https://analytics.example.com/m.js?s=your-site"></script>`

Then publish the app and check **Live**. If the app has its own server, ask the agent to
pass `misomoon.ref()` to the checkout too ([Connect payments](revenue.md#pass-the-ref-to-the-checkout)).

## Mobile apps

React Native and Expo apps use `@misomoon/sdk/react-native`. It counts screens and
engaged time without a script tag ([Track a React Native or Expo app](sdk.md#track-a-react-native-or-expo-app)).

---

# Track a WordPress site and WooCommerce store

The misomoon plugin adds the tracker to every page of a WordPress site. It can also
serve the tracker from your own domain, and it sends WooCommerce orders and refunds to
misomoon. Each paid order then counts toward the source, country, and device of the
visit that placed it. The plugin lives in [`plugins/wordpress/misomoon`](../plugins/wordpress/misomoon)
and needs WordPress 6.0 and PHP 7.4 or later.

## Install the plugin

1. Make a zip of the plugin folder:

   ```sh
   cd plugins/wordpress && zip -r misomoon.zip misomoon -x '*.DS_Store'
   ```

2. In WordPress, open **Plugins** > **Add New Plugin** > **Upload Plugin**, choose
   `misomoon.zip`, and click **Install Now**. Then click **Activate**.
3. Open **Settings** > **misomoon**.
4. In **misomoon address**, enter the address of your dashboard, such as
   `https://analytics.example.com`.
5. In **Site id**, enter the value after `?s=` in the snippet under **Settings** >
   **Install** in misomoon.
6. Click **Save Changes**.

The settings page then shows the script tag your pages load. Open your site in a private
window: you appear in **Live** in misomoon within a few seconds.

The plugin loads no tracker for people who can edit posts while they are logged in, so
your own visits don't count. To count them, untick **Don't count people who can edit
posts**.

## Settings

| Setting | Default | What it does |
| --- | --- | --- |
| **misomoon address** | none | Where misomoon answers. Must be a full `http` or `https` URL. |
| **Site id** | none | The site to count visits for. Letters, digits, dots, dashes, and underscores. |
| **Don't count people who can edit posts** | on | Editors, authors, and administrators load no tracker while they are logged in. |
| **Serve the tracker from this site** | off | Loads the tracker and sends its events through the REST API of your site ([Serve the tracker from your domain](#serve-the-tracker-from-your-domain)). |
| **Count #/route changes as pages** | off | Adds `data-hash`, for a single-page app that routes with `#/`. |
| **Send orders and refunds to misomoon** | off | Appears when WooCommerce is active ([Count WooCommerce orders](#count-woocommerce-orders)). |
| **Signing secret** | none | The secret of the custom webhook. The page never shows a saved secret. Leave the field empty to keep it. |

Without an address and a site id, the plugin prints nothing. A wrong value isn't saved:
the page shows an error and keeps the value you had.

To send custom events, call `misomoon('Signup')` from JavaScript, or add
`data-misomoon-event` to an element ([Send custom events](tracking.md#send-custom-events)).

## Serve the tracker from your domain

Ad blockers drop requests to analytics hosts. With **Serve the tracker from this site**
ticked, the page loads the tracker from `/wp-json/mm-relay/v1/m.js`, and the tracker
sends its events to `/wp-json/mm-relay/v1/api/event`. WordPress forwards each event to
misomoon with the visitor's address, user agent, and language.

- The proxy fetches `m.js` from misomoon for your site id and keeps it for 5 minutes.
  It serves no other site's tracker.
- An event over 16 KB isn't forwarded, the same limit misomoon applies.
- Visitor locations survive only when the site is behind Cloudflare, which tells
  WordPress the country, and the city when **Add visitor location headers** is on.
  Elsewhere misomoon counts the visitors and leaves their location unknown.
- The visitor's address comes from `CF-Connecting-IP`, `True-Client-IP`, `X-Real-IP`,
  the first `X-Forwarded-For`, then the connection. To trust only the header your host
  sets, filter `misomoon_visitor_ip`.
- A security plugin that turns off the REST API for visitors who aren't logged in also
  turns off the proxy. The tracker then fails to load, and nothing is counted.

## Count WooCommerce orders

1. In misomoon, open **Settings** > **Revenue**, pick **Your server**, and click **Make
   signing secret**.
2. In WordPress, open **Settings** > **misomoon**.
3. Tick **Send orders and refunds to misomoon** and paste the secret into **Signing
   secret**.
4. Click **Save Changes**.

When a shopper places an order, the plugin hands out a ref from the shopper's visit. It
finds the visit by the address and user agent that WooCommerce stores on the order, and
it keeps the ref in the order's `_misomoon_ref` meta. The classic checkout and the block
checkout both work.

When the order is paid, the plugin posts it to the custom webhook
([Send payments from your own server](revenue.md#send-payments-from-your-own-server)),
signed with the secret. The plugin treats an order as paid when the payment gateway
reports it, or when the order moves to **Processing** or **Completed**, for payments such
as bank transfers. An order is sent once, as `wc_<order id>`, in the order's currency.
Each refund is sent as `wc_refund_<refund id>` and counts against its order.

- An order made in **wp-admin** gets no ref, because it carries the address of the shop
  manager, not the buyer. Its payment still counts, under **Unknown**.
- A guest has no customer id, so a later order from the same guest finds its own visit
  and doesn't follow the first one.
- Orders of zero, and orders paid before you ticked the setting, aren't sent.
- After a network error, `429`, or a `5xx` answer, WP-Cron sends the order again after
  1, 5, and 25 minutes. The order id makes a resend count once.
- The settings page shows the last order sent, or the reason the last one failed, such as
  `status 401` for a wrong secret.

Totals count only payments in the site's currency in misomoon. Set that currency to your
store's currency under **Settings** > **Sites** ([Track revenue](tracking.md#track-revenue)).

## Hooks

| Hook | Kind | Use it to |
| --- | --- | --- |
| `misomoon_should_track` | filter, `bool` | Decide whether a page loads the tracker, for example to skip a page or a role. |
| `misomoon_script_attributes` | filter, `array` | Add attributes to the script tag, such as `data-disable` or `data-prop-plan`. |
| `misomoon_visitor_ip` | filter, `string` | Choose the visitor's address for proxied events and refs. |

```php
// never count the account pages
add_filter('misomoon_should_track', function ($track) {
	return $track && !is_account_page();
});

// turn off click tracking on checkout
add_filter('misomoon_script_attributes', function ($attrs) {
	if (is_checkout()) {
		$attrs['data-disable'] = 'clicks';
	}
	return $attrs;
});
```

## Remove the plugin

Deactivating the plugin stops the tracker. Deleting it removes its settings and any
queued retries. The `_misomoon_ref` and `_misomoon_sent` meta stay on your orders.

## Test the plugin

`plugins/wordpress/test/run.mjs` runs WordPress and WooCommerce in WordPress Playground
against a fake misomoon. It checks the script tag, the proxy, the settings page, and an
order with its refund:

```sh
node plugins/wordpress/test/run.mjs --php=7.4
```

It downloads WordPress and WooCommerce, so it needs the network. It isn't part of
`pnpm test`.

---

# Use the dashboard

The dashboard is where you read your traffic and change how misomoon tracks a site. The
same Worker that runs the API and the tracker serves it at `/` on your misomoon host, for
example `https://analytics.example.com/`. To look around before you install anything,
open the public demo at `https://app.misomoon.com/?site=demo`.

This page walks through every view and every **Settings** tab. For what each number
means and how misomoon counts it, see [What the numbers mean](metrics.md).

## Find your way around

The sidebar on the left holds everything that isn't part of one view:

- The site menu at the top. Select the site name to switch to another site you can see.
  Signed-in users also get **Add a site** at the bottom of the menu, which opens
  **Settings** > **Sites**.
- The live counter, for example **3 people here now**. It counts visitors in the last 5
  minutes and refreshes every 30 seconds. Select it to open **Live**.
- The list of views, each with its number key.
- Your name and role, with a button to sign out. When you are signed out, a **Sign in**
  button takes their place.
- The theme button, which switches between the day and night themes, and the
  **Command** button, which opens the command palette.

The dashboard has seven views:

| View | Key | What it shows |
| --- | --- | --- |
| **Overview** | `1` | The summary, the KPI tiles and chart, and the panels for sources, pages, places, technology, actions, and speed |
| **Live** | `2` | Who is on the site now, minute by minute |
| **Funnels** | `3` | How many people get through a series of steps |
| **Paths** | `4` | Where people go after a page, or how they reached it |
| **Behavior** | `5` | Clicks, scroll depth, forms, site search, errors, media, and content blocks on a page |
| **Speed** | `6` | Web Vitals measured in real visitors' browsers |
| **Settings** | `7` | The script tag, goals, sharing, integrations, revenue, your team, your sites, and your account |

On a screen 960 pixels wide or narrower, the sidebar is hidden. Each view then starts
with a **View** menu and, when you can see more than one site, a **Site** menu. To sign
out on a narrow screen, open **Settings** > **Account**.

The theme follows your system setting until you pick one. The dashboard saves your
choice in this browser under the `localStorage` key `misomoon.theme`. It also remembers
the last tab you opened in each panel.

Some situations replace the views with a single screen:

- With no site yet, the dashboard asks **Which site should we watch?** and shows a form
  to add one. If you are signed out, it shows **Sign in or create an account** instead.
- When a site has never had a visit, **Overview** shows the script tag to paste, with a
  **Copy** button. The page checks every few seconds and loads the dashboard as soon as
  the first visit arrives.
- The Billing role sees no stats. Every view except **Settings** shows **Billing access**
  instead.

## Pick a period

The period controls sit at the top right of **Overview**, **Funnels**, **Paths**,
**Behavior**, and **Speed**. **Live** and **Settings** have none. The default period is
the last 30 days. Days start and end in the site's timezone, which you set under
**Settings** > **Sites**.

To pick a period, do one of these:

- Select one of the quick periods: **Today**, **7 days**, **30 days**, or **12 months**.
- Open the period menu, which shows the current period's name, and select a period.
- Press the period's key. The keys work whenever the period controls are on screen and
  you aren't typing in a field. You don't need to open the menu first.

| Key | Period | `period` value |
| --- | --- | --- |
| `D` | Today | `today` |
| `E` | Yesterday | `yesterday` |
| `H` | Last 24 hours | `24h` |
| `W` | Last 7 days | `7d` |
| `F` | Last 28 days | `28d` |
| `T` | Last 30 days | `30d` |
| `N` | Last 90 days | `90d` |
| `M` | Month to date | `mtd` |
| `L` | Last month | `lastmonth` |
| `Y` | Year to date | `ytd` |
| `S` | Last 6 months | `6mo` |
| `Z` | Last 12 months | `12mo` |
| `A` | All time | `all` |

### Pick a custom range

1. Open the period menu.
2. Under **Custom range**, enter the two dates. The order doesn't matter.
3. Select **Apply**.

A custom range covers at most 400 days. A longer range keeps **Apply** disabled and shows
**A custom range can cover at most 400 days.**

You can also drag across the chart on **Overview** to zoom into the days you dragged
over. The dashboard turns the selection into a custom range. Zooming works when the
chart shows days, weeks, or months, not minutes or hours.

### Compare two periods

The **Compare** buttons set what each number is compared with:

| Button | Compares with | `compare` value |
| --- | --- | --- |
| **Off** | Nothing | `0` |
| **Previous** | The same length of time just before the period. This is the default. | not set |
| **Last year** | The same dates a year earlier | `year` |

With a comparison on, each KPI tile shows its change, and the chart draws a second line
labelled **Previous period** or **A year earlier**. Rates such as **Left at once** change
in percentage points. A drop in **Left at once** shows as an improvement.

### Include imported history

The **Imported** button appears only when the site has imported history from Google or
a CSV export. It is on by default. While it is on, reports without filters add the
imported days to what misomoon collected. Filtered reports never include imported data.
To bring in history, see [Bring your history](import.md).

### Refresh and export

- The refresh button loads every number again. **Live** refreshes by itself, and it has
  the refresh button too.
- **Export CSV**, the download button, downloads a zip of CSV files for the current
  period and filters. The zip holds `visitors.csv` with one row per chart point, one file
  per breakdown such as `sources.csv`, `pages.csv`, and `countries.csv` with up to 1,000
  rows each, and `conversions.csv` for your goals.

## Read the overview

**Overview** reads from top to bottom. The summary sentence comes first, then the KPI
tiles and the chart, then the panels.

### Read the summary sentence

The card at the top puts the period into a few sentences, for example:

> 1,204 people visited in the last 30 days, up 12% on the period before. Most came
> through Organic Search (41%), and /pricing was the most opened page. The biggest
> audience is in Germany.

The sentence always compares with the period before, whatever the **Compare** buttons
say. A change under 1% reads **about the same as before**. When someone is on the site
now, a button such as **4 on the site right now** follows the sentence and opens
**Live**.

### Pick a metric on the chart

Each KPI tile shows a total for the period, its change when a comparison is on, and a
small line of its trend. Select a tile to draw that metric on the chart. Hover over a
tile to read its definition. The **Revenue** tile shows only when the period has revenue
above zero.

| Tile | `metric` value | What it counts |
| --- | --- | --- |
| **People** | `visitors` | Different people, counted without cookies |
| **Visits** | `visits` | Times someone came by. A visit ends after 30 quiet minutes. |
| **Pageviews** | `pageviews` | Pages opened, reloads included |
| **Pages per visit** | `views_per_visit` | Pages a visit opens on average |
| **Left at once** | `bounce_rate` | Visits that saw one page and did nothing else |
| **Time per visit** | `visit_duration` | Time from the first page to the last action of a visit |
| **Revenue** | `revenue` | Revenue sent with events and payments |

[What the numbers mean](metrics.md) explains how misomoon computes each one.

The chart picks a time step for the period. The buttons above it switch to another step
that fits the period: `minute` for up to 6 hours, `hour` for up to 8 days, `day` for 2
to 400 days, `week` for 14 days or more, and `month` for 60 days or more. The last stretch
of the line is dashed while its time step is still in progress. Hover over the chart to
read the value at each point.

### Mark an event on the chart

Notes mark a launch, a deploy, or a campaign on the chart. Each note shows as a flag on
the point it falls in. The **Note** button shows for the Owner, Admin, Editor, and Guest
editor roles.

1. Select **Note** above the chart.
2. Type what happened, up to 200 characters.
3. Select **Add**. To cancel, press `Esc`.

The dashboard dates a note at the moment you add it. To mark an earlier date, or to mark
deploys from CI, post the note with a `ts` through the [API](api.md). The dashboard has no
control for deleting a note.

### Read the panels

Below the chart, six cards break the period down:

| Card | Lists | Tabs or lenses |
| --- | --- | --- |
| **Where they come from** | Channels | **Sites**, **Search terms**, **Links**, **Campaigns**, **Mediums**, **Landed on** |
| **What they read** | Pages | **Most opened**, with time on page and the share read, **First page**, with the share that left at once, and **Last page**, with the exit rate |
| **Where they are** | Countries, with a world map | **Regions**, **Cities**, **Languages**, **Came via** |
| **What they use** | Devices | **Browsers**, **Systems**, **Screens**, **Networks** |
| **What they did** | Goals and events | **Goals**, **Events**, **Details sent** |
| **How fast it feels** | Web Vitals | **Open Speed** opens **Speed** |

**Where they come from**, **Where they are**, and **What they use** have two columns.
The left column lists the top channels, countries, or devices. Select a row on the left
to break it down on the right, under **within** and the row's name. That doesn't filter
the dashboard. For example, select **Organic Search** and then **Sites** to see which
search engines sent people. To filter the whole dashboard by a left-hand row, select the
filter icon on that row. Selecting a row on the right filters the dashboard by both
rows.

**Search terms** shows only when the site has Google Search Console connected and you
selected **Organic Search**. It lists Google searches with their clicks. Search Console reports searches, not visits, so its rows don't filter the dashboard.

**What they read** and **What they did** have one list with tabs. Select a row to filter
the dashboard by it. Select it again to remove the filter. **Details sent** lists the
custom properties sent with events, as rows such as `plan: pro`. Selecting one filters by
that property. Goals and events that carry revenue show it next to their name.

### Open the full list

Each card lists its top rows. To see every row, select **See all**, or **All channels**,
**All countries**, or **All devices** on the two-column cards. The full list opens in a
window that has these controls:

- A search box that narrows the rows as you type.
- Column headers that sort the rows. Select a header again to reverse the order.
- **Load more**, which adds the next 50 rows.
- Rows that filter the dashboard. Selecting one also closes the window.

The columns follow the list. Pages show pageviews, the share that left at once, time on
page, and the share read. Goals and events show times, conversion rate, revenue, and
average revenue. Other lists
show people, visits, pageviews, the share that left at once, time per visit, and revenue
when any row has some. To close the window, press `Esc` or select the close button.

## Filter the dashboard

A filter narrows every number in every view to the visits that match. Filters stay when
you switch views and clear when you switch sites. They also go into the URL, so a link
carries them.

### Filter by a row

Select a row in any panel. The filter bar under the period controls shows the new filter
as a chip, such as **Country is Germany**. Select the same row again to remove it.

### Build a filter

1. Select **Filter** in the filter bar.
2. Pick a **Dimension**.
3. Pick an **Operator**.
4. Type a value, or select one of the suggestions from your data. To match any of
   several values, separate them with `|`, for example `Germany|France`.
5. Select **Apply filter**, or press `Enter`.

The dimensions come in five groups:

| Group | Dimensions |
| --- | --- |
| Content | Page, Entry page, Exit page, Hostname |
| Acquisition | Channel, Source, Referrer, UTM source, UTM medium, UTM campaign, UTM term, UTM content |
| Location | Country, Region, City, Continent, Timezone, Network |
| Technology | Browser, Browser version, OS, OS version, Device, Screen, Language |
| Behaviour | Goal, Event, Custom property |

To filter by a property that you send with events, pick **Custom property** and type the
property's name, for example `plan`.

| Operator | Matches | In the URL |
| --- | --- | --- |
| **is** | The exact value. A `*` in the value matches any text, so `/blog/*` matches every blog post. | `==` |
| **is not** | Everything except the value. `*` works the same way. | `!=` |
| **contains** | Values that contain the text anywhere | `~` |
| **does not contain** | Values that don't contain the text | `!~` |

Each dimension takes one filter. A new filter on a dimension replaces the one already
there. The server refuses more than these limits, and the dashboard says so before it
sends the filter:

- 8 filters.
- 6 values in one filter.
- 16 values across all filters.
- No `;` or `|` inside a value.

### Remove filters

- Select the close button on a filter's chip.
- Press `Esc` to remove the last filter you added. If a menu or a window is open, `Esc`
  closes that first.
- Select **Clear all**, which shows when two or more filters are set.
- Run **Clear all filters** from the command palette.

**Live** has no filter bar, but filters still apply there. A filter you add from a list
on **Live** shows in the bar once you open another view. To remove it while you stay on
**Live**, press `Esc`.

### Save a segment

A segment is a saved set of filters. To save one, sign in and set up the filters first.

1. Select **Segments** in the filter bar.
2. Type a **Segment name**.
3. To share the segment with everyone who can see the site, select **Everyone on the site
   sees it**. The checkbox shows for the Owner, Admin, Editor, and Guest editor roles.
   Without it, only you see the segment, and the list marks it **you**.
4. Select **Save current filters**.

Saving a segment under a name that you already used replaces that segment's filters.

To apply a segment, open **Segments** and select its name. While the filters match a
segment, the button shows the segment's name. To delete a segment, select the close
button next to it. You can delete your own segments. Only the roles that can share a
segment can delete a shared one. You can also limit a shared link to one segment, as
[Sharing](#sharing) describes.

## Watch visitors live

**Live** shows the site right now and updates itself every 5 seconds while the browser
tab is visible. It ignores the period.

- The large number counts visitors in the last 5 minutes.
- The bars show pageviews for each of the last 30 minutes. Hover over a bar to read its
  pageviews and visitors.
- **Live activity** lists the latest 40 pageviews and events from the last 30 minutes,
  with the city or country, the browser, and the source.
- **Pages**, **Sources**, and **Countries** list the top 8 of each from the last 5
  minutes. Select a row to filter by it.

## Build a funnel

**Funnels** counts how many people get through a series of steps, and where the others
drop out.

1. Select the new funnel button next to **Saved**. The new funnel starts with two
   steps, `/` and `/pricing`.
2. Give the funnel a name.
3. Pick a **Funnel type**:
   - **Sequential**: the steps in order, with other pages and events allowed in between.
   - **Strict**: the steps in order, with nothing in between.
   - **Flexible**: the middle steps in order. The last step counts anyone who reached it
     after the first step.
4. For each step, pick **Visits page** or **Triggers event**, and type a path or an event
   name. A path takes `*`, as in `/blog/*`. Select **Add step** for more steps, up to 8.
5. To keep the funnel, select **Save funnel**. The Owner, Admin, Editor, and Guest editor
   roles can save and delete funnels.

The result updates as you edit, for the current period and filters. It shows the share
that **Converted**, how many **Completed**, and the share **Of all visitors**. Each step
shows its visitors and how many dropped out since the step before. To change a saved
funnel, select it under **Saved**, edit it, and select **Save changes**. **Delete** asks
you to select it twice.

[Goals, funnels, and paths](conversions.md) explains goals, funnels, and paths in depth.

## Follow paths through the site

**Paths** shows the pages people opened one after another.

- **Where they go next** starts with the pages where visits began. Select a page to see
  where people went after it.
- **How they got there** starts with the pages where visits ended. Select a page to see
  where people came from before it.

Each page you select adds a column, up to 6 pages. The trail above the columns shows your
selection and how many visitors followed it. Select **Start over** to clear the trail.
Switching direction clears it too. See [Goals, funnels, and paths](conversions.md) for how
misomoon builds paths.

## See what people do on a page

**Behavior** has seven reports: **Clicks**, **Scroll**, **Forms**, **Search**,
**Errors**, **Media**, and **Content**. Each report except **Scroll** needs its feature
ticked under **Settings** > **Install** > **What to track**. When the feature is off, the
report says so, and **Open settings** takes you there.

**Clicks** and **Scroll** report on one page. If you filtered by a single page with
**is**, they use that page. Otherwise, pick it from the **Page** menu, which lists the 50
most visited pages. **Show on your site** opens the page in a new tab and draws the
clicks and the scroll depth over it.

[See what people do on a page](tracking.md#see-what-people-do-on-a-page) describes what
each report counts and the attributes that shape it.

## Check page speed

**Speed** shows five Web Vitals, measured in real visitors' browsers. They need **Web
Vitals** ticked under **Settings** > **Install** > **What to track**
([Choose what to track](tracking.md#choose-what-to-track)).

Each tile shows the 75th percentile, the number of samples, a rating, and a bar of how the
samples split between the three ratings. The rating also has a shape: a circle for
**Good**, a square for **Needs work**, and a triangle for **Poor**.

| Vital | Measures | Good | Poor |
| --- | --- | --- | --- |
| LCP | Time until the main content is visible | 2.5 s or less | Over 4 s |
| INP | How fast the page responds to clicks and taps | 200 ms or less | Over 500 ms |
| CLS | How much the layout moves while it loads | 0.1 or less | Over 0.25 |
| FCP | Time until the first text or image appears | 1.8 s or less | Over 3 s |
| TTFB | Time until the server starts to respond | 800 ms or less | Over 1.8 s |

Values between the two limits rate **Needs work**. INP needs interactions, so pages that
people only read collect fewer INP samples.

**Slice by** lists the top **Pages**, **Devices**, **Countries**, and **Browsers**.
Select a row to filter by it, and the tiles show the vitals for that slice.

## Change settings

**Settings** has eight tabs. Each tab shows only when it has something for your role on
the open site. Owner, Admin, Editor, and Guest editor are the roles that can edit a
site. Owner and Admin can also manage people and sites. [Work with your team](teams.md) lists what
each role can do.

| Tab | Shows for | `tab` value |
| --- | --- | --- |
| **Install** | Anyone who can open the site. Only roles that can edit change it. | `install` |
| **Goals** | Anyone who can open the site. Only roles that can edit add or delete goals. | `goals` |
| **Sharing** | Roles that can edit | `sharing` |
| **Integrations** | Anyone who can open the site. Imports and Search Console show only for roles that can edit. | `connect` |
| **Revenue** | Roles that can edit | `revenue` |
| **Team** | The site's team owners and admins | `team` |
| **Sites** | Anyone signed in | `sites` |
| **Account** | Everyone | `account` |

With no site open, only **Sites** and **Account** show.

### Install

**Install** holds four cards:

- **Install** shows the script tag for the site, with a copy button. Paste it into the
  `<head>` of every page. [Track your site](tracking.md) covers custom events and revenue.
- **What to track** sets what the tracker collects beyond pageviews. Pick a preset
  (**Everything**, **Light**, or **Pageviews only**) or tick the features one by one. The
  card also holds **Search parameters**, **Only count these paths**, and **Never count
  these paths**. Select **Save** to apply your changes.
  [Choose what to track](tracking.md#choose-what-to-track) explains each feature.
- **Privacy** sets **Keep stats for** (how long the site's visits and events are kept),
  **Never count these IP addresses**, and **Respect Global Privacy Control and Do Not
  Track**. Select **Save** to apply them. Below, **Text for your privacy policy** is a
  section for your own privacy policy that lists what the site's saved settings
  collect, and **Opt-out button** is a snippet for your privacy page. Both have a copy
  button. [Privacy settings](compliance.md#privacy-settings) explains each one.
- **Proxy** serves the tracker from your own domain, so ad blockers don't drop it. It
  offers a **Managed subdomain** when the server has it turned on, one-click deploy
  buttons, and snippets for your own stack. **Path on your site** sets the path the
  snippets use, `/relay` by default. [Serve the tracker from your own domain](PROXY.md) walks through each option.

### Goals

**Goals** lists the site's goals with their type, name, and match. To add a goal:

1. Pick a **Goal type**: **Event** or **Page**.
2. Type an event name, such as `Signup`, or a path, such as `/thanks` or `/docs/*`.
3. Optionally, type a label.
4. Select **Add**.

To delete a goal, select the delete button next to it. Goals count data you already
collected. [Goals, funnels, and paths](conversions.md) explains goals and conversion rates.

### Sharing

**Sharing** holds two cards.

**Shared links** creates a read-only dashboard at `/share/<slug>`. To create one:

1. Type a name. Without one, the link is named **Shared link**.
2. Optionally, type a password.
3. Pick a **Segment** to limit the link to, or keep **All traffic**.
4. Pick when it **Expires**: **Never expires**, **7 days**, **30 days**, **90 days**, or
   **1 year**.
5. Select **Create link**.

Each link in the list has a button to copy its URL and one to delete it. See
[Share a dashboard](sharing.md) for how shared links work.

**Email reports** sends summaries and alerts by email. Type an address, pick a **Kind**,
and select **Subscribe**:

| Kind | Sends | Setting |
| --- | --- | --- |
| **Weekly report** | A summary each week | None |
| **Monthly report** | A summary each month | None |
| **Traffic spike** | An alert when visitors online pass a number, at most every 12 hours | **Visitors**, 10 by default |
| **No traffic** | One alert after a number of hours without a pageview, until traffic returns | **Hours**, 1 to 168, 12 by default |

**Preview report** opens the weekly report, or the monthly one when **Kind** is **Monthly
report**, as it would be sent now. **Send a test** emails it. Reports need an email
provider on the Worker ([Configuration](configuration.md)). [Email reports and alerts](reports.md)
covers reports and alerts in depth.

### Integrations

**Integrations** holds three cards.

**Connect AI tools (MCP)** connects Claude, Cursor, or another MCP client. If you have no
key for the site yet, select **Create API key for** and the site's name. The key reads
only this site, and the dashboard shows it once. The card then fills the key into a
`claude mcp add` command and a JSON config to copy. **Rotate** gives an existing key a
new secret, and you select it twice to confirm. Tools that use the old secret stop
working. See [Ask AI tools about your traffic](mcp.md).

**Import history** brings in data from before misomoon:

- **Upload CSV or zip** takes a CSV export, as a zip or as its CSV files.
- **Connect Google** signs in to Google. Then pick a **Google property**, optionally the
  dates, and select **Import**. Without dates, the import runs up to yesterday. Import only
  the days before you added misomoon, or they count twice.

The list shows each import with its status, its dates, and its row count, and a button to
delete it.

**Google Search Console** adds the Google searches that bring people to the site. Select
**Connect Search Console**, pick the property, and select **Connect**. The searches then
show under **Where they come from** > **Search terms**. Google reports searches about two
days late. To disconnect, select the delete button next to the property.
[Bring your history](import.md) covers imports and Search Console.

### Revenue

**Revenue** connects a payment provider, so each payment shows under the source,
campaign, country, and device that brought the buyer. Pick the provider: **Stripe**,
**Polar**, **Lemon Squeezy**, **Dodo Payments**, or **Your server**. The card then lists
the steps for it:

1. Copy the webhook URL into the provider.
2. Send the events that the card lists.
3. Add the signing secret. For Stripe, Polar, and Dodo Payments, paste the provider's
   secret and select **Save**. For Lemon Squeezy and your own server, select **Make
   signing secret** and copy the secret, which shows once.

The status then reads **Waiting**, **Live**, or **Problem**, with the last event or
error. **Disconnect** removes the provider. When payments came in during the last 30
days, the card shows how many there were and how many it linked to a visit.
[Connect payments](revenue.md) covers each provider and the checkout ref.

### Team

**Team** manages the people on the team that owns the open site. Everyone on a team
holds one role on all of its sites. A guest sees one site only.

- To rename the team, edit the name and select **Rename**.
- To change someone's role, pick it from the menu next to their name. Only an owner can
  make someone an owner or change another owner.
- To remove someone, select the delete button next to their name. On your own row, the
  same button leaves the team.
- Guests on the open site and pending invitations show in the same list. You can change a
  guest's role, remove a guest, or withdraw an invitation.

To invite someone:

1. Type their email address.
2. Pick **Access to**: **Whole team**, or **Only** and the site's name for a guest.
3. Pick a **Role**.
4. Select **Invite**.

The dashboard shows the invitation link to copy. If the Worker can send email, it also
emails the link. The link works for 7 days. [Work with your team](teams.md) covers roles and
invitations.

### Sites

**Sites** holds up to three cards:

- The open site's details, for roles that can edit: **Name**, **Timezone**, and **Revenue
  currency**. Select **Save** to apply them. The timezone sets where each day starts and
  ends in your reports.
- **Your sites** lists every site you can see, with **Open** to switch to it. Under it,
  **Add a site** takes a domain. The dashboard guesses the timezone and the currency.
  Select **Change** to set them, or to pick the team when you belong to more than one.
  Select **Add site**, and the dashboard opens **Install** for the new site.
- **Danger zone**, or **Leave** for roles that can't manage, holds the actions you can't
  undo. An owner can move the site to another team where they are an owner or an admin.
  Owners and admins can delete the site after they type its domain. Anyone except an
  owner can leave the team, or leave the site when they are a guest.

The dashboard has no control to make a site public or to set its daily cap. Set `public`
through the [Sites API](api.md#sites), and the cap as
[Daily ingest cap](configuration.md#daily-ingest-cap) describes.

### Account

**Account** shows the email you signed in with and your role on the open site.

- To change your name, edit it and select **Save**.
- To change your password, type the current one and a new one of at least 10
  characters, and select **Save**.
- **Sign out** ends your session.
- **API keys** lists your keys, with the site each one reads or **all your sites**, and
  when each was last used. Select the delete button to revoke a key. A key acts with your
  role, so it loses access when you do.
- **Delete account…** asks for your password, then deletes your account
  ([Delete your account](teams.md#delete-your-account)).

When you are signed out, **Account** shows **Sign in or create an account**.
[Work with your team](teams.md) covers accounts and API keys.

## Use keyboard shortcuts

The shortcuts work anywhere in the dashboard, except while you type in a field.

| Keys | Action |
| --- | --- |
| `⌘` `K` on macOS, `Ctrl` `K` elsewhere | Open or close the command palette |
| `1` to `7` | Open **Overview**, **Live**, **Funnels**, **Paths**, **Behavior**, **Speed**, or **Settings** |
| `D`, `E`, `H`, `W`, `F`, `T`, `N`, `M`, `L`, `Y`, `S`, `Z`, `A` | Pick a period, as [Pick a period](#pick-a-period) lists. Works where the period controls show. |
| `Esc` | Close the open menu or window. With none open, remove the last filter. |

The command palette runs any of these commands by name. Type to narrow the list, move
with the arrow keys, and press `Enter` to run the highlighted command. `Esc` closes the
palette.

| Group | Commands |
| --- | --- |
| Go to | Each view |
| Period | Each period in the period menu |
| Switch site | Each site you can see |
| Actions | **Compare with previous period**, or **Hide comparison** while a comparison is on. **Clear all filters**. **Switch to night theme**, or **Switch to day theme**. |

## Link to a view

The dashboard keeps the URL in step with what you look at. Copy the URL to share the
exact view, period, and filters with someone who can open the site. The dashboard leaves
out a parameter that has its default value, and falls back to the default for a value it
doesn't accept.

| Parameter | Values | Default | Example |
| --- | --- | --- | --- |
| `site` | A site id | The demo site when you can see it, otherwise your first site | `site=shop` |
| `view` | `overview`, `realtime`, `funnels`, `journeys`, `behavior`, `vitals`, `settings` | `overview` | `view=vitals` |
| `tab` | `install`, `goals`, `sharing`, `connect`, `revenue`, `team`, `sites`, `account`. Used only with `view=settings`. | The first tab you can see | `view=settings&tab=goals` |
| `period` | A period from the [period table](#pick-a-period), or `custom` | `30d` | `period=7d` |
| `from`, `to` | Dates as `YYYY-MM-DD`, at most 400 days apart. Used only with `period=custom`. | None | `period=custom&from=2026-09-01&to=2026-09-30` |
| `f` | Filters, in the format below | None | `f=page~/blog` |
| `compare` | `0` for off, `year` for last year | The previous period | `compare=year` |
| `metric` | A `metric` value from the [tile table](#pick-a-metric-on-the-chart) | `visitors` | `metric=bounce_rate` |
| `imported` | `0` leaves imported history out | Included | `imported=0` |

Each filter in `f` is a dimension id, an operator from the [operator table](#build-a-filter),
and one or more values. A semicolon separates two filters, and a pipe separates two values
of one filter. This value keeps visits from Germany or France to pages that contain
`/blog`:

```text
f=country==DE|FR;page~/blog
```

The dimension ids are `page`, `entry_page`, `exit_page`, `hostname`, `channel`,
`source`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`,
`utm_content`, `country`, `region`, `city`, `continent`, `timezone`, `network`,
`browser`, `browser_version`, `os`, `os_version`, `device`, `screen`, `language`,
`goal`, `event`, and `prop:` followed by a property name. Encode the value when you build
the URL by hand. The Stats API reads the same grammar ([API](api.md)).

Three paths open something other than the dashboard:

| Path | Opens |
| --- | --- |
| `/share/<slug>` | A shared link, as [Open a shared or public dashboard](#open-a-shared-or-public-dashboard) describes |
| `/invite/<token>` | An invitation from an email, on the sign-in screen |
| `/reset/<token>` | A password reset from an email, on the sign-in screen |

## Open a shared or public dashboard

A shared link opens the site's dashboard read-only at `/share/<slug>`. If the link has a
password, the dashboard asks for it first. After that, the browser tab stays unlocked for
up to 7 days, or until the link expires if that comes first. Once the link expires or
is deleted, the dashboard shows an error that says the link has expired or was removed.

A viewer on a shared link sees every view except **Settings**, and the sidebar reads
**Shared, read-only view**. They can change the period, compare, filter, and export,
but they can't add notes, save segments, or save funnels. When the link is limited to a
segment, the server applies the segment's filters to every number. A filter of the
viewer's own on the same dimension is ignored.

A public site opens read-only for signed-out visitors, the way the demo does. The site
menu lists the public sites, and the sidebar shows a **Sign in** button. Once you sign in,
the site menu lists only the sites where you have a role.
[Share a dashboard](sharing.md) covers shared links and public sites.

---

# Goals, funnels, and paths

An event is what your page sends: a pageview, or a custom event such as `Signup` that
you send with `misomoon()` ([Send custom events](tracking.md#send-custom-events)). A goal
marks one event name or one page path as a conversion. misomoon then counts how many
visitors reached it and what share of all visitors they are.

Goals, funnels, and paths read the events you already collected. A new goal shows
numbers for past periods right away, and deleting a goal deletes no data.

## Create a goal

An event goal counts the visitors who sent an event with a given name. To create one in
the dashboard:

1. Open **Settings** and pick the **Goals** tab.
2. In **Goal type**, pick **Event**.
3. Type the event name exactly as your page sends it, such as `Signup`.
4. To show a different name in reports, type it in the label field. Without a label, the
   goal takes the event name.
5. Click **Add**.

You need the editor role or above on the site: owner, admin, editor, or guest editor.
Viewers see the list of goals without the form.

To create the same goal with the API, send `kind`, `match`, and an optional `name`:

```sh
curl -X POST "https://analytics.example.com/api/v1/sites/shop/goals" \
	-H "Authorization: Bearer $MISOMOON_KEY" -H "Content-Type: application/json" \
	-d '{"kind": "event", "match": "Signup", "name": "Signed up"}'
```

The API returns `201` with the goal's `id`, `site_id`, `name`, `kind`, and `match`.

A goal has no edit action. To change a goal, delete it with the trash icon next to it,
or with `DELETE /api/v1/sites/:id/goals/:goal`, and add it again.

## Count a page as a goal

A page goal counts the visitors who opened a page, such as a thank-you page after a
checkout.

1. Open **Settings** and pick the **Goals** tab.
2. In **Goal type**, pick **Page**.
3. Type the path, such as `/thanks`. To match many pages, use `*`, such as `/docs/*`.
4. Click **Add**.

Write the path the way misomoon stores it, without the domain, the query string, or a
trailing slash. `/thanks/` never matches, because the page is stored as `/thanks`.
[Matching rules](#matching-rules) lists what `*` matches.

With the API, send `"kind": "page"` and the path in `match`.

## Read conversion rates

Open **Overview** and find the **What they did** panel. It has three tabs:

- **Goals** lists each goal with its **Rate** and the number of **People** who reached
  it. An event goal that carries revenue shows the amount next to its name.
- **Events** lists every event name with how many **Times** it was sent, its **Rate**,
  and its **People**, whether or not it is a goal.
- **Details sent** lists the custom properties of your events as `key: value` rows, with
  the same columns as **Events**.

To see the whole dashboard for the visitors who converted, click a goal's row. The
dashboard adds the filter `goal==<name>`, and every panel then counts only visitors who
reached that goal. Click the row again to remove the filter.

The rate is the share of visitors in the period who reached the goal.
[Conversion rate](#conversion-rate) explains what it divides by. For how misomoon counts
a unique visitor, see [What the numbers mean](metrics.md).

## Build a funnel

A funnel is an ordered list of 2 to 8 steps. It shows how many visitors reached each step
and how many dropped out between steps.

1. Open **Funnels**.
2. To start a new funnel, click the **+** button next to **Saved**. The builder starts
   with two page steps, `/` and `/pricing`.
3. For each step, pick **Visits page** or **Triggers event**.
4. Type a path, such as `/pricing` or `/blog/*`, or an event name, such as `Signup`.
5. To add a step, click **Add step**. To remove a step, click its trash icon.
6. In **Funnel type**, pick **Sequential**, **Strict**, or **Flexible**.
   [Funnel modes](#funnel-modes) says what each one counts.

The chart updates while you edit. It uses the period and the filters at the top of the
dashboard. A filter applies to every event the steps look at, so a page or event filter
usually leaves only one step with visitors.

Anyone who can read the site can build and run a funnel. Saving needs the editor role or
above.

## Save a funnel

1. Type a name in **Funnel name**. Without a name, the funnel is saved as
   `Untitled funnel`.
2. Click **Save funnel**.

The funnel appears under **Saved** with its number of steps. When you open **Funnels**,
the first saved funnel opens.

To change a saved funnel, click it under **Saved**, edit its name, steps, or type, and
click **Save changes**.

To delete a saved funnel, open it and click **Delete**. Then click **Click again to
delete**. To cancel, click **Keep it**.

To save a funnel with the API, send `name`, `steps`, and `mode`:

```sh
curl -X POST "https://analytics.example.com/api/v1/sites/shop/funnels" \
	-H "Authorization: Bearer $MISOMOON_KEY" -H "Content-Type: application/json" \
	-d '{"name": "Pricing to signup", "mode": "sequential", "steps": [{"kind": "page", "match": "/pricing"}, {"kind": "event", "match": "Signup", "label": "Signed up"}]}'
```

The API returns `201` with the funnel's `id`, `name`, `steps`, and `mode`. To change it,
send the same body to `PUT /api/v1/sites/shop/funnels/<id>`. A step `label` replaces the
step's name in the chart. The dashboard has no field for it, so set it through the API.

To run a saved funnel through the API, send its id as `funnel` instead of `steps`:

```sh
curl -X POST "https://analytics.example.com/api/v1/stats/funnel" \
	-H "Authorization: Bearer $MISOMOON_KEY" -H "Content-Type: application/json" \
	-d '{"site": "shop", "period": "30d", "funnel": "<funnel id>"}'
```

When the body has both `steps` and `funnel`, misomoon runs the `steps`. A `mode` in the
body replaces the saved mode.

## Find where people drop out

Above the chart, the funnel shows three numbers:

- **Converted** is the share of the first step's visitors who reached the last step.
- **Completed** is the number of visitors who reached the last step.
- **Of all visitors** is **Completed** divided by every visitor who sent a pageview or
  an event in the period, after the filters.

Each step has a column. The solid bar is the step's visitors, and the percent on it is
their share of the first step. The hatched area behind the bar is the step before it, so
the gap between the two is the drop-off. Under each step after the first, `−N dropped`
gives the number of visitors who reached the step before but not this one.

A step without a label is named after its match. Page steps read `Visit /pricing`, and
event steps read the event name.

## See where people go after a page

1. Open **Paths**. **Where they go next** is selected.
2. The first column, **Entry pages**, lists the pages visits start on. Click a page.
3. A new column, **After /page**, lists the pages visitors opened next. Click one of them
   to follow the path one more page.

Each row shows the share of the path's visitors who went to that page, and the number of
visitors. The row `(exit)` means the visit ended there. You can't click `(exit)`.

You can follow a path for up to 6 pages. To change an earlier page, click another row in
its column. The columns after it go away. To clear the path, click **Start over**.

After you pick a page, the next column counts every visit that opened it, at any point
in the visit, and not only visits that started on it. To start from a page that isn't in
**Entry pages**, call the API with that page in `path`:

```sh
curl -H "Authorization: Bearer $MISOMOON_KEY" "https://analytics.example.com/api/v1/stats/journeys?site=shop&period=30d&path=/pricing&direction=forward"
```

## See how people reached a page

1. Open **Paths** and click **How they got there**.
2. The first column, **Exit pages**, lists the pages visits end on. Click a page.
3. A new column, **Before /page**, lists the pages visitors opened just before it. Click
   one to go one more page back.

The row `(entrance)` means the visit started on the page. Switching between **Where they
go next** and **How they got there** clears the path.

With the API, send `direction=backward`. Send `path` in visit order, so the page you
start from is last.

## Count revenue with goals

An event goal adds up the revenue its events carry. In **What they did** > **Goals**, a
goal with revenue shows the amount next to its name. The API returns it as `revenue` and
`average_revenue` on each goal row.

Page goals never carry revenue, because a visitor who opened the page may have paid
somewhere else. To count revenue, make the goal on the event that carries it.

To send revenue with an event, see [Track revenue](tracking.md#track-revenue). Payments
from a connected provider arrive as `Payment` events, so a goal on `Payment` counts the
visitors who paid ([Connect payments](revenue.md)). [Read revenue on the
dashboard](revenue.md#read-revenue-on-the-dashboard) says where else revenue shows.

## Use the API and MCP

The dashboard, the API, and the MCP server run the same queries. [API reference](api.md)
covers authentication and the query parameters, and [MCP](mcp.md) covers connecting a
client.

| Task | API | MCP tool |
| --- | --- | --- |
| List, create, or delete goals | `GET`, `POST /api/v1/sites/:id/goals`, `DELETE /api/v1/sites/:id/goals/:goal` | None |
| Read goal conversions | `GET /api/v1/stats/breakdown?property=goal` | `get_goal_conversions` |
| Download goal conversions | `GET /api/v1/stats/export`, the file `conversions.csv` in the ZIP | None |
| List, save, change, or delete funnels | `GET`, `POST /api/v1/sites/:id/funnels`, `PUT`, `DELETE /api/v1/sites/:id/funnels/:funnel` | None |
| Run a funnel | `POST /api/v1/stats/funnel` with `steps` or a saved `funnel` id | `run_funnel`, with `steps` only |
| Follow a path | `GET /api/v1/stats/journeys` | `get_journeys` |

## Reference

### Matching rules

misomoon stores each page as its path, without the query string and without a trailing
slash, except for `/` itself. With `data-hash` on the script tag, a hash route is part of
the path, such as `/#/pricing`. A part of the path that looks like an email address is
stored as `:email`, and a part of 20 or more letters and digits is stored as `:token`.

| Where | A value without `*` | A value with `*` |
| --- | --- | --- |
| Page goal | Matches the path exactly. Case matters. | `*` matches any characters, `/` included. Letters match in either case. |
| Event goal | Matches the event name exactly. Case matters. | `*` matches any characters. Letters match in either case. |
| Funnel page step | Matches the path. Letters match in either case. | `*` matches any characters, `/` included. |
| Funnel event step | Matches the event name exactly. Case matters. | `*` is a plain character, not a wildcard. |
| Paths `path` | Matches the page exactly. Case matters. | `*` is a plain character, not a wildcard. |

Examples for page goals:

| Match | Matches | Doesn't match |
| --- | --- | --- |
| `/thanks` | `/thanks` | `/thanks/order`, `/Thanks` |
| `/docs/*` | `/docs/setup`, `/docs/api/keys` | `/docs` |
| `/docs*` | `/docs`, `/docs/setup`, `/docsearch` | `/blog/docs` |

### Conversion rate

A goal's conversion rate is the number of visitors who reached the goal divided by the
number of visitors in the period, as a percent with one decimal. A visitor counts once
per goal, however many times they reach it.

The visitors you divide by follow the dashboard filters, except goal, event, and
property filters. With the filter `country==DE`, the rate is the share of visitors from
Germany who reached the goal.

Each goal row in the API also has `events`. For an event goal, `events` is how many times
the event was sent. For a page goal, it is the number of pageviews of matching pages.

Goals count only the events misomoon collected, not imported history. On a period that
includes imported history, the visitors you divide by include the imported visitors, so
the rate reads lower. To leave imported history out of an API query, send `imported=0`.

### Funnel modes

| Mode | A visitor reaches a step when |
| --- | --- |
| `sequential` | They did the earlier steps in order and then this one. Other pages and events may come between steps. This mode is the default. |
| `strict` | Their very next pageview or event after the previous step matches this step. Any pageview or event in between, including the ones the tracker sends by itself, breaks the funnel. |
| `flexible` | The middle steps count as in `sequential`. The last step counts every visitor who did the first step and the last step later, whatever they did in between. |

In `flexible` mode with more than two steps, the last step can have more visitors than
the step before it. The drop-off for the last step then shows as zero.

A funnel counts visitors, and a visitor id lasts one UTC day. The steps of one visitor
must happen on the same UTC day, but they can span several visits on that day. Every
step's percent is a share of the first step's visitors.

### Paths

- Paths count pageviews only, in the order of one visit. Reloads of the same page count
  as one page.
- A path matches pages that follow each other in a visit. When a path appears more than
  once in a visit, misomoon uses the first time.
- With no path, forward lists the pages visits start on, and backward lists the pages
  visits end on.
- `(exit)` means the visit ended after the path. `(entrance)` means the visit started
  with it.
- Each row's share is a percent of the visitors who followed the path. Rows past the
  limit are left out. There is no row that groups the rest.
- Filters at the top of the dashboard apply to every page in the path. A page filter
  keeps only the pages it matches.

### Limits

- A site has at most 50 goals. Adding one more returns `400` with
  `a site has at most 50 goals`.
- A goal name is unique on its site. A second goal with the same name returns `409`
  with `a goal with this name already exists`.
- A goal name keeps its first 80 characters, and a goal `match` keeps its first 200.
- A goal filter names goals by their name. A name that doesn't exist returns `400`, and
  one filter can't mix page goals and event goals.
- A funnel has 2 to 8 steps. Running a funnel with more than 8 returns `400` with
  `a funnel has 2 to 8 steps`. Saving a funnel with more than 8 keeps the first 8.
- A funnel name keeps its first 80 characters, a step `match` its first 200, and a step
  `label` its first 80. Two saved funnels can have the same name.
- A path holds up to 6 pages, and each page keeps its first 500 characters. `limit` takes
  1 to 50 rows and defaults to 12. The dashboard shows 12 rows per column, and
  `get_journeys` has no `limit`.
- Funnels and paths read only the events misomoon collected, not imported history.
- Reading goals, saved funnels, funnels, and paths needs read access to the site. A
  public site or a shared link gives that access. Creating and deleting goals, and saving,
  changing, and deleting funnels, need the editor role or above.

---

# Connect payments

This guide sends payments from Stripe, Polar, Lemon Squeezy, Dodo Payments, or your own
server to misomoon. Each payment then counts toward the source, campaign, country, and
device of the visit that brought the buyer. Renewals and refunds count toward that same
visit. You don't need cookies for any of this.

## How a payment finds its visit

The tracker sets no cookies, so misomoon can't recognise a buyer by a stored id. The
checkout carries a reference from the visit to the payment instead:

1. On your site, the tracker makes a ref such as `mm_3f9c0a…` and records it with the
   visit's source, country, and device.
2. The ref travels into the checkout: in a payment-link URL, or in the metadata of a
   checkout that your server creates.
3. The payment provider sends the ref back to misomoon in its webhook. misomoon finds the
   visit by the ref and writes a `Payment` event with that visit's details.

A payment can also find its visit by the checkout id on your success page. Stripe adds
`session_id`, Polar adds `checkout_id`, and Dodo Payments adds `payment_id` or
`subscription_id` to the return URL. When the tracker counts that page, the server reads
the id from its URL and records it with the visit.

The order of events doesn't matter. If the webhook arrives first, misomoon stores the
payment and credits it when the ref or the id turns up. A payment always ends up with its
strongest key: its own ref beats the success page, and both beat the buyer's earlier
purchases. A refund follows its payment.

Once a payment has a visit, misomoon remembers its subscription and customer for 400
days. A renewal a year later still counts toward the visit that started the
subscription. A ref or a checkout id is kept for 30 days.

A payment that finds no visit still counts toward total revenue. Reports list it under
**Unknown**.

## Connect a provider

1. Open **Settings** > **Revenue** and pick your provider.
2. Copy the webhook URL. It looks like `https://analytics.example.com/api/webhooks/stripe/shop`:
   `/api/webhooks/<provider id>/<site id>`, with the provider ids in the table below.
3. In the provider's dashboard, add a webhook endpoint with that URL and the events below.
4. Save the signing secret. For Stripe, Polar, and Dodo Payments, paste their secret into
   misomoon. For Lemon Squeezy and your own server, click **Make signing secret** in
   misomoon and paste it into the provider.

Connecting a provider ticks **Payments** under **Settings** > **Install** > **What to
track**. That feature tags payment links, hands out `misomoon.ref()`, and reads checkout
ids from success pages. Without it, `misomoon.ref()` returns `undefined`, so a checkout
gets no ref but still works.

| Provider | Id | Where to add the webhook | Events |
| --- | --- | --- | --- |
| Stripe | `stripe` | **Developers** > **Webhooks** | `checkout.session.completed`, `checkout.session.async_payment_succeeded`, `invoice.paid`, `refund.created` |
| Polar | `polar` | **Settings** > **Webhooks**, format **Raw** | `order.paid`, `refund.created`, `refund.updated` |
| Lemon Squeezy | `lemonsqueezy` | **Settings** > **Webhooks** | `order_created`, `order_refunded`, `subscription_created`, `subscription_payment_success`, `subscription_payment_refunded` |
| Dodo Payments | `dodo` | **Developer** > **Webhooks** | `payment.succeeded`, `refund.succeeded` |
| Your server | `custom` | Your own code ([Send payments from your own server](#send-payments-from-your-own-server)) | Payments and refunds |

**Settings** > **Revenue** shows the time of the last event. If a webhook fails its
signature check, the page shows the error. Test-mode payments from Stripe and Lemon
Squeezy mark the connection as working but don't count toward revenue.

## Pass the ref to the checkout

If you use payment links, you don't need to change anything. When a visitor clicks a
link to `buy.stripe.com`, `buy.polar.sh`, a Lemon Squeezy checkout, or
`checkout.dodopayments.com`, the tracker adds the ref to the link's URL. A link that
already carries its own `client_reference_id` keeps it.

If your server creates the checkout, get the ref in the browser with `misomoon.ref()`,
send it to your server, and put it in the checkout's metadata as `misomoon_ref`:

```js
// in the browser
const ref = misomoon.ref()
await fetch('/api/checkout', { method: 'POST', body: JSON.stringify({ plan, ref }) })
```

```js
// Stripe, on your server
stripe.checkout.sessions.create({
	// your line items
	metadata: { misomoon_ref: ref },
	subscription_data: { metadata: { misomoon_ref: ref } },
	success_url: 'https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}',
})
```

| Provider | Where the ref goes |
| --- | --- |
| Stripe | `metadata.misomoon_ref`, or `client_reference_id` |
| Polar | `metadata.misomoon_ref`. Add `?checkout_id={CHECKOUT_ID}` to the success URL. |
| Lemon Squeezy | `checkout_data.custom.misomoon_ref` |
| Dodo Payments | `metadata.misomoon_ref` |

In a bundled app, `ref()` from `@misomoon/sdk/web` waits for the tracker and returns the
same ref. A React Native app gets one from `misomoon.ref()`. Your server can also make
the ref from the visitor's request with the Node SDK, so the browser sends nothing extra.
The [SDK guide](sdk.md#pass-the-visit-to-a-checkout-your-server-creates) shows all three.

`misomoon.ref()` returns the same ref for the whole page view and a new one after the
next page view. If the tracker isn't loaded, for example because an ad blocker stopped
it, guard the call: `window.misomoon?.ref?.()`. A checkout without a ref still works.

To turn off the link tagging on some pages, add `data-disable="payments"` to the script
tag there. `misomoon.ref()` keeps working. To turn off the success-page ids too, untick
**Payments**.

## Send payments from your own server

For a WooCommerce store, the WordPress plugin sends orders and refunds to the custom
webhook for you ([Count WooCommerce orders](wordpress.md#count-woocommerce-orders)).

For a provider that misomoon doesn't support, post each payment to the custom webhook
URL. From Node, Bun, Deno, or Workers, `payment()` in the SDK signs and retries the
request for you ([Send payments from providers without a webhook](sdk.md#send-payments-from-providers-without-a-webhook)).
From another language, sign the request with one of these headers:

- `Authorization: Bearer <secret>`
- `X-Misomoon-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the secret>`

```sh
curl -X POST "https://analytics.example.com/api/webhooks/custom/shop" \
	-H "Authorization: Bearer $MISOMOON_WEBHOOK_SECRET" -H "Content-Type: application/json" \
	-d '{"id": "order_1042", "amount": 49.9, "currency": "EUR", "ref": "mm_3f9c0a…", "customer": "cus_77"}'
```

| Field | Meaning |
| --- | --- |
| `id` | Your payment id, unique per site. Required. A second request with the same id is ignored, so retries are safe. |
| `amount` | Positive, in major units: `49.9` for 49.90. Required. |
| `currency` | ISO 4217 code. Required. |
| `type` | `payment` (the default) or `refund`. |
| `refund_of` | For a refund, the `id` of the payment it returns. Required for refunds. |
| `ref` | The value of `misomoon.ref()` from the buyer's visit. |
| `customer`, `subscription` | Your ids. A later payment with the same customer or subscription counts toward the first payment's visit. |
| `billing` | `new`, `renewal`, or `one_time`. Defaults to `renewal` when `subscription` is set. |
| `ts` | When the payment happened: Unix seconds, milliseconds, or an ISO 8601 string. Defaults to now. |
| `test` | `true` to check the connection without counting the payment. |

The response is `{"ok": true, "counted": 1}`. A malformed body returns `400` with the
reason, and a bad signature returns `401`.

## Read revenue on the dashboard

Payments are events named `Payment` and refunds are events named `Refund`, with a
negative amount. Each event has the props `provider` and `billing`. They appear in
**What they did**, and the revenue they carry shows next to each source, country, and
device. To see revenue for one provider, filter by the prop `provider`.

Totals count only payments in the site's currency, the same rule as for
[revenue events](tracking.md#track-revenue). Payments in other currencies are stored but
left out, because misomoon doesn't convert currencies.

## Limits

- A visit and a payment are linked only through a ref, a checkout id, or a subscription
  or customer that an earlier payment already linked. misomoon never matches by email or
  IP address.
- A payment on a later day than its visit counts toward that visit's source, country, and
  device. It doesn't count toward the visit's unique visitors, because visitor ids change
  every day.
- Test mode is detected for Stripe and Lemon Squeezy. Use a separate site for test
  webhooks from Polar and Dodo Payments.

---

# Track apps and servers with the SDK

`@misomoon/sdk` sends events from places a script tag can't reach: React Native and
Expo apps, and your own server. It also has a typed wrapper for the browser tracker, for
React, Next.js and other bundled apps.

| Import | Use it for |
| --- | --- |
| `@misomoon/sdk/web` | Any bundled browser app. Loads `m.js` and gives you typed `track()` and `pageview()`. |
| `@misomoon/sdk/react` | React and Next.js: a `<Misomoon>` component and a `useMisomoon()` hook. |
| `@misomoon/sdk/next` | Next.js config: `withMisomoon()` serves the tracker from your own domain. |
| `@misomoon/sdk/react-native` | React Native and Expo: screens, engaged time, custom events, and revenue. |
| `@misomoon/sdk/node` | Server-side events in Node, Bun, Deno, and Workers: signups, payments, webhooks. |

Install it:

```sh
npm install @misomoon/sdk
```

The package ships ESM and CommonJS. It has no dependencies. React and React Native are optional peer
dependencies.

Like the script tag, the SDK sets no cookies and stores nothing on the device. The
server derives the visitor id from the address, the user agent, and a salt that changes
daily, as [Architecture](ARCHITECTURE.md#ingest) explains. An app therefore needs no
AsyncStorage and no consent prompt for an identifier.

## Add the tracker to a React or Next.js app

Put `<Misomoon>` once in your root layout. It renders nothing and adds `m.js` when the
page loads:

```tsx
// app/layout.tsx
import { Misomoon } from '@misomoon/sdk/react'

export default function RootLayout({ children }: { children: React.ReactNode }) {
	return (
		<html lang="en">
			<body>
				{children}
				<Misomoon site="your-site" host="https://analytics.example.com" />
			</body>
		</html>
	)
}
```

The App Router and React Router change routes with `history.pushState`, and `m.js`
counts each change as a pageview, so routing needs nothing more.

Send events from any component:

```tsx
'use client'
import { useMisomoon } from '@misomoon/sdk/react'

export function UpgradeButton() {
	const { track } = useMisomoon()
	return <button onClick={() => track('Upgrade', { props: { plan: 'pro' } })}>Upgrade</button>
}
```

### Serve the tracker from your Next.js app

Ad blockers drop requests to analytics hosts. `withMisomoon()` adds rewrites to your
Next.js config, so the tracker and its events go through your own domain:

```js
// next.config.mjs
import { withMisomoon } from '@misomoon/sdk/next'

export default withMisomoon({ reactStrictMode: true }, { host: 'https://analytics.example.com' })
```

Then set `host` to the proxy path:

```tsx
<Misomoon site="your-site" host="/relay" />
```

`withMisomoon()` maps `/relay/m.js`, `/relay/api/event`, and `/relay/overlay.js` to
`host`, before your own pages and files, and keeps any rewrites your config already has.
It also wraps a config that you export as a function. To use another path, pass
`prefix: '/pulse'`. Pick a neutral word: `analytics`, `tracking`, and `stats` are on
filter lists. `host` must be a full URL, or the build fails with an error.

misomoon counts each visitor by the address that a rewrite forwards in
`X-Forwarded-For`. Vercel and Netlify set it. A self-hosted Next.js server passes on the
header it receives, so put it behind a proxy that sets the header, such as Nginx with
`proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for`. A bare `next start` that
faces the internet sets no such header, so every visitor arrives with the server's
address.
[Serve the tracker from your own domain](PROXY.md#visitor-ip-and-location) explains which visitor locations survive
the proxy on each platform.

### Type your events

Pass your events and their props to `useMisomoon()`. A misspelled name or a prop value
that isn't in the type then fails the type check:

```tsx
type Events = { Signup: { plan: 'pro' | 'team' }; Logout: undefined }

const { track } = useMisomoon<Events>()
track('Signup', { props: { plan: 'pro' } })
```

Declare the events with `type`, not `interface`: TypeScript doesn't match an interface to
the props type. Outside React, `typed<Events>()` from `@misomoon/sdk/web` returns the
same typed functions.

### Turn tracking off in development

`enabled: false` adds no tracker and sends nothing. Calls to `track()` still run their
`callback`:

```tsx
<Misomoon site="your-site" host="/relay" enabled={process.env.NODE_ENV === 'production'} />
```

To leave your own browser out of the counts, call `ignore()` from
`@misomoon/sdk/web`, for example from an admin page. It takes effect on the next page
load. `ignore(false)` counts the browser again. It sets the same `misomoon_ignore` key as
the [console command](tracking.md#exclude-yourself).

Without React, call the functions from `@misomoon/sdk/web`:

```ts
import { init, track } from '@misomoon/sdk/web'

init({ site: 'your-site', host: 'https://analytics.example.com' })
track('Signup', { props: { plan: 'pro' } })
track('Purchase', { revenue: { amount: 49.9, currency: 'EUR' } })
```

The functions do nothing during server rendering, so you can import them anywhere.
Calls made before `m.js` loads wait in a queue, and `m.js` sends them after the first
pageview, so the visit keeps its referrer.
A `callback` passed to `track()` runs after the event is sent, or after one second when
an ad blocker stops `m.js` from loading, so a navigation that waits for it still happens.

`init()` takes the [script tag attributes](configuration.md#tracker-attributes) as
options:

| Option | Attribute |
| --- | --- |
| `site` | `?s=` on the script URL |
| `host` | where events go, and the script's `src` (`<host>/m.js`) unless you set `src` |
| `src` | the tracker's URL, when it isn't `<host>/m.js`; events still go to `host` |
| `api` | `data-api` |
| `manual`, `hash` | `data-manual`, `data-hash` |
| `debug` | none: logs what the SDK does |
| `disable: ['outbound', 'downloads', 'clicks']` | `data-disable` |
| `props: { plan: 'pro' }` | `data-prop-plan="pro"` |
| `downloadExtensions` | `data-download-ext` |
| `enabled` | none: `false` adds no tracker |

To serve the tracker from your own domain, set `host` to your proxy path, such as
`host: '/relay'`. [Serve the tracker from your own domain](PROXY.md) shows the proxy setups.

### Pass the visit to a checkout from the browser

To credit a payment to the visit that made it, give the checkout your server creates the
page view's ref. `ref()` waits up to 3 seconds for `m.js` to load, then resolves to the
ref:

```ts
import { ref } from '@misomoon/sdk/web'

const res = await fetch('/api/checkout', { method: 'POST', body: JSON.stringify({ plan, ref: await ref() }) })
```

In React, `ref` comes from `useMisomoon()`. `ref()` resolves to `undefined` when an ad
blocker stops `m.js`, when `enabled` is `false`, or when the site's **Payments** feature
is off. A checkout without a ref still works, but its payment counts under **Unknown**.
[Connect payments](revenue.md#pass-the-ref-to-the-checkout) shows where each provider
keeps the ref.

## Track a React Native or Expo app

Wrap the app in `MisomoonProvider`. Set `domain` to the domain you added to misomoon for
this app. Each screen becomes a pageview at `https://<domain>/<screen>`, so screens show
up as pages in the dashboard.

```tsx
import { MisomoonProvider } from '@misomoon/sdk/react-native'

export default function App() {
	return (
		<MisomoonProvider
			site="recipes-app"
			host="https://analytics.example.com"
			domain="recipes.app"
			app={{ name: 'Recipes', version: '2.3.0' }}
		>
			<RootNavigator />
		</MisomoonProvider>
	)
}
```

The `app` name and version take the place of the browser in reports. The OS, its
version, and phone or tablet come from the device.

### Count screens

With Expo Router, pass the current path to `useScreen` in the root layout:

```tsx
// app/_layout.tsx
import { Stack, usePathname } from 'expo-router'
import { useScreen } from '@misomoon/sdk/react-native'

function Screens() {
	useScreen(usePathname())
	return <Stack />
}
```

Render `<Screens />` inside `MisomoonProvider`.

With React Navigation, spread `useNavigationTracking` on the container. It returns the
`onReady` and `onStateChange` callbacks, so the first screen counts too:

```tsx
import { createNavigationContainerRef, NavigationContainer } from '@react-navigation/native'
import { useNavigationTracking } from '@misomoon/sdk/react-native'

const navigationRef = createNavigationContainerRef()

function Navigation() {
	const tracking = useNavigationTracking(navigationRef)
	return <NavigationContainer ref={navigationRef} {...tracking}>{/* screens */}</NavigationContainer>
}
```

To count one screen by hand, call `useScreen('Settings')` in it. A repeat of the current
screen isn't counted twice, so re-renders and StrictMode are safe.

### Send events

```tsx
import { useMisomoon } from '@misomoon/sdk/react-native'

function BuyButton() {
	const misomoon = useMisomoon()
	return <Button title="Buy" onPress={() => misomoon.track('Purchase', { revenue: { amount: 4.99, currency: 'USD' } })} />
}
```

### Credit campaigns from links

When a link opens the app, the visit gets the link's campaign. The SDK reads the link
from React Native's `Linking` by itself, so Expo Router and React Navigation apps need no
code. The link's `utm_*`, `gclid`, `msclkid`, `ref`, and `source` parameters go on the
visit's first screen view, and other parameters are left out.

misomoon takes a visit's traffic source from its first event, so a new visit waits for
the link before it sends anything:

- On a cold start, the first screen view waits up to 1 second for
  `Linking.getInitialURL()`. Events you send meanwhile wait too, and go out after it in
  order.
- When a link brings the app back after 30 minutes or more in the background, the screen
  view that starts the new visit waits up to 1 second for the link.
- A link that opens the app while a visit is still open puts its campaign on the next
  screen view. The visit keeps the source it started with.

For a link the SDK can't see, such as one your push notification library hands you, pass
it to `misomoon.openedFrom(url)` before the screen it opens. The campaign goes on the
next screen view.

### Pass the visit to a checkout from the app

For a purchase your server starts, such as a web checkout opened from the app, send
`misomoon.ref()` to that server with the order. The server puts the ref in the
checkout's metadata ([Connect payments](revenue.md#pass-the-ref-to-the-checkout)):

```tsx
const misomoon = useMisomoon()
await api.createCheckout({ plan: 'yearly', ref: misomoon.ref() })
```

Each screen view has one ref, and the next screen gets a new one. The SDK tells misomoon
about a ref when it hands the ref out, so the payment finds the visit even if the app
never sends another event.

### What the app sends by itself

| Event | When |
| --- | --- |
| `pageview` | A new screen, and the current screen again when the app comes back after 30 minutes or more, because the server ends a visit after 30 minutes without events. |
| `engagement` | When the screen changes or the app goes to the background: the time the screen was in the foreground, if it was one second or more. |

Events wait in memory while the device is offline and go out in order once it's back.
The SDK drops an event that is still unsent after 5 minutes, because the server dates an
older event by its arrival and would put it in the wrong visit. When the app goes to the
background, the SDK sends what it has.

## Send events from your server

Server-side events cover what the browser never sees, such as a signup your API handles
or a payment your server confirms. Pass the visitor's address and user agent. The server
then gives the event the same visitor id as the visitor's browser. If the visit had an
event in the last 30 minutes, the server event joins that visit and its traffic source.
Otherwise it starts a new visit.

```ts
import { createMisomoon, visitorFromRequest } from '@misomoon/sdk/node'

const misomoon = createMisomoon({ site: 'your-site', host: 'https://analytics.example.com' })

// Express. visitorFromRequest also takes a Fetch API Request (Hono, Next.js route handlers, Workers).
app.post('/api/signup', async (req, res) => {
	await createAccount(req.body)
	const visitor = visitorFromRequest(req)
	if (visitor) misomoon.track('Signup', { url: 'https://example.com/signup', visitor, props: { plan: req.body.plan } })
	res.sendStatus(201)
})
```

`visitorFromRequest` reads the address your platform reports: `CF-Connecting-IP`,
`True-Client-IP`, `Fly-Client-IP`, `X-Real-IP`, the first `X-Forwarded-For`, then the
socket. It also reads Cloudflare's and Vercel's location headers when they're there. It
returns `null` when the request has no address or no user agent. Without them the event
would count your server as the visitor, so `track()` refuses an event that has none.

A payment webhook comes from the payment provider, not the visitor, so it has no
visitor to send. Send the purchase when the visitor's browser returns to your success
page instead. That request is theirs, and it arrives while their visit is still open:

```ts
// GET /checkout/success?session_id=...
const session = await stripe.checkout.sessions.retrieve(req.query.session_id)
const visitor = visitorFromRequest(req)
if (session.payment_status === 'paid' && visitor) {
	misomoon.track('Purchase', {
		url: 'https://example.com/checkout/success',
		visitor,
		revenue: { amount: session.amount_total / 100, currency: session.currency },
	})
}
```

A visitor can reload the success page, so send the purchase once per order: for example,
mark the order as tracked in your database the first time.

### Pass the visit to a checkout your server creates

When your server creates the checkout, it can make the ref itself from the visitor's
request. The browser then needs no extra code:

```ts
app.post('/api/checkout', async (req, res) => {
	const ref = misomoon.ref({ url: 'https://example.com/pricing', visitor: visitorFromRequest(req) })
	const session = await stripe.checkout.sessions.create({
		// your line items
		metadata: { misomoon_ref: ref },
		success_url: 'https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}',
	})
	res.json({ url: session.url })
})
```

The ref joins the visit that the visitor's address and user agent have open, when that
visit had an event in the last 30 minutes. A checkout started from a page the tracker
counted has one. Without an open visit, the ref keeps only what the request shows: the
page and the device, and no traffic source. `ref()` returns `undefined` and sends nothing when
the visitor has no address or no user agent, or when `url` isn't absolute. In a
serverless function, `await misomoon.flush()` before it returns, or the ref may never
reach misomoon.

### Send payments from providers without a webhook

For a provider misomoon has no webhook for, send each payment with `payment()`. It posts
to the site's custom webhook ([Send payments from your own server](revenue.md#send-payments-from-your-own-server)),
signed with the secret from **Settings** > **Revenue**:

```ts
const misomoon = createMisomoon({
	site: 'your-site',
	host: 'https://analytics.example.com',
	secret: process.env.MISOMOON_WEBHOOK_SECRET,
})

await misomoon.payment({ id: order.id, amount: 49.9, currency: 'EUR', ref: order.misomoonRef, customer: order.customerId })
await misomoon.payment({ id: refund.id, type: 'refund', refundOf: order.id, amount: 10, currency: 'EUR' })
```

| Field | Meaning |
| --- | --- |
| `id` | Your payment id, unique per site. Required. A resend with the same id counts once. |
| `amount` | Positive, in major units: `49.9` for 49.90. Required. |
| `currency` | ISO 4217 code. Required. |
| `type` | `'payment'` (the default) or `'refund'`. |
| `refundOf` | For a refund, the `id` of the payment it returns. |
| `ref` | The ref from the buyer's visit: from `ref()` in the browser, the app, or here. |
| `customer`, `subscription` | Your ids. A later payment with the same customer or subscription counts toward the first payment's visit. |
| `billing` | `'new'`, `'renewal'`, or `'one_time'`. |
| `ts` | When the payment happened: a `Date`, Unix milliseconds, or an ISO 8601 string. Defaults to now. |
| `test` | `true` checks the connection without counting the payment. |

`payment()` resolves to `true` once misomoon has the payment and to `false` otherwise.
It never rejects. After a network error, a timeout, `429`, or a `5xx` answer, it tries
again, with waits that double up to 30 seconds, for up to `maxAge`. A `400` or `401`
answer stops it, and the console shows the server's reason, such as a wrong secret or a
negative amount. `payment()` isn't part of `flush()`, so await it. Set `host` to
misomoon's own address here, not a proxy: a proxy forwards only the tracker's paths.

`track()` and `pageview()` return a promise that resolves to `true` once misomoon has the
event and `false` when it was dropped. They never reject. Don't await them in a request
handler: while misomoon is unreachable, the promise waits for the retries, up to
`maxAge` (5 minutes).

In a serverless function, which can stop as soon as it responds, wait for the events
before it ends: `await misomoon.flush()`, or `ctx.waitUntil(misomoon.flush())` on
Cloudflare Workers. `flush()` resolves once every queued event is sent or dropped, or
after 11 seconds, whichever comes first. A long-running server needs neither. Call
`await misomoon.shutdown()` before the process exits.

## How the SDK handles failures

Every client refuses an event with a mistake the server would drop, with a console
warning: an event name longer than 120 characters or with `;` or `|` in it, a negative
revenue amount, or a currency that isn't an ISO 4217 code. `track()` in the browser then
still runs its `callback`. `payment()` refuses a payment without an id, an amount above
0, or a currency code, and a refund without `refundOf`, before it sends a request.

The React Native and Node clients share one transport:

- An event with a relative URL is refused with a warning. Props the server would drop are
  removed with a warning.
- After a network error, a timeout (10 seconds), `429`, or a `5xx` answer, the SDK sends
  the event again. The waits double from 1 second up to 30 seconds, and each wait is
  shortened by a random amount up to half its length. Any other `4xx` answer drops the
  event.
- Each event carries a random id. When a response is lost after the server stored the
  event, the retry has the same id, and the server stores it once.
- An event over the 16 KB the server accepts is refused with a warning. String props are
  cut to the 300 characters the server keeps.
- The queue holds 500 events (200 in apps). When it is full, the oldest unsent event goes
  first.
- The SDK reads each answer to the end, so Node's `fetch` reuses its connections.

## Options

These options work in `createMisomoon()` and in `MisomoonProvider`:

| Option | Default | Meaning |
| --- | --- | --- |
| `site` | required | The site id. |
| `host` | required | Where misomoon answers, or your proxy, such as `https://example.com/relay`. Events go to `<host>/api/event`. |
| `domain` | required in apps | The site's domain. Screens become `https://<domain>/<screen>`. |
| `app` | `{ name: 'App' }` | Apps only: the name and version shown in place of a browser. |
| `timeout` | `10000` | Milliseconds before a request is abandoned and retried. |
| `concurrency` | `4` on servers, `1` in apps | Requests in flight at once. With `1`, events arrive in order. |
| `maxQueue` | `500` on servers, `200` in apps | Unsent events kept. |
| `maxAge` | `300000` | Milliseconds an event may wait before it is dropped. |
| `enabled` | `true` | `false` sends nothing, for example in tests or development. |
| `debug` | `false` | Logs every event sent, retried, and dropped. |
| `beforeSend` | none | A function that changes an event, or returns `null` to drop it. |
| `headers` | none | Headers on every request. |
| `fetch` | the global `fetch` | Your own `fetch`. |
| `secret` | none | Server only: the custom webhook's signing secret, for `payment()`. |

---

# Import your history and connect Search Console

You can bring the numbers you collected before misomoon into your reports. Import them
from a Google Analytics property, or upload the CSV files of an export. You can also
connect Google Search Console to see the Google searches that brought people to the
site.

## What an import adds

An import stores daily totals per dimension, for example the visitors from each source
on each day. misomoon adds these totals to the data it collects itself in the top-line
numbers, the chart, and the breakdowns of [the dimensions that imports fill](#what-imported-data-fills).

Imported numbers appear only in reports without filters. misomoon stores totals, not
single visits, so it can't tell which imported visits match a filter. When you add a
filter, every report shows collected data only.

The **Imported** button in the top bar turns imported history on and off. It appears
when the site has at least one finished import, and it starts on. Turning it off adds
`imported=0` to the address, which the [API](api.md#query-parameters) also accepts.
[The dashboard guide](dashboard.md) describes the top bar.

## Set up Google sign-in on your instance

The Google import and Search Console sign in to Google with one OAuth client, which you
create in your own Google Cloud project. If the instance already has the secrets
`GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, skip this section. CSV uploads don't need
Google sign-in.

1. In the Google Cloud console, create a project or open an existing one.
2. Enable the Google Analytics Data API, the Google Analytics Admin API, and the Google
   Search Console API for the project.
3. Configure the OAuth consent screen for the project.
4. Create an OAuth client ID with the application type **Web application**.
5. Under **Authorized redirect URIs**, add your misomoon address followed by
   `/api/v1/google/callback`, for example
   `https://analytics.example.com/api/v1/google/callback`.
6. Copy the client ID and the client secret.
7. In `apps/api`, set the two secrets:

   ```sh
   wrangler secret put GOOGLE_CLIENT_ID
   wrangler secret put GOOGLE_CLIENT_SECRET
   ```

The import uses the Analytics Data and Analytics Admin APIs. Search Console uses the
Search Console API. If you want only one of the two features, enable only the APIs it
uses.

misomoon builds the redirect URI from the address you open the dashboard at. If you
reach the instance at more than one address, such as its `workers.dev` address and your
own domain, add a redirect URI for each one. The `PUBLIC_URL` variable doesn't change
the redirect URI.

If the consent screen's publishing status is **Testing**, add each Google account that
signs in as a test user. Google ends the refresh tokens of apps in testing after 7 days
([Google's OAuth documentation](https://developers.google.com/identity/protocols/oauth2#expiration),
checked 2026-10-25). After that, Search Console shows the error
`Google sign-in expired; connect again` until you connect again.

On an instance deployed with the button, set the two secrets in the Cloudflare
dashboard. Open the Worker, then **Settings** > **Variables and Secrets**.
[Turn on optional features](self-hosting.md#turn-on-optional-features) and the
[secrets reference](configuration.md#secrets) list the other secrets.

## Import a Google Analytics property

misomoon adds imported days to the days it collected. A day that is in both counts
twice. Before you start, find the day misomoon started collecting on the site, and
import only the days before it.

1. Open **Settings** > **Integrations**.
2. In the **Import history** card, click **Connect Google**.
3. Sign in with a Google account that can read the property, and allow access. Finish
   within an hour of the click.
4. Back in **Settings**, pick the property in **Google property**. The list shows every
   property that the Google account can read, as `Account: Property`.
5. Set the last day to import in **To**. Use the day before misomoon started collecting.
6. To start later than the earliest day Google has, set the first day in **From**.
7. Click **Import**.

Both dates are included. An empty **From** starts at `2015-08-14`, the earliest day
Google serves. An empty **To** ends yesterday.

The import runs on the server, so it doesn't need the page to stay open. Its row in the
list says **Importing…**, and the card checks again every 4 seconds. A finished import
shows its first and last day and the number of rows it stored. misomoon stores each
Google day under the same date in the site's time zone.

If the import fails, its row shows **Failed:** and the error from Google or misomoon. To
try again, delete the failed import, which also removes any rows it stored. Then start
again at **Connect Google**, because the dashboard forgets the Google sign-in once you
click **Import**.

If Google sign-in fails or you cancel it, **Settings** opens again with the
**Connect Google** button and no property list. Click **Connect Google** to try again.

Each import is separate. If you import the same days twice, they count twice, so delete
the old import before you import those days again.

## Upload CSV files

misomoon reads a CSV export as one ZIP file or as the CSV files from it. Each file holds
one report and is named `imported_<report>.csv` or
`imported_<report>_<YYYYMMDD>_<YYYYMMDD>.csv`. [CSV format](#csv-format) lists the
reports and their columns.

1. Open **Settings** > **Integrations**.
2. In the **Import history** card, click **Upload CSV or zip**.
3. Pick the ZIP file, or pick one or more CSV files.

misomoon reads the files while you wait. The new row in the list shows the file names,
the first and last day in the files, and the number of rows stored.

Include `imported_visitors.csv`. It is the only file that fills the site totals, which
are the top-line visitors, visits, pageviews, bounce rate, and visit duration, and the
chart. The other files fill breakdowns. `imported_custom_events.csv` also adds its events
to the total event count.

misomoon skips files whose names don't match the pattern and reports it doesn't read. If
no file holds rows that misomoon reads, the upload fails with
`no imported_*.csv files found (expected a CSV export)`.

To upload from a script, send the files as `file` fields of a multipart form. The call
returns `201` and the new import:

```sh
curl -X POST "https://analytics.example.com/api/v1/sites/shop/imports" \
	-H "Authorization: Bearer $MISOMOON_KEY" \
	-F "file=@export.zip"
```

## Delete an import

If an import says **Importing…**, wait until it finishes or fails before you delete it.
Rows that a running import writes after you delete it stay in your reports.

1. Open **Settings** > **Integrations**.
2. In the **Import history** card, click the **Delete import** button on the row of the
   import.

misomoon deletes the import at once, without asking you to confirm. It removes the
import's rows from every shard that holds data for the site, then removes the import
from the list. When the last finished import is gone, the **Imported** button
disappears.

## Connect Search Console

The site must be in Google Search Console under a Google account that you can sign in
with, and the instance needs [Google sign-in](#set-up-google-sign-in-on-your-instance).
If the secrets are missing, the **Google Search Console** card says
**Not enabled on this server**.

1. Open **Settings** > **Integrations**.
2. In the **Google Search Console** card, click **Connect Search Console**.
3. Sign in with a Google account that has the site in Search Console, and allow access.
4. Back in **Settings**, pick the property in **Search Console property**.
5. Click **Connect**.

Properties for the site's domain come first in the list and say **matches this site**.
A domain property shows as `example.com (domain)`. The list leaves out properties that
the account hasn't verified. If none is left, the card says that this Google account
has no verified Search Console properties. Add the site in Search Console, or sign in
with another account.

The card then shows the property, the person who connected it, and the date. A site has
one connected property. If you connect again and pick another property, it replaces
the first one.

### Find the search terms

1. Open **Overview**.
2. In **Where they come from**, click the **Organic Search** channel.
3. Click the **Search terms** tab.

The tab lists the terms that brought the most clicks from Google in the period, with
the clicks for each one. It appears only for a site with Search Console connected, and
only while **Organic Search** is the chosen channel. Everyone who can see the site's
reports sees it, viewers included.

To get impressions, click-through rate, and position too, call
[the breakdown endpoint](api.md#get-apiv1statsbreakdown) with `property=search_term`,
or use the `get_search_terms` [MCP tool](mcp.md#tools).

misomoon reads search terms from Google when you open the report, and keeps each answer
for ten minutes. It doesn't save them in its database. Google reports searches about two days late, so
the last two or three days of a period fill in later.

Google can filter search terms by page and by device only. With any other filter on,
the tab shows an error that names the filter. Remove that filter to see the terms.

### Disconnect Search Console

1. Open **Settings** > **Integrations**.
2. In the **Google Search Console** card, click the **Disconnect Search Console**
   button.

misomoon disconnects at once, without asking you to confirm. It asks Google to revoke
its access and deletes the tokens it stored. The **Search terms** tab disappears.

## Reference

### Roles

| Task | Who can do it |
| --- | --- |
| Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` | Whoever deploys the Worker |
| See the import list, import from Google, upload CSV files, delete imports | Owner, admin, editor, and guest editor |
| Connect, change, and disconnect Search Console | Owner, admin, editor, and guest editor |
| See imported numbers and the **Imported** button | Everyone who can see the site's reports |
| See search terms | Everyone who can see the site's reports |

The **Import history** and **Google Search Console** cards appear only for the roles
that can edit the site. An API key acts with its owner's role.

### CSV format

These rules apply to every file:

- The name is `imported_<report>.csv`, or `imported_<report>_<YYYYMMDD>_<YYYYMMDD>.csv`
  with the dates of the export. Inside a ZIP file, a file may sit in a folder.
- The first line holds the column names. misomoon finds each column by its name, in any
  order, and ignores columns it doesn't read. A missing column counts as empty.
- `date` is `YYYY-MM-DD`. misomoon skips rows with any other date.
- Commas separate the values. A value in double quotes may hold commas and line breaks,
  and `""` inside it is one double quote.
- misomoon rounds counts to whole numbers. It reads an empty, negative, or non-numeric
  count as `0`.
- misomoon trims text values and cuts them at 500 characters. It stores an empty value
  as `(none)`.

Most reports carry the visit columns:

| Column | What it holds |
| --- | --- |
| `visitors` | Unique visitors that day |
| `visits` | Visits |
| `pageviews` | Pageviews |
| `bounces` | Visits that bounced |
| `visit_duration` | The total length of all the visits, in seconds |

misomoon reads these reports. It skips files for other reports.

| Report | Columns besides `date` | What it fills |
| --- | --- | --- |
| `visitors` | The visit columns | The site totals and the chart |
| `sources` | `source`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, and the visit columns | `source`, `channel`, `referrer`, and each UTM dimension that has a value. An empty `source` is `Direct`. misomoon works out the channel from `source`, `utm_medium`, and `utm_source`. It keeps the host of `referrer` without `www.`. |
| `pages` | `page`, `visitors`, `visits`, `pageviews`, `total_time_on_page`, `total_time_on_page_visits`, `total_scroll_depth`, `total_scroll_depth_visits` | `page`. Time on page is `total_time_on_page`, in seconds, divided by `total_time_on_page_visits`. Scroll depth is `total_scroll_depth`, in percent, divided by `total_scroll_depth_visits`. |
| `entry_pages` | `entry_page`, `entrances`, `visitors`, `pageviews`, `bounces`, `visit_duration` | `entry_page`. `entrances` is the visit count. |
| `exit_pages` | `exit_page`, `exits`, `visitors`, `pageviews`, `bounces`, `visit_duration` | `exit_page`. `exits` is the visit count. |
| `locations` | `country`, `region`, and the visit columns | `country` as an uppercase code, and `region` |
| `browsers` | `browser`, `browser_version`, and the visit columns | `browser`, and `browser_version` as the browser name followed by the version |
| `operating_systems` | `operating_system`, `operating_system_version`, and the visit columns | `os`, and `os_version` as the system name followed by the version |
| `devices` | `device` and the visit columns | `device` |
| `custom_events` | `name`, `visitors`, `events` | `event`. `Outbound Link: Click` becomes `Outbound link`, `File Download` becomes `Download`, and `Form: Submission` becomes `Form sent`. |

### What imported data fills

Imported history fills the site totals, the chart, and the breakdowns of these
dimensions. [The metrics page](metrics.md) defines each metric.

| Dimension | From a Google property | From CSV files |
| --- | --- | --- |
| Site totals and the chart | Yes | `imported_visitors.csv` |
| Custom event counts in the totals | Yes | `imported_custom_events.csv` |
| `channel` | Yes | Yes |
| `source` | Yes | Yes |
| `referrer` | Yes | Yes |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | Yes | Yes |
| `page` | Yes | Yes |
| `entry_page` | Yes | Yes |
| `exit_page` | No | Yes |
| `country`, `region` | Yes | Yes |
| `city` | Yes | No |
| `browser` | Yes | Yes |
| `browser_version` | No | Yes |
| `os`, `os_version` | Yes | Yes |
| `device` | Yes | Yes |
| `event` | Yes | Yes |

Imported visitors are unique per day, as Google and the export report them. A period's
imported visitors are the sum of its days.

A page's bounce rate and visit duration come from the visits that entered on that page,
which are the `entry_page` rows.

A day of imported data has no time of day. Minute and hour charts show the whole day at
midnight.

### What a Google import reads

misomoon runs one Google Analytics Data API report per group of dimensions, 100,000 rows
per request, and maps the results like this:

| misomoon | Google |
| --- | --- |
| Visitors | `totalUsers` |
| Visits | `sessions` |
| Pageviews | `screenPageViews` |
| Bounces | `sessions` minus `engagedSessions` |
| Visit duration | `userEngagementDuration` |
| Time on page | `userEngagementDuration` divided by `sessions`, per `pagePath` |
| Events | `eventCount` per `eventName` |
| `source` | `sessionSource` without `www.`, or `Direct` when Google has none |
| `channel` | `sessionDefaultChannelGroup` |
| `referrer` | `sessionSource` when it contains a dot |
| `utm_source`, `utm_medium` | `sessionSource`, `sessionMedium` |
| `utm_campaign`, `utm_content`, `utm_term` | `sessionCampaignName`, `sessionManualAdContent`, `sessionGoogleAdsKeyword` |
| `page` | `pagePath`, without the query string or a trailing slash |
| `entry_page` | `landingPage`, without the query string or a trailing slash |
| `country`, `region`, `city` | `countryId`, `region`, `city` |
| `device` | `deviceCategory` as `Desktop`, `Mobile`, or `Tablet` |
| `browser` | `browser` |
| `os`, `os_version` | `operatingSystem`, and `operatingSystem` followed by `operatingSystemVersion` |

Most Google channel groups keep their names. `Organic Video` and `Paid Video` become
`Video`, `Organic Shopping` becomes `Referral`, and `Paid Shopping` becomes
`Paid Search`. Google's automatic events `page_view`, `session_start`, `first_visit`,
`user_engagement`, and `scroll` are left out, because misomoon measures those itself.
Google values `(not set)`, `(none)`, and `(direct)` count as empty.

### What imports leave out

- Reports with any filter, including segments and goal filters.
- Goal conversions, revenue, and the **Funnels**, **Paths**, **Live**, **Behavior**, and
  **Speed** views.
- Dimensions that the table above doesn't list, such as screens, networks, and
  languages.
- Scroll depth from a Google import.
- The **All time** period. It starts at the first visit that misomoon collected for the
  site, so it doesn't reach imported days before that visit. To see older imported
  days, pick a period that reaches back to them. A custom period covers up to 400 days.

### Search terms

Each row of the breakdown with `property=search_term` has these fields:

| Field | What it holds |
| --- | --- |
| `key` | The search term |
| `clicks` | Clicks from Google search results to the site |
| `impressions` | How often the site appeared in the results |
| `ctr` | Clicks divided by impressions, in percent, with one decimal |
| `position` | The average position in the results, with one decimal. `1` is the top. |
| `visitors` | The same number as `clicks` |

`total_visitors` is the sum of `clicks` on the page of results. misomoon asks Google for
web search results, fresh data included.

The filters that misomoon passes to Google:

- `page` and `entry_page` with `==` or `!=`, where `*` matches any characters, or with
  `~` or `!~` and one value.
- `device` with `==` or `!=` and one of `desktop`, `mobile`, or `tablet`.
- `source==google` and `channel==Organic Search`, which change nothing because every
  search term comes from Google search.

Any other filter returns an error that names it. The `search` parameter keeps only the
terms that contain its text.

### Limits

- A Google sign-in must finish within an hour of the click on **Connect Google** or
  **Connect Search Console**.
- Google import dates are `YYYY-MM-DD`. misomoon ignores a date in another form and uses
  the default instead.
- An import's name is cut at 120 characters, and its error at 500.
- While the site's data moves between shards, imports fail with
  `this site's history is being moved between shards; try the import again in a few hours`.
- The breakdown returns up to 1,000 search terms per page. The MCP tool returns up to
  100.

### What misomoon stores

- For each import: its source, name, first and last day, status, error, and row count.
- The imported daily totals, in the shards that hold the site's data for those days.
- During a Google sign-in, the Google tokens. misomoon deletes them after a successful
  Google import or a Search Console connection. The next Google sign-in deletes unused
  ones that are more than a day old.
- For a connected Search Console property: the property, the Google tokens, the person
  who connected it, and the date.

misomoon asks Google for read-only access. The import asks for the
`https://www.googleapis.com/auth/analytics.readonly` scope, and Search Console for
`https://www.googleapis.com/auth/webmasters.readonly`. Both ask for offline access, so
misomoon can renew the access token without a new sign-in.

### API endpoints

Every path starts with `/api/v1/sites/:id/` except the callback.

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET imports` | Editor | Lists the site's imports, newest first: `id`, `site_id`, `source` (`csv` or `google`), `label`, `from_day`, `to_day`, `status` (`importing`, `done`, or `failed`), `error`, `rows`, and `created_at`. |
| `POST imports` | Editor | Uploads a CSV export as multipart `file` fields. Returns `201` and the import. |
| `DELETE imports/:import` | Editor | Deletes the import and its rows. Returns `204`. |
| `POST imports/google/connect` | Editor | Starts a Google sign-in for the import. Returns `{"url": "..."}` to open in the browser. |
| `GET imports/google/properties?grant=` | Editor | Lists the Google Analytics properties that the grant can read: `id`, `name`, and `account`. |
| `POST imports/google` | Editor | Starts an import from `{"grant", "property", "from", "to", "label"}`. `property` looks like `properties/123`. Returns `202` and `{"id", "status": "importing"}`. |
| `GET search-console` | Editor | Returns `available`, which is `true` when the instance has the Google secrets, and `connected`, the connected property or `null`. |
| `POST search-console/connect` | Editor | Starts a Google sign-in for Search Console. Returns `{"url": "..."}`. |
| `GET search-console/properties?grant=` | Editor | Lists the verified Search Console properties: `property`, and `matches`, which is `true` for the site's domain. |
| `PUT search-console` | Editor | Connects `{"grant", "property"}`. Returns the same object as `GET search-console`. |
| `DELETE search-console` | Editor | Disconnects Search Console. Returns `204`. |
| `GET /api/v1/google/callback` | None | Google redirects here after sign-in. It opens **Settings** again with the grant in the address. |

Without the Google secrets, every endpoint that calls Google returns `501`. `GET search-console` returns `available: false` instead.

---

# Work with your team

A team owns sites. Everyone on a team holds one role on all of its sites, and a guest
holds a role on one site only. This page shows how to invite people, change what they
can do, move sites between teams, look after your account, and manage API keys.

## How teams own sites

Every site belongs to exactly one team. A team member's role applies to every site of
that team, including sites added after the person joined. A guest belongs to no team and
sees only the site they were invited to.

You get your first team when you create an account. misomoon names it after you, for
example "Ada's sites", and makes you its owner. An account made through an invitation
starts without a team of its own. If that person adds a site and no team lets them add
sites, misomoon creates a team named "My sites" with them as owner.

The **Team** tab in **Settings** always shows the team of the site that is open. To
manage another team, open one of its sites first.

## What each role can do

A team role is one of five values. Each role grants a set of permissions from
`packages/core/src/roles.ts`, and the API checks those permissions on every request.

| Role | Permissions | What it can do |
| --- | --- | --- |
| **Owner** | `read`, `edit`, `manage`, `own`, `billing` | Everything an admin can do. Invite, change, and remove other owners. Move the team's sites to another team. Delete the team. |
| **Admin** | `read`, `edit`, `manage` | Everything an editor can do. Invite, change, and remove members other than owners. Invite, change, and remove guests. Delete sites. Rename the team. |
| **Editor** | `read`, `edit` | Everything a viewer can do. Change goals, funnels, segments, imports, shared links, email reports, annotations, the proxy, and site details. Add sites to the team. |
| **Viewer** | `read` | See stats and saved reports. Save personal segments. |
| **Billing** | `billing` | No stats and no settings. No screen or API route checks the `billing` permission, so this role gives access to nothing beyond the person's own account. The team's sites appear in the site list, and opening one shows **Billing access** instead of stats. A billing member can leave the team. |

A guest holds one of two roles on a single site:

| Guest role | Permissions | What it can do |
| --- | --- | --- |
| **Guest editor** | `read`, `edit` | What an editor can do, on that one site. A guest can't add sites to the team. |
| **Guest viewer** | `read` | What a viewer can do, on that one site. |

If someone is both a team member and a guest on one of the team's sites, the team role
applies.

These rules decide who can give which role:

- An owner can give, change, and take away any role, including owner.
- An admin can't invite an owner, make someone an owner, change an owner's role, or
  remove an owner.
- A team always keeps one owner. misomoon refuses to change the role of the last owner
  or to remove the last owner, and that includes the last owner leaving.
- Only owners and admins manage people, so only they see the **Team** tab.

## Who can sign up

The `SIGNUPS` variable decides who can create an account from the sign-in screen.
[Configuration](configuration.md#variables) lists it with the other variables.

| `SIGNUPS` | Who can sign up |
| --- | --- |
| `open`, or unset | Anyone who opens the dashboard. |
| `invite` | One person, while the instance has no account yet. That person owns the instance. After that, sign-up is off, and people join through invitations. |
| `closed` | Nobody, not even the first account. |

Invitations create accounts under every value, including `closed`. The **Create an
account** link on the sign-in screen appears only while sign-up is open. The deploy
bundle sets `invite`, and [Run misomoon in your Cloudflare account](self-hosting.md#claim-your-instance) shows
how to claim a new instance.

With `closed` and no account yet, nobody can sign in or send an invitation. Claim the
instance before you set `closed`.

## Invite a teammate

You need the **Owner** or **Admin** role on the team.

1. Open a site of the team, and go to **Settings** > **Team**.
2. Enter the person's email address.
3. In **Access to**, keep **Whole team**.
4. In **Role**, pick the role. Admins don't see **Owner** in the list.
5. Select **Invite**.

The invitation link appears below the form, with a button to copy it. If the instance
has an email provider, misomoon also emails the link, with the team name in the subject.
Without an email provider, send the link yourself. The link works for 7 days.
[Configuration](configuration.md#bindings) explains how to set up email.

The invitation stays in the member list as **pending**, with its expiry date, until the
person accepts it. To withdraw it, select the trash icon next to it.

If you invite the same email address again, the new invitation replaces the old one, and
the old link stops working. You can't invite someone who is already on the team.

## Give someone one site

To let someone see one site without joining the team, invite them as a guest. You need
the **Owner** or **Admin** role on the site's team.

1. Open the site, and go to **Settings** > **Team**.
2. Enter the person's email address.
3. In **Access to**, pick **Only** followed by the site name.
4. In **Role**, pick **Guest editor** or **Guest viewer**.
5. Select **Invite**.

The link, the email, and the 7-day expiry work as they do for a team invitation. The
**Team** tab lists the open site's guests with their role. To change a guest's role,
pick another value in the menu next to their name. To remove a guest, select the trash
icon next to their name.

## Accept an invitation

Open the link from the email or from the person who invited you. It looks like
`https://analytics.example.com/invite/mi_...`. The page names who invited you, to which
team or site, and with which role.

- If you have no account, enter your name and a password of at least 10 characters, and
  select **Accept invitation**. misomoon creates your account with the invited email
  address and signs you in.
- If you have an account and are signed out, select **Sign in as** followed by your
  email address. Enter your password, and select **Sign in**. misomoon accepts the
  invitation after you sign in.
- If you are signed in with the invited email address, select **Accept invitation**.

If you are signed in with a different email address, misomoon refuses the invitation.
Sign out, and open the link again.

After you accept, the dashboard opens on the site you were invited to, or on the team's
first site. If you were already a guest on that site, the role in the new invitation
replaces your old one. An expired or withdrawn link shows an error, so ask for a new
invitation.

## Change a role

You need the **Owner** or **Admin** role on the team.

1. Open a site of the team, and go to **Settings** > **Team**.
2. In the menu next to the person's name, pick the new role.

The change applies to every site of the team. An admin sees an owner's role as a plain
**Owner** label, with no menu and no trash icon. To change the role of the last owner,
make someone else an owner first.

## Remove someone

You need the **Owner** or **Admin** role on the team. Only an owner can remove an owner.

1. Open a site of the team, and go to **Settings** > **Team**.
2. Select the trash icon next to the person's name.

The person loses access to every site of the team at once. Their API keys stop working
on those sites too, because a key acts with its owner's role.

## Leave a team

Every role except owner leaves from the **Sites** tab:

1. Open a site of the team, and go to **Settings** > **Sites**.
2. Select **Leave team**.

You lose access to every site of the team. A guest sees **Leave site** in the same place,
and it ends their access to that one site.

The **Sites** tab has no leave button for an owner. If the team has another owner, go
to **Settings** > **Team**, and select the trash icon on your own row. The last owner
can't leave. Make someone else an owner first.

## Create another team

The dashboard has no button to create a team. Use the API with a browser session token.
API keys can't call team routes.

1. Sign in through the API, and copy the `token` from the response:

   ```sh
   curl -X POST "https://analytics.example.com/api/v1/auth/login" \
   	-H "Content-Type: application/json" \
   	-d '{"email": "you@example.com", "password": "your password"}'
   ```

2. Create the team with that token:

   ```sh
   curl -X POST "https://analytics.example.com/api/v1/teams" \
   	-H "Authorization: Bearer ms_..." -H "Content-Type: application/json" \
   	-d '{"name": "Client work"}'
   ```

The response is the new team with `"role": "owner"`. A name longer than 80 characters
is cut to 80, and an empty name becomes "My team".

To put a site in the new team, add one from **Settings** > **Sites**. Select **Change**
under the domain field, and pick the team in **Team**. That menu appears when you can
add sites to more than one team. You can also move an existing site into the new team,
as [Move a site to another team](#move-a-site-to-another-team) describes. A team with no
sites has no **Team** tab, because the tab follows the open site.

## Rename or delete a team

To rename a team, you need the **Owner** or **Admin** role.

1. Open a site of the team, and go to **Settings** > **Team**.
2. Edit the name at the top of the tab.
3. Select **Rename**.

To delete a team, you need the **Owner** role, and the team must have no sites. Move or
delete its sites first. The dashboard has no button to delete a team, so send
`DELETE /api/v1/teams/:team` with a session token. misomoon answers `204` when the team
is gone, or `409` while the team still has sites.

## Move a site to another team

You need the **Owner** role on the site's current team, and the **Owner** or **Admin**
role on the team that receives it.

1. Open the site, and go to **Settings** > **Sites**.
2. Under **Danger zone**, pick the receiving team in **Team**.
3. Select **Move site**.

The **Team** menu lists only the teams that you own or administer. If you have none,
the move controls don't appear.

When the site moves:

- Members of the old team lose access, unless they are members of the new team too.
- Members of the new team get access with their team role.
- Guests keep their guest role. A guest who is a member of the new team stops being a
  guest, because the team role now covers the site.
- Pending invitations to the site are withdrawn.

The API call is `POST /api/v1/sites/:id/transfer` with `{"team": "<team id>"}`.

## Manage your account

**Settings** > **Account** shows the email address you signed in with and your role on
the open site. You can't change your email address.

### Change your name or password

1. Go to **Settings** > **Account**.
2. Edit your name.
3. To change your password, enter your current password in **Current password** and the
   new one in **New password**.
4. Select **Save**.

A password has 10 to 200 characters. A name longer than 80 characters is cut to 80.
Changing your password here keeps your other sessions signed in.

### Reset a forgotten password

The reset link goes out by email, so the instance needs an email provider.

1. On the sign-in screen, select **Forgot your password?**.
2. Enter your email address, and select **Send the link**.
3. Open the link in the email. The link works for one hour.
4. Enter a new password of at least 10 characters, and select **Save and sign in**.

The new password signs you out of every other browser and device. If you ask for a
second link, the first one stops working. The screen answers the same way whether or not
the email address has an account.

Without an email provider, the screen says that email isn't set up, and no link goes
out. misomoon has no other way to reset a password from the dashboard or the API.

### Sign out

Select **Sign out** in **Settings** > **Account**. Signing out ends the session in that
browser only.

A session starts each time you sign in and lasts 30 days. After that, the dashboard asks
you to sign in again. To end every session at once, reset your password.

### Delete your account

1. Go to **Settings** > **Account**, and select **Delete account…**.
2. Enter your password, and select **Delete account**.

misomoon deletes the account at once, and signs you out:

- A team where you are the only member is deleted, with its sites and all of their stats.
  Export what you want to keep first ([Refresh and export](dashboard.md#refresh-and-export)).
- You leave every other team, and lose guest access to other teams' sites. Their sites
  and stats stay.
- Your sessions, API keys, saved segments, pending invitations to your email address, and
  the email reports sent to it are deleted.

If you are the only owner of a team that has other members, deleting fails with "you are
the only owner of … make someone else owner or remove its members first". Make one of
them an owner ([Change a role](#change-a-role)), or remove them, and try again. A wrong
password changes nothing.

On app.misomoon.com, backups that could still hold the deleted data expire within the
time the [data processing agreement](dpa.md#12-deletion-and-return) gives.

## Manage API keys

An API key starts with `mm_` and acts as you. Send it in the `Authorization` header, as
[API](api.md#authentication) shows. To connect an AI tool with a key, see
[Ask AI tools about your traffic](mcp.md#connect-a-client).

### Create an API key

To create a key for one site in the dashboard:

1. Open the site, and go to **Settings** > **Integrations**.
2. In **Connect AI tools (MCP)**, select **Create API key for** followed by the site name.
3. Copy the key, or the command or JSON that contains it. misomoon shows the key only
   once.

The key is named "MCP · " followed by the site name, and it reads only that site. The
create button appears only while you have no key for the site. After that, the section
lists the key with a **Rotate** button.

To create a key for every site you can see, use the API with a session token. Leave out
`site`:

```sh
curl -X POST "https://analytics.example.com/api/v1/keys" \
	-H "Authorization: Bearer ms_..." -H "Content-Type: application/json" \
	-d '{"name": "Nightly export"}'
```

To limit the key to one site, add `"site": "<site id>"`. You need at least read access
to that site. The response holds the key in `key`, and misomoon doesn't show it again. A
name longer than 80 characters is cut to 80, and an empty name becomes "API key".

### Rotate an API key

Rotating gives a key a new secret. The name and the site stay. The old secret stops
working at once, so update every tool that uses it.

1. Open the key's site, and go to **Settings** > **Integrations**.
2. Select **Rotate** next to the key, then **Confirm rotate**.
3. Copy the new key. misomoon shows it only once.

The dashboard rotates site keys only. For a key without a site, send
`POST /api/v1/keys/:key/rotate` with a session token.

### Revoke an API key

1. Go to **Settings** > **Account**.
2. Under **API keys**, select the trash icon next to the key.

The list shows each key's first characters, its name, its site or "all your sites", and
when it was last used. A revoked key stops working at once.

### What a key can do

- A key has your role on each site. If your role changes or you lose access, the key
  changes with you.
- A key can do everything your role allows on a site, including changes and deletes. A
  key that belongs to an owner or an admin can delete a site.
- A key with a site reads and changes that site only.
- The Stats API allows 100 requests per minute per key, as
  [API](api.md#rate-limits) describes.
- misomoon records when a key was last used, about once a minute while the key is busy.

Some calls need a signed-in person, and a key gets `403` for them. Sign in to the
dashboard, or use a session token, to do these things:

- Change your name or password.
- List, create, rotate, or revoke API keys.
- Read or change teams, members, roles, and team invitations.
- Add a site.
- Move a site to another team.
- Save a personal segment.

## Limits on sign-in attempts

When the `STATS_LIMIT` binding exists, misomoon allows 100 attempts per minute per IP
address for each of these actions: sign-up, sign-in, the forgotten-password form, the
password reset, and the invitation accept. Over the limit, the action answers `429`.
Wait a minute, and try again.

## API routes for accounts and teams

Every route is under `/api/v1`. Routes that need a signed-in person refuse API keys.
[API](api.md#accounts-and-teams) lists the same routes with the rest of the API.

| Method and path | Who can call it | What it does |
| --- | --- | --- |
| `POST /auth/signup` | Anyone, while sign-up is open | Takes `email`, `name`, and `password`. Creates the account and its first team, and returns a session `token`. |
| `POST /auth/login` | Anyone | Takes `email` and `password`. Returns a session `token`, its `expires_at`, and the `user`. |
| `POST /auth/logout` | A session | Ends the session in the `Authorization` header. |
| `POST /auth/forgot` | Anyone | Takes `email`. Emails a reset link that works for one hour. `sending` in the response is `false` without an email provider. |
| `POST /auth/reset` | Anyone with a reset link | Takes `token` and `password`. Sets the password, ends every session of the account, and returns a new session `token`. |
| `GET /me` | Anyone | Who you are, your teams with your role, your sites, and whether sign-up is open. |
| `PATCH /me` | A session | Takes `name`, or `password` with `current_password`. |
| `DELETE /me` | A session | Takes `password`. Deletes your account and the teams only you are in, with their sites ([Delete your account](#delete-your-account)). |
| `GET /teams` | A session | Your teams, with your role and the number of members and sites. |
| `POST /teams` | A session | Takes `name`. Creates a team with you as owner. |
| `PATCH /teams/:team` | Owner, admin | Takes `name`. Renames the team. |
| `DELETE /teams/:team` | Owner | Deletes a team that has no sites. |
| `GET /teams/:team/members` | Owner, admin | The members, the guests of every site of the team, and the pending invitations. |
| `PATCH /teams/:team/members/:user` | Owner, admin | Takes `role`. Changes a member's role. |
| `DELETE /teams/:team/members/:user` | Owner, admin, or the member | Removes a member. With your own user id, you leave the team. |
| `POST /teams/:team/invitations` | Owner, admin | Takes `email`, `role`, and `site`. Without `site`, the role is a team role. With `site`, the role is `editor` or `viewer`, and the person becomes a guest of that site. Returns the link in `url` and whether the email went out in `sent`. |
| `DELETE /teams/:team/invitations/:invitation` | Owner, admin | Withdraws an invitation. |
| `GET /invitations/:token` | Anyone | The invited email, the role, the team, the site, who invited, and whether the email has an account. |
| `POST /invitations/:token/accept` | The invited person | Signed in with the invited email, takes no body. Signed out, takes `name` and `password`, creates the account, and returns a session `token`. Returns the `site` to open and the `team`. |
| `PATCH /sites/:id/guests/:user` | Owner, admin | Takes `role`, `editor` or `viewer`. Changes a guest's role. |
| `DELETE /sites/:id/guests/:user` | Owner, admin, or the guest | Removes a guest. With your own user id, you leave the site. |
| `POST /sites/:id/transfer` | Owner of the site's team | Takes `team`, a team where you are owner or admin. Moves the site. |
| `GET /keys` | A session | Your keys, with `prefix`, `site_id`, `created_at`, and `last_used_at`. |
| `POST /keys` | A session | Takes `name` and `site`. Returns the new key once. |
| `POST /keys/:key/rotate` | A session | Gives the key a new secret and returns it once. |
| `DELETE /keys/:key` | A session | Revokes the key. |

The dashboard guide, [Use the dashboard](dashboard.md), covers the rest of **Settings**.
Links that let people outside the team read a site are in [Share a dashboard](sharing.md).

---

# Share a dashboard

You can let someone read a site's numbers without adding them to your team. A shared
link opens a read-only dashboard for one site, with an optional password, a fixed
segment, and an expiry date. A public site is readable by anyone who is signed out. Scripts
and AI tools read through the API with a key.

## Pick a way to share

| Option | Who can open it | What they can read | When access ends |
| --- | --- | --- | --- |
| Shared link | Anyone with the URL | One site, read-only | You delete the link, or it expires |
| Password link | Anyone with the URL and the password | One site, read-only | You delete the link, or it expires |
| Segment link | Anyone with the URL, and the password if it has one | Only the traffic that matches one saved segment | You delete the link, or it expires |
| Public site | Anyone who is signed out, in the dashboard, the API, and MCP | One site, read-only | You set `public` back to `false` |
| Team guest | A person with a misomoon account | One site, as a guest editor or guest viewer. See [Work with your team](teams.md). | You remove the guest |
| API key | A script that holds the key | Every site its owner can read, or one site, with the owner's role. See [API](api.md#authentication). | You revoke or rotate the key |
| MCP | An AI client that holds an API key | The same as the key. See [Ask AI tools about your traffic](mcp.md). | You revoke or rotate the key |

To create a shared link or make a site public, you need the editor role or above on the
site: owner, admin, editor, or guest editor. The **Sharing** tab in **Settings** shows
only for those roles.

## Create a shared link

1. Open **Settings** for the site.
2. Select the **Sharing** tab.
3. In the **Shared links** card, type a name in the **Name** field, such as the client's
   name.
4. To require a password, type one in **Password (optional)**. Leave it empty for a link
   that opens straight away.
5. In **Segment**, keep **All traffic**, or pick a saved segment to limit the link to it.
6. In **Expires**, pick **Never expires**, **7 days**, **30 days**, **90 days**, or
   **1 year**.
7. Select **Create link**.

The link appears in the list above the form. It shows a **password** label if it has a
password, the segment's name if it has a segment, and "until" with the end date if it
expires. Select the **Copy link** button next to it to copy the URL. The URL has this form:

```text
<your misomoon URL>/share/<slug>
```

For example, `https://analytics.example.com/share/k3m9x2abq`. The slug is 9 random
lowercase letters and digits. Anyone who has the URL can open the link, so send it only to
the people who should see the numbers.

A link without a name is called "Shared link". A name can be 80 characters at most.

### Create a link with the API

To create a link from a script, send `POST /api/v1/sites/:id/shared` with an API key that
has the editor role or above:

```sh
curl -X POST "https://analytics.example.com/api/v1/sites/shop/shared" \
	-H "Authorization: Bearer mm_..." -H "Content-Type: application/json" \
	-d '{"name": "Acme", "password": "a long passphrase", "expires_days": 30}'
```

Every field is optional:

- `name` is the label for the link.
- `password` locks the link. misomoon stores only a salted hash of it.
- `segment_id` is the `id` of a segment from `GET /api/v1/sites/:id/segments`.
- `expires_days` is the number of days until the link stops working, at most 3650. Leave
  it out for a link that never expires.

The response holds the `slug`. `GET /api/v1/sites/:id/shared` lists the site's links, and
`DELETE /api/v1/sites/:id/shared/:slug` deletes one.

## Protect a link with a password

To protect a link, type a password in **Password (optional)** when you create it. Send the
password to the viewer separately from the URL.

When a viewer opens a password link, the dashboard shows the link's name and the text
"This dashboard is shared with a password." The viewer types the password and selects
**Open**. A wrong password shows "wrong password". With the `STATS_LIMIT` rate limit
bound, each IP address gets 100 attempts per minute. After that, the dashboard shows "too
many attempts, wait a minute".

The link's name appears on the password page before the viewer unlocks it, so don't put
anything in the name that the viewer shouldn't see.

You can't add, change, or remove the password of an existing link. Create a new link with
the password you want, send the new URL, and delete the old link.

## Share only part of the data

A segment link shows only the traffic that matches a saved segment, such as one country,
one campaign, or one section of the site.

1. On the dashboard, add the filters you want with the filter bar.
2. Select **Segments**.
3. Type a name in **Segment name**.
4. Select **Everyone on the site sees it**, so the segment belongs to the site and not to
   you.
5. Select **Save current filters**.
6. Create a shared link and pick the segment in **Segment**.

The **Segment** list in **Settings** also offers your personal segments. Pick a site
segment instead. A personal segment is deleted with your account, and the link then shows
all traffic.

### What the segment fixes

misomoon applies the segment's filters to every query the link makes, on the server. That
covers each report, the live view, funnels, paths, and the CSV export.

A viewer can still add filters in the filter bar. A filter on a dimension that the segment
doesn't use narrows the data further. A filter on a dimension that the segment already
uses is dropped, and the segment's filter applies instead. A viewer can therefore see less
than the segment, but never more.

The dashboard doesn't show the segment's filters to the viewer as filter chips. The
numbers are smaller than the site's totals, and nothing on the page says why.

### Change a segment that a link uses

The link reads the segment's filters on every request. If you save a segment again with
the same name, the new filters replace the old ones, and every link that uses the segment
shows the new filters at once.

If you delete a segment, every link that used it shows all of the site's traffic. Delete
those links first, or create new links with another segment.

## Set an expiry

To make a link stop working on its own, pick a time in **Expires** when you create it. The
dashboard offers 7, 30, 90, or 365 days. The API takes any number of days up to 3650.

When a link expires, misomoon refuses every request made with it, including from viewers
who already unlocked it. Those requests fail with a `401` error that says the shared
link has expired. Opening the URL again shows an error that says "this link has expired or was
removed".

An expired link stays in the **Shared links** list until you delete it. You can't extend
an expiry. Create a new link instead.

## Stop sharing

To stop sharing a link, select the **Delete link** button next to it in the **Shared
links** list. The dashboard deletes the link without asking first.

Deleting a link ends every session opened from it. A viewer who has the dashboard open
loses access on the next request. The URL then shows an error that says "this link has
expired or was removed".

To stop sharing a public site, send `PATCH /api/v1/sites/:id` with `{"public": false}`, as
in [Make a site public](#make-a-site-public).

## Make a site public

A public site is readable by anyone who is signed out, with no link and no password. The
dashboard has no control for it, so you set it with the API.

1. Create an API key for the site in **Settings** > **Integrations**, or use one you
   have. The key acts with your role, so you need the editor role or above on the site.
2. Send `PATCH /api/v1/sites/:id` with `{"public": true}`:

```sh
curl -X PATCH "https://analytics.example.com/api/v1/sites/shop" \
	-H "Authorization: Bearer mm_..." -H "Content-Type: application/json" \
	-d '{"public": true}'
```

The response is the updated site. To make the site private again, send
`{"public": false}`. You can also pass `"public": true` when you create a site with
`POST /api/v1/sites`.

### What public means

A public site is open to everyone who reaches your misomoon URL signed out:

- The dashboard opens the site at `<your misomoon URL>/?site=<id>`. A visitor who is
  signed out sees every public site in the site menu, so they can find the site without
  the `id`.
- `GET /api/v1/sites` without a token lists every public site.
- The Stats API answers requests without a token for the site. Those requests share a
  limit of 100 per minute per IP address.
- The MCP server answers clients without a key. Its `list_sites` tool lists the public
  sites, and its read tools return their stats.

Anyone signed out can also read the site's goals, funnels, site segments, and
annotations. They can't change anything, because every change needs the editor role or
above. The site's daily usage stays hidden.

A person who is signed in to an account with no role on the site doesn't see a public
site in their dashboard. They can open it signed out, for example in a private window.

## Give a script or an AI tool read access

A script or an AI tool reads with an API key in the `Authorization: Bearer` header.
**Settings** > **Integrations** creates a key that reads only the current site. For a key
that reads every site you can see, use `POST /api/v1/keys` without a `site`.

A key acts with its owner's role. A key from an editor can also change the site, for
example its goals and shared links. For a key that can only read, have a person with the
viewer role create it. Viewers see the **Integrations** tab too.

- To connect Claude, Cursor, or another MCP client, follow [Ask AI tools about your traffic](mcp.md).
- To call the Stats API from a script, see [API](api.md), which lists the endpoints,
  parameters, and filters.

A script can also read through a shared link. `POST /api/v1/share/:slug` with
`{"password": "..."}` returns an `sh_` token. The token is read-only, reads one site, and
applies the link's segment to every query. It lasts 7 days at most, so the script trades
the link for a new token when the old one expires.

## What a viewer sees

A shared link opens the dashboard for one site, with "Shared, read-only view" in the
sidebar. The viewer can:

- open **Overview**, **Live**, **Funnels**, **Paths**, **Behavior**, and **Speed**
- pick a period and a comparison
- add filters, which the segment limits as described in
  [What the segment fixes](#what-the-segment-fixes)
- apply the site's segments from **Segments**
- run the site's saved funnels, and try steps without saving them
- download the CSV export with **Export CSV**

The viewer can't open **Settings**, save segments or funnels, sign in from the sidebar, or
see the site's daily usage. The keys `1` to `6` switch views, and `7` does nothing.

A viewer who is signed in to misomoon in the same browser still sees only the shared
link's site. The dashboard doesn't send their own session with requests from the link.

## How long a viewer stays unlocked

When a viewer opens a link, misomoon trades it, and the password if it has one, for a
read-only `sh_` token. The token lasts 7 days, or until the link expires if that comes
first.

The dashboard keeps the token for that browser tab. A new tab, or a reload after the token
expires, opens the link again. A link without a password unlocks itself with no prompt. A
link with a password asks for it again.

## Limits

- A link reads one site. To share two sites, create a link on each.
- You can't edit a link. To change its name, password, segment, or expiry, create a new
  link and delete the old one.
- A segment link limits the data, not the menus. A viewer sees the names and filters of
  the site's segments, and the site's goals, funnels, and annotations.
- The per-page reports in **Behavior**, such as the click and scroll reports for one page,
  replace every page filter with the page you pick, the segment's page filter too. If a
  segment filters by page, a viewer can open those reports for other pages.
- misomoon has no embed code or embed widget.

---

# Email reports and alerts

misomoon emails a site's numbers to the addresses you subscribe. It sends a weekly or
monthly report, an alert when traffic spikes, and an alert when the site stops sending
pageviews. It also sends account emails: invitations, password resets, and a notice when
a site reaches its daily ingest cap. This page shows how to set up each email, then lists
when each one goes out and what it contains.

## Set up an email provider first

misomoon sends no email until the API Worker has an email provider. Use Cloudflare Email
Service through the `EMAIL` binding, or Amazon SES through the `AWS_SES_REGION` variable
and the two `AWS_SES_*` secrets. Every email comes from `EMAIL_FROM`, which must be an
address on a domain that your provider verified. Set `PUBLIC_URL` to the address of your
dashboard too. The cron job sends reports and alerts without a request to take an address
from, so without `PUBLIC_URL` their links point to `https://misomoon.com`. To attach a PDF
to reports, add the `BROWSER` binding. [Bindings](configuration.md#bindings) lists each
binding, and [Variables](configuration.md#variables) lists each variable. Until a provider
is set up, the **Email reports** card says so and nothing goes out.

## Who can manage reports

The **Email reports** card is on the **Sharing** tab of **Settings**. The card and every
`/api/v1/sites/:id/reports` endpoint need the edit permission on the site. The owner,
admin, and editor team roles have it, and so does a guest editor of that site. Viewers and
billing members don't see the **Sharing** tab.

## Get a weekly report

1. Open **Settings** > **Sharing** and find the **Email reports** card.
2. Type the address in the email field.
3. In **Kind**, select **Weekly report**.
4. Click **Subscribe**.

The address appears in the list with a `weekly` label. The first report goes out on the
next Monday after 08:00 in the site's timezone and covers the Monday to Sunday before it.

For a monthly report, select **Monthly report** in **Kind** instead. It goes out on the 1st
of each month and covers the month before.

The address doesn't need a misomoon account. The server accepts any address of the form
`name@domain.tld` and stores it in lowercase. misomoon sends no confirmation email, and the
emails carry no unsubscribe link. To stop them, someone with the edit permission removes
the subscription, as described in [Unsubscribe an address](#unsubscribe-an-address).

## Get an alert when traffic spikes

1. In the **Email reports** card, type the address.
2. In **Kind**, select **Traffic spike**.
3. In **Visitors**, type how many visitors at once trigger the alert. Leave it empty to use
   10.
4. Click **Subscribe**.

Every 5 minutes, misomoon counts the visitors of the last 5 minutes. When the count reaches
your threshold, it emails "Traffic spike on" and the site name. The email gives the count,
the top source, and the most viewed page. Its **See who is here** button opens **Live** in
the dashboard. After an alert, the subscription sends nothing for 12 hours, however high
traffic goes.

## Get an alert when the site stops sending

A no-traffic alert tells you that the snippet was removed or the site is down. A spike alert
can't catch either case.

1. In the **Email reports** card, type the address.
2. In **Kind**, select **No traffic**.
3. In **Hours**, type how many hours without a pageview trigger the alert, from 1 to 168.
   Leave it empty to use 12.
4. Click **Subscribe**.

Every hour, misomoon counts the site's pageviews over the last `threshold` hours. If there
are none, and the site had pageviews in the 7 days before that window, it emails "No traffic
on" and the site name. A site with no pageviews in that week counts as quiet, not down, so a
new site or a site with very few visitors sends no alert.

The alert goes out once for each quiet spell. While the site stays quiet, misomoon sends
nothing more. After a pageview arrives, the next spell of `threshold` hours without one
sends a new alert.

## Change a threshold

Subscribe the same address with the same kind again, with the new number. A site keeps one
subscription for each address and kind, so the new threshold replaces the old one. An empty
field sets the threshold back to its default.

## Unsubscribe an address

Click the **Unsubscribe** button, the trash icon, next to the address in the list. With the
API, call `DELETE /api/v1/sites/:id/reports/:report` with the subscription's `id`.

## Preview a report

Click **Preview report**. A new tab opens the weekly report for the last full week, as
misomoon would send it now. To preview the monthly report, select **Monthly report** in
**Kind** first. With any other kind selected, the preview shows the weekly report.

The button opens the email's HTML. To see the PDF attachment, open
`GET /api/v1/sites/:id/reports/preview?kind=weekly&format=pdf`, or `kind=monthly`. The PDF
preview needs the `BROWSER` binding. Without the binding, it returns `501`. If Browser Run
can't print the report, it returns `503`.

## Send a test

Click **Send a test**. misomoon builds the report now and sends it to the address in the
email field. With the field empty, the test goes to the first address in the list. The test
is the monthly report when **Kind** is **Monthly report**, and the weekly report for every
other kind. It carries the PDF when Browser Run can print one.

Once the provider accepts the email, the button reads **Sent** for a moment. A test doesn't
change when the next scheduled report goes out. If no provider is set up, or the provider
refuses the email, the request fails with `503`.

## Change the timezone of reports

Report periods, send times, and the days on the report's chart follow the site's timezone.
To change the timezone, open **Settings** > **Sites**, select a **Timezone**, and click
**Save**. The **Name** field on the same card sets the site name that heads each report.

## When each email goes out

| `kind` | **Kind** in the dashboard | When it sends | `threshold` | How often at most |
| --- | --- | --- | --- | --- |
| `weekly` | Weekly report | On Monday, at the first hourly run after 08:00 in the site's timezone. It covers the last full week, Monday to Sunday. | Not used | Once a week |
| `monthly` | Monthly report | On the 1st, at the first hourly run after 08:00 in the site's timezone. It covers the last full month. | Not used | Once a month |
| `spike` | Traffic spike | When the visitors of the last 5 minutes reach `threshold`. misomoon checks every 5 minutes. | Visitors, a whole number of 1 or more. Default 10. | Once every 12 hours |
| `drop` | No traffic | When the site has had no pageview for `threshold` hours, after pageviews in the 7 days before. misomoon checks every hour. | Hours, a whole number from 1 to 168. Default 12. | Once for each quiet spell |

The cron trigger `*/5 * * * *` in `apps/api/wrangler.jsonc` runs every 5 minutes, and each
run checks spike alerts. The run at minute 15 of each UTC hour also sends weekly and
monthly reports and checks no-traffic alerts. In a timezone with a whole-hour offset,
reports therefore go out at 08:15 local time.

misomoon marks a subscription as sent only when the provider accepts the email. The
subscription list shows that date after the word "sent". If a report fails to send, the
next hourly run tries again, until the Monday or the 1st ends. A report that can't go out
on its day is skipped, not sent later. A spike alert that fails to send is tried again at
the next 5-minute run. Amazon SES gets one more try after 250 ms when it answers `429`. A
`5xx` from SES gets no second try, because SES may have sent the email already.

In each run, misomoon builds one edition for each site and kind and sends it to every
subscriber. Browser Run prints the PDF once for that edition, however many people
subscribe.

## What a report contains

The subject reads "Weekly report for", the site name, and the visitor count, for example
`Weekly report for Shop: 1,234 visitors`. When the site took payments, the subject adds the
revenue. Each report compares its period with the same number of days just before it. The
email has an HTML version, laid out as a small newspaper, and a plain-text version with the
same numbers.

- **Front page.** The site name, the edition, such as `Week 42, 2026` or `No. 10, 2026`, and
  the issue date. The headline names the biggest move: visitors up or down by 10% or more,
  else the revenue, else the visitor count. Two or three sentences say how many people came,
  where most came from, and which day was busiest. A chart shows visitors per day, with the
  period before as a dashed line. A table compares visitors, visits, pageviews, views per
  visit, bounce rate, and visit duration with the period before. Revenue joins the table
  when either period had any.
- **Business.** This page appears only when either period had revenue. It shows the total
  revenue, the average payment, the revenue per visitor, the revenue of the period before,
  and up to 4 top paying sources. It counts payments in the site's currency only, and leaves
  out payments in other currencies.
- **Arrivals.** The top 5 sources, each with its change against the period before, and the 5
  most read pages.
- **World.** The top 5 countries and the top 4 devices.
- **Back page.** The scoreboard lists up to 5 goals with their conversions and conversion
  rates, when the site has goals. The almanac lists the busiest day, the quietest day, the
  most read page, the top source, the top country, and the top device. The **Open the
  dashboard** button opens the dashboard on the report's dates. The last line gives the date
  of the next edition.

A page with no data to show is left out. A period with no visitors gets the headline "A quiet
week" or "A quiet month", and a reminder to check that the snippet is still on the site.

## The PDF attachment

Weekly and monthly reports carry a PDF of the same pages, one sheet per page. Browser Run
prints it through the `BROWSER` binding. The file is named after the site's domain and the
period: `<domain>-week-<week>-<year>.pdf` with the ISO week number, or
`<domain>-<YYYY-MM>.pdf`.

The report goes out without the PDF in these cases:

- The `BROWSER` binding is missing.
- The print fails, for example when the browser time is used up or the print times out. The
  log then has a `report pdf failed` line.
- The Worker runs in `wrangler dev`, which can't print.

Alerts and account emails never carry a PDF.

## What an alert contains

| `kind` | Subject | Body | Button |
| --- | --- | --- | --- |
| `spike` | `Traffic spike on <site name>` | How many people are on the site right now, the top source, and the most viewed page | **See who is here** opens **Live** |
| `drop` | `No traffic on <site name>` | How many hours have passed without a pageview, and that the snippet may have been removed or the site may be down | **Check the site** opens the dashboard |

## Other emails misomoon sends

| Email | Subject | Who gets it | When | Link |
| --- | --- | --- | --- | --- |
| Invitation | `Join <team or site name>` | The invited address | An owner or admin invites someone to the team, or to one site as a guest. | `/invite/<token>`, which works for 7 days. A new invitation to the same address replaces the earlier one. |
| Password reset | `Reset your password` | The address of the account | Someone clicks **Forgot your password?** on the sign-in screen and enters an address that has an account. | `/reset/<token>`, which works for 1 hour. A new request replaces earlier links. |
| Daily-cap notice | `Tracking for <domain> is paused until 00:00 UTC` | The team's owners and admins | The daily ingest cap drops an event for the site for the first time on a UTC day. A blocked site, with a cap of `0`, gets no notice. | The dashboard |

Links in invitations and password resets use `PUBLIC_URL`, or the address of the request
when `PUBLIC_URL` is unset. Links in reports, alerts, and the daily-cap notice use
`PUBLIC_URL`, or `https://misomoon.com`. Without an email provider, the dashboard shows
each invitation link for you to send another way. [Teams](teams.md) covers invitations,
roles, and password resets. [Daily ingest cap](configuration.md#daily-ingest-cap) explains
the cap.

## When an email doesn't arrive

Follow the steps in [Emails don't arrive](troubleshooting.md#emails-dont-arrive). To see why
a send failed, run `wrangler tail` in `apps/api` and look for these lines:

| Log line | What it means |
| --- | --- |
| `email skipped: no email provider set up` | No provider is set up, or `EMAIL_PROVIDER` names one that isn't. Nothing went out. |
| `email failed` | The provider refused the email. The line names the provider, the subject, and the provider's error code. |
| `report failed` | Building or sending a weekly or monthly report, or checking a no-traffic alert, threw an error. The line carries the subscription `id`. |
| `alert failed` | Checking or sending a spike alert threw an error. The line carries the subscription `id`. |
| `report pdf failed` | Browser Run couldn't print the PDF. The report went out without it. |
| `cap email failed` | Sending the daily-cap notice threw an error. |

If report links point to `misomoon.com`, see
[Links in email reports point to misomoon.com](troubleshooting.md#links-in-email-reports-point-to-misomooncom).

## API reference

Each endpoint needs the edit permission on the site. [Sites](api.md#sites) lists the other
site collections.

| Method and path | What it does |
| --- | --- |
| `GET /api/v1/sites/:id/reports` | Returns `subscriptions`, each with `id`, `email`, `kind`, `threshold`, and `last_sent_at` in milliseconds, and `sending`, which is `true` when an email provider is set up. |
| `POST /api/v1/sites/:id/reports` | Subscribes `email` to `kind`, one of `weekly`, `monthly`, `spike`, or `drop`, with an optional `threshold`. Returns `201`. A second call with the same `email` and `kind` replaces the threshold. A missing or malformed `email`, an unknown `kind`, or a `threshold` out of range returns `400`. A `threshold` is a whole number: 1 or more visitors for `spike`, and 1 to 168 hours for `drop`. Reports store no threshold. |
| `DELETE /api/v1/sites/:id/reports/:report` | Removes one subscription. Returns `204`. |
| `GET /api/v1/sites/:id/reports/preview` | Returns the report as HTML. `kind=monthly` gives the monthly report, and any other value the weekly one. `format=pdf` returns the PDF, or `501` without the `BROWSER` binding, or `503` when the print fails. |
| `POST /api/v1/sites/:id/reports/test` | Sends the report for `kind` to `email` now, with the PDF when one prints. `kind=monthly` gives the monthly report, and any other value the weekly one. Returns `{"ok": true}`, `400` without `email`, or `503` when no provider is set up or the provider refuses the email. |

To subscribe an address to no-traffic alerts after 6 hours:

```sh
curl -X POST "https://analytics.example.com/api/v1/sites/shop/reports" \
	-H "Authorization: Bearer $MISOMOON_KEY" -H "Content-Type: application/json" \
	-d '{"email": "ops@example.com", "kind": "drop", "threshold": 6}'
```

---

# Ask AI tools about your traffic

misomoon has a built-in MCP server at `/mcp` on your dashboard host. Claude Code,
Claude Desktop, Cursor, and other MCP clients can use it to read your analytics. They
call the same query functions as the dashboard and the Stats API, so the numbers match.

Your client runs the model, so the server needs no AI key or extra setup.

## Create a key

1. In the dashboard, open **Settings** > **Integrations** for a site.
2. In **Connect AI tools (MCP)**, select **Create API key for** your site.
3. Copy the command or the JSON that appears. The key is shown only once.

That key reads one site. When the site already has a key, the card lists it with a
**Rotate** button instead. Rotating gives the key a new secret, and tools that use the
old secret stop working until you paste the new one.

To read every site you can see, create a key with no site through the API:
`POST /api/v1/keys` with a `name` and no `site` ([API keys](api.md#accounts-and-teams)).
A key acts with the role of the person who created it, so it loses access when they
do. **Settings** > **Account** lists all your keys, and you revoke a key there.

Without a key, the server answers as a signed-out visitor and reads only public sites.

## Connect a client

In the examples, replace `analytics.example.com` with your dashboard host and `mm_...`
with your key.

### Claude Code

```sh
claude mcp add --transport http misomoon https://analytics.example.com/mcp --header "Authorization: Bearer mm_..."
```

### Claude Desktop, Cursor, and other clients

Add this server to the client's MCP configuration file. For Cursor, the file is
`~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project.

```json
{
  "mcpServers": {
    "misomoon": {
      "type": "http",
      "url": "https://analytics.example.com/mcp",
      "headers": { "Authorization": "Bearer mm_..." }
    }
  }
}
```

If a client supports only local stdio servers, use a bridge such as
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "misomoon": {
      "command": "npx",
      "args": ["mcp-remote", "https://analytics.example.com/mcp", "--header", "Authorization: Bearer mm_..."]
    }
  }
}
```

### Check the connection

Ask the client a question such as "How many visitors did my site have last week, and
where did they come from?" It should call `list_sites`, then `get_aggregate` and
`get_breakdown`.

## Tools

| Tool | What it returns |
| --- | --- |
| `list_sites` | The sites the key can read, with id, domain, and timezone. |
| `get_aggregate` | Headline metrics for a period, with an optional comparison. |
| `get_timeseries` | The headline metrics in buckets over time. |
| `get_breakdown` | Metrics grouped by one dimension, such as source, page, or country. |
| `get_goal_conversions` | Visitors, conversion rate, and revenue for each goal. |
| `get_realtime` | Visitors in the last 5 minutes and a live event feed. |
| `get_web_vitals` | p75 and good, needs-improvement, and poor counts for LCP, INP, CLS, FCP, and TTFB. |
| `run_funnel` | Conversion through up to 8 page or event steps. |
| `get_journeys` | The most common paths through the site. |
| `get_search_terms` | Google Search Console queries, if the site is connected. |
| `get_page_interactions` | Clicks, scroll depth, site search, JavaScript errors, forms, media, or tagged content, one report at a time, for the site or one page. |
| `add_annotation` | Adds a note to the site timeline, such as a deploy. Needs the editor role or above. |
| `list_dimensions` | Every dimension that breakdowns and filters accept. |

The read tools take a `site` id, a `period`, `from` and `to` for a `custom` period,
and `filters`. They differ from the [Stats API](api.md#query-parameters) in three
ways:

- `period` is one of `today`, `yesterday`, `24h`, `7d`, `28d`, `30d`, `90d`, `mtd`,
  `lastmonth`, `ytd`, `6mo`, `12mo`, `all`, or `custom`. The default is `30d`. There is
  no `realtime` period: call `get_realtime` instead.
- `filters` is one string of filters joined by `;`, such as
  `page==/blog/*;channel==Organic Search`. Each filter is `<dimension><op><value>`,
  with the operators `==`, `!=`, `~` (contains), and `!~`. Join values with `|` to
  match any of them.
- `limit` is 100 at most.

`compare` takes `previous` or `year`. `run_funnel` takes 2 to 8 steps, and
`get_journeys` takes a `path` of up to 6 pages. `add_annotation` takes `text` of up to
200 characters and an optional ISO `ts`, which defaults to now.

## Limits

- The server is stateless JSON-RPC over Streamable HTTP. It answers `POST` only and
  does not stream.
- It supports the MCP protocol versions `2025-11-25`, `2025-06-18`, `2025-03-26`, and
  `2024-11-05`.
- A request body can be 64 KB at most, and a batch can hold 20 requests at most.

---

# First-party proxy

Ad blockers and privacy browsers drop requests to known analytics hosts. Serving
misomoon from the site's own domain makes the tracker and its beacons first-party, so
they count the visitors a third-party script would miss.

There are two ways to do it. Both are in the dashboard under **Settings** > **Install**,
in the **Proxy** card, filled in for the current site.

## 1. Managed subdomain

The site adds one DNS record:

```
stats.example.com  CNAME  proxy.misomoon.com
```

and enters `stats.example.com` in Settings. misomoon registers it as a Cloudflare for
SaaS custom hostname, Cloudflare issues the certificate (HTTP validation, usually a few
minutes once the CNAME resolves), and the site loads:

```html
<script defer src="https://stats.example.com/m.js?s=example"></script>
```

The browser talks to that hostname directly, so the visitor's IP and full location
arrive exactly as without a proxy. On a customer hostname the Worker only answers
`/m.js`, `/api/event` and `/overlay.js`; everything else is a 404.

The hostname must be a subdomain of the site's domain (not `www`), one per site.
If Cloudflare asks for TXT records (for example while the CNAME is proxied through
another CDN), Settings lists them next to the CNAME.

API (needs the edit permission, so an editor's session or an API key for the site works):

| Method | Path | |
|---|---|---|
| `GET` | `/api/v1/sites/:id/proxy` | state; refreshes from Cloudflare until live |
| `PUT` | `/api/v1/sites/:id/proxy` | `{ "hostname": "stats.example.com" }` |
| `DELETE` | `/api/v1/sites/:id/proxy` | removes the custom hostname |

### Enabling it on your own deployment

1. On the zone that owns the target (say `misomoon.com`), enable Cloudflare for SaaS,
   create `proxy.misomoon.com` (proxied) and set it as the fallback origin.
2. Route customer hostnames to the Worker: add `{ "pattern": "*/*", "zone_name":
   "misomoon.com" }` to `routes` in `apps/api/wrangler.jsonc`, after the app's own route.
3. Set `CF_ZONE_ID` and `PROXY_CNAME_TARGET` as vars and `CF_API_TOKEN` as a secret
   (token permission: *SSL and Certificates: Edit* on that zone).
4. Apply the control migrations. `migrations/control/0001_init.sql` creates the `proxy_domains` table.

Without these settings `GET …/proxy` reports `available: false`, `PUT` answers 501
and the dashboard points to the snippets.

## 2. One-click deploy

Templates in `templates/` deploy a ready proxy to the site owner's own account, then
they add a subdomain to it:

| | Button | Then add the domain under |
|---|---|---|
| Cloudflare Worker (`templates/proxy-cloudflare`) | [Deploy to Cloudflare](https://deploy.workers.cloudflare.com/?url=https://github.com/jackzard/misomoon/tree/main/templates/proxy-cloudflare) | Worker → Settings → Domains & Routes |
| Vercel (`templates/proxy-vercel`) | [Deploy with Vercel](https://vercel.com/new/clone?repository-url=https://github.com/jackzard/misomoon/tree/main/templates/proxy-vercel&project-name=misomoon-proxy&repository-name=misomoon-proxy) | Project → Settings → Domains |

Both buttons clone from GitHub, so the repository has to be public. The Worker reads
`MISOMOON_URL` (default `https://app.misomoon.com`); the Vercel template has it in
`vercel.json`. The links come from `deployLinks()` in `packages/core/src/snippets.ts`.

## 3. Your own proxy

Map three paths under a prefix of your choice to misomoon:

| On your site | Upstream |
|---|---|
| `<prefix>/m.js` | `https://app.misomoon.com/m.js`, with the query string |
| `<prefix>/api/event` | `https://app.misomoon.com/api/event` |
| `<prefix>/overlay.js` | `https://app.misomoon.com/overlay.js` |

`m.js?s=<site id>` carries the site id, and the server adds the code for the features
ticked in the site settings ([tracking guide](tracking.md#choose-what-to-track)). Pass
the query string through: without it the tracker doesn't know the site and counts
nothing.

`overlay.js` loads only on a page the dashboard opens to draw clicks over it
([tracking guide](tracking.md#see-what-people-do-on-a-page)). A proxy without it still
tracks everything, but **Show on your site** stays empty.

Then load `<script defer src="<prefix>/m.js?s=example">`. The tracker posts to
`api/event` next to wherever its script came from, so there is nothing else to
configure (`data-api` still overrides it). Pick a neutral prefix: words like
`analytics`, `tracking` or `stats` are on filter lists. The default is `/relay`.

Ready-made versions live in `packages/core/src/snippets.ts` (Settings shows them with
your site's values): Cloudflare Worker, Next.js, Vercel, Netlify, Nginx, Caddy and
SvelteKit.

In Next.js, `withMisomoon()` from `@misomoon/sdk/next` adds the same three rewrites to
your config ([SDK guide](sdk.md#serve-the-tracker-from-your-nextjs-app)).

### Visitor IP and location

Behind a proxy the request reaches misomoon from the proxy, so the Worker reads the
visitor from headers (`edgeFromRequest` in `packages/core/src/proxy.ts`):

- **IP**, used only for the daily visitor hash and never stored: `x-misomoon-ip`, else
  the first `X-Forwarded-For` hop, else `X-Real-IP` and friends.
- **Location**: `x-misomoon-country`, `-region`, `-city`, `-continent`, `-timezone`,
  `-as-org` (URL-encoded), else Vercel's `x-vercel-ip-*`, Netlify's `x-country`, or
  `cf-ipcountry`. Without any of them, location is unknown; visitors still count.
- A request counts as proxied when the forwarded IP differs from the connecting one
  and the request carries a proxy's mark: `x-misomoon-ip`, Vercel's `x-vercel-id`,
  Netlify's `x-nf-request-id`, Cloudflare's `cf-worker`, or an `X-Forwarded-Host` for
  another host. A bare `X-Forwarded-For` (corporate proxies, VPNs) is ignored. Then Cloudflare's own geo and bot score describe the proxy, so they are ignored;
  user-agent bot detection still runs.

| Setup | Location |
|---|---|
| Managed subdomain, Cloudflare Worker | full |
| Vercel, Next.js on Vercel, Netlify, SvelteKit on Cloudflare | what the platform forwards |
| Nginx, Caddy, other self-hosted | unknown, unless you add `x-misomoon-country` (e.g. from the GeoIP2 module or `CF-IPCountry` when Cloudflare sits in front) |

Anyone can send these headers, which only lets them misreport their own visit; the
same is true of any beacon, and the site's hostname check still applies.

The Worker, SvelteKit, Nginx and Caddy snippets drop the site's cookies on the way
through. Platform rewrites (Next.js, Vercel, Netlify) forward them; misomoon never reads
or stores cookies.

---

# Upgrade misomoon

New versions are listed in the [changelog](../CHANGELOG.md) and on the
[releases page](https://github.com/jackzard/misomoon/releases). Read the notes for every
version between yours and the new one before you upgrade.

An upgrade keeps your data. The deploy applies new migrations to every database, and
migrations only add to the schema. To roll back, deploy the previous version again.
The extra columns or tables that a newer migration added stay, and the older code
ignores them.

## Upgrade a command-line install

1. Get the new version:

   ```sh
   git pull
   pnpm install
   ```

   If you keep your own fork, merge the upstream `main` branch into it instead. Keep
   your database ids in `apps/api/wrangler.jsonc`.

2. Deploy:

   ```sh
   pnpm --filter @misomoon/api run deploy
   ```

   The deploy applies new migrations, and then deploys the Worker.

## Upgrade a Deploy to Cloudflare install

The button copied the deploy bundle into a repository that you own. Cloudflare deploys
that repository again each time you push to it. To upgrade, copy the new bundle into
your repository, and keep your own `wrangler.jsonc`, which holds your database ids.

1. Clone your repository, and go into it:

   ```sh
   git clone https://github.com/<you>/<your-repo>.git
   cd <your-repo>
   ```

2. Download the latest bundle:

   ```sh
   curl -L https://github.com/jackzard/misomoon/archive/refs/heads/deploy.tar.gz | tar xz
   ```

3. Copy it over your files, but keep your `wrangler.jsonc`:

   ```sh
   rsync -a --exclude wrangler.jsonc misomoon-deploy/misomoon/ ./
   rm -rf misomoon-deploy
   ```

4. Compare the new `wrangler.jsonc` with yours:

   ```sh
   curl -sL https://raw.githubusercontent.com/jackzard/misomoon/deploy/misomoon/wrangler.jsonc | diff wrangler.jsonc -
   ```

   Copy new settings into your file, such as a new variable or a new
   `compatibility_date`. Don't copy the `database_id` values.

5. Commit and push:

   ```sh
   git add -A
   git commit -m "Upgrade misomoon"
   git push
   ```

   Cloudflare builds and deploys the push. The `deploy` script applies the new
   migrations first.

## Scale the shards

Events and visits live in the shard databases. A D1 database holds up to 10 GB. When a
shard reaches `SHARD_SOFT_LIMIT_MB` (8,000 MB by default), it stops taking new days of
data, and its sites continue on another shard. Add shards before every shard is near
the limit. To see the size of each database, open **Storage & Databases** > **D1** in
the Cloudflare dashboard.

More shards also spread the writes. One D1 database handles one write at a time, so a
busy instance with many sites is faster with more shards.

### Command-line installs

Set `SHARD_COUNT` to the number of shards you want, and deploy:

```sh
SHARD_COUNT=4 pnpm --filter @misomoon/api run deploy
```

The deploy creates the new databases, binds them, migrates them, and deploys. A new
shard registers itself on the next request, and it takes most new sites because it has
the most free space. To see the plan without changing anything, add `--plan`:

```sh
SHARD_COUNT=4 pnpm --filter @misomoon/api run deploy -- --plan
```

To remove shards, deploy with a smaller `SHARD_COUNT`. The extra shards are marked
`retiring`, and the Worker moves their data to the other shards every 5 minutes. Run
the same deploy again later. It unbinds each retiring shard after it is empty. The
script never deletes a database. Delete an empty one yourself with
`wrangler d1 delete <name>`.

### Deploy to Cloudflare installs

1. Create a database:

   ```sh
   npx wrangler d1 create misomoon-shard-2
   ```

   If your other databases are in the EU jurisdiction, add `--jurisdiction eu`.

2. Add it to `d1_databases` in your `wrangler.jsonc`, with the id that the command
   printed:

   ```jsonc
   { "binding": "SHARD_2", "database_name": "misomoon-shard-2", "database_id": "<id>", "migrations_dir": "migrations/shard" }
   ```

3. Commit and push. The `deploy` script migrates every `SHARD_*` binding, and the new
   shard registers itself.

To remove a shard from this kind of install, use a command-line install, because the
data has to move first.

---

# Troubleshooting

To see what the Worker does, stream its logs:

```sh
npx wrangler tail misomoon
```

Use the name of your Worker. Command-line installs are called `misomoon-api`.

## No visits appear in Live

1. Reload your site and open the browser console. A browser the tracker doesn't count
   says why, once, as `misomoon skipped: <reason>`.
2. Check the reason:

   | Reason | What to do |
   | --- | --- |
   | `site` | The script URL has no site id. Load `m.js?s=<site id>`, and if a proxy serves it, pass the query string through. |
   | `bot` | The browser is driven by automation (`navigator.webdriver`). |
   | `ignored` | This browser has `misomoon_ignore` set. Run `localStorage.removeItem('misomoon_ignore')`. |
   | `overlay` | The page was opened from the dashboard to draw clicks on it. |

3. If the console shows nothing, open the **Network** tab, and look for the request to
   `api/event`:
   - If there is no request, or it shows `blocked`, an ad blocker dropped it.
     [Serve the tracker from your own domain](PROXY.md).
   - If the browser reports a Content Security Policy error, add your misomoon host to
     `script-src` and `connect-src`.
   - If the response is `202`, the request arrived. Check that `?s=` on the script URL
     is the site id shown in **Settings**, not the domain. Check that the page is on the
     site's domain or one of its subdomains: `localhost` is not, so a local copy of the
     site counts nothing. Check the site's path rules under **Settings** > **Install**.

The endpoint always answers `202`, even for an event it drops. It drops events from
bots, events for a site id that doesn't exist, and events from a page on another
domain.

## The deploy fails

- **`Queue misomoon-events does not exist`**: An older deploy script didn't create the
  queues. Create them, and deploy again:

  ```sh
  npx wrangler queues create misomoon-events
  npx wrangler queues create misomoon-events-dlq
  ```

- **A D1 database is not found**: A `database_id` in `wrangler.jsonc` doesn't exist in
  this account, for example after you copied the file from another account. On a
  command-line install, set the id back to its placeholder, such as
  `00000000-0000-0000-0000-000000000001`, and the deploy creates the database.
- **`pnpm deploy` copies files into a folder instead of deploying**: `deploy` is a
  built-in pnpm command. Use `pnpm --filter @misomoon/api run deploy`.

## Sign-up says "sign-up is by invitation on this server"

Either `SIGNUPS` is `invite` and the instance already has an account, or `SIGNUPS` is
`closed`. Ask a team owner or admin to invite you from **Settings** > **Team**. An
invitation works whatever `SIGNUPS` says. [Work with your team](teams.md) covers
invitations.

## Emails don't arrive

1. Check that one email provider is set up: the `EMAIL` binding or the three `AWS_SES_*`
   settings. If you set `EMAIL_PROVIDER`, check that it names that provider.
2. Check that `EMAIL_FROM` uses an address on a domain that the provider verified.
   The default address is on `misomoon.com`, and your provider refuses it.
3. Look for `email failed` lines in `wrangler tail`. They name the provider and its error
   code, for example `E_SENDER_DOMAIN_NOT_AVAILABLE` from Cloudflare Email Service.

## A site stops recording events during the day

The site reached its daily ingest cap. Its owners and admins got an email named
"Tracking for ... is paused until 00:00 UTC". `GET /api/v1/sites/:id/usage` shows
`"capped": true` for that day. To give the site a higher cap, see
[Daily ingest cap](configuration.md#daily-ingest-cap).

## Links in email reports point to misomoon.com

Set the `PUBLIC_URL` variable to the address of your dashboard, for example
`https://analytics.example.com`.

## The API returns 429

The Stats API allows 100 requests a minute for each API key, or for each IP address
when the caller has no key. Signed-in dashboards and shared links aren't limited.
Sign-up, sign-in, password resets, invitation accepts, and shared-link passwords share
the same limit for each IP address. Wait a minute, or spread the requests out.

## Google import fails with `redirect_uri_mismatch`

In your Google Cloud OAuth client, add `<your misomoon URL>/api/v1/google/callback` as an
authorized redirect URI. misomoon builds the redirect from the address you open the
dashboard on, not from `PUBLIC_URL`, so add one URI for each address you use, such as
the `workers.dev` URL and a custom domain.

## Events reach the dead-letter queue

The queue retries a batch 5 times, and then moves it to `misomoon-events-dlq`. This
happens when the shard databases fail for a long time. Look for errors in
`wrangler tail`. If the queue itself can't take an event, for example because the Free
plan's daily limit is used up, the Worker writes the event straight to the database, so
it isn't lost.

## Still stuck

Open a [discussion](https://github.com/jackzard/misomoon/discussions), or
[report a bug](https://github.com/jackzard/misomoon/issues/new/choose). Include the
version, how you deployed, and the error. Remove API keys and other secrets first.

---

# What the numbers mean

This page defines every number and every dimension that misomoon reports, as the code
computes them. The dashboard, the Stats API, and the MCP tools call the same functions in
[`apps/api/src/stats.ts`](../apps/api/src/stats.ts), which build their SQL in
[`packages/core/src/queries.ts`](../packages/core/src/queries.ts), so one number means the
same thing everywhere. [The API reference](api.md) lists the parameters and response
fields. [Use the dashboard](dashboard.md) shows where each number appears.

## Headline metrics

The KPI tiles, `GET /api/v1/stats/aggregate`, and every point of
`GET /api/v1/stats/timeseries` return these nine metrics. A metric read from events counts
the events whose time falls in the period. A metric read from visits counts the visits
that started in the period.

| Dashboard tile | API name | Read from | Definition | Unit |
| --- | --- | --- | --- | --- |
| **People** | `visitors` | Events | Distinct visitor ids among the pageviews and custom events. Engagement pings don't count, and neither do payments without a visit on their UTC day. | Count |
| **Visits** | `visits` | Visits | Visits that started in the period. | Count |
| **Pageviews** | `pageviews` | Events | `pageview` events. | Count |
| **Pages per visit** | `views_per_visit` | Visits | The pageviews of the visits that started in the period, divided by `visits`. | Rounded to 2 decimals |
| **Left at once** | `bounce_rate` | Visits | Bounced visits as a percent of visits. [Bounces](#a-bounce-is-a-visit-with-one-pageview-and-no-interaction) has the rule. | Percent, 1 decimal |
| **Time per visit** | `visit_duration` | Visits | Summed visit durations divided by `visits`. [Visit duration and time on page](#visit-duration-and-time-on-page-measure-different-things) has the rule. | Whole seconds |
| None | `events` | Events | Every event that is not a `pageview` or an `engagement`: custom events, the events the tracker sends by itself, and `Payment` and `Refund` events. Events sent with `interactive: false` count here too. | Count |
| **Revenue** | `revenue` | Events | The sum of the amounts on events, net of refunds, in the site's currency. | Site currency, 2 decimals |
| None | `average_revenue` | Events | `revenue` divided by the number of events with an amount above zero. Refunds don't count in that number. | Site currency, 2 decimals |

`pageviews` and `views_per_visit` can disagree. `pageviews` counts views by their own
time, and `views_per_visit` counts the views of visits that started in the period, even
when a view happened after the period ended.

Each site has one reporting currency, `USD` unless you set another. `revenue` and
`average_revenue` count the events in that currency and the events sent without a
currency. They never add up amounts in different currencies. The amount on a tracker or
SDK event is kept between 0 and 1,000,000,000. Refunds come from payment webhooks as
negative amounts. [Connect payments](revenue.md) explains how a payment finds its visit.

### Compare with an earlier period

With `compare=previous` the comparison period is the stretch of the same length right
before the current one. With `compare=year` it is the same dates a year earlier. `change`
holds one value per metric:

| Metric | `change` |
| --- | --- |
| `bounce_rate` | The difference in percentage points, rounded to 1 decimal. |
| Every other metric | The percent change from the earlier period, rounded to 1 decimal. It is `0` when both periods are `0`, and `null` when only the earlier period is `0`. |

## A visitor id lasts one UTC day

misomoon sets no cookies and stores nothing on the device. To count people, the Worker
hashes a random salt, the site id, the IP address, and the user agent with SHA-256, and
keeps the first 16 hex characters as `visitor_id` (`visitorId` in
[`packages/core/src/ingest.ts`](../packages/core/src/ingest.ts)). Each UTC day has its
own salt. The Worker makes it on first use and keeps it in the `salts` table of
`CONTROL`. The hourly maintenance job deletes salts that are more than two days old.
The IP address is never stored.

These rules follow from the daily salt:

- The same person gets a new id at 00:00 UTC. A visitor count over several days is the
  sum of each UTC day's unique visitors. Someone who visits on 5 days of a month counts
  5 times in that month's `visitors`.
- The salt rotates at 00:00 UTC, not at the site's local midnight. A local day, a
  `today` period, or a `24h` period that spans 00:00 UTC can count one person twice.
- Two people behind one IP address with the same user agent share an id that day. One
  person on two devices, or with two browsers, has two ids.
- Breakdown rows, funnels, paths, and page interaction reports count visitors by the same
  id.

[Why is a visitor unique only for one day?](faq.md#why-is-a-visitor-unique-only-for-one-day)
gives the short answer.

### Unique counts add up across shards

A site's data lives in ranges of whole UTC days, one shard per range
([Sharding](ARCHITECTURE.md#sharding)). A day never spans two shards, and an id never
lasts past its day, so no visitor appears on two shards. misomoon counts distinct
visitors on each shard and adds the counts. For a rate such as `bounce_rate`, it adds the
numerators and the denominators of every shard first and divides once. It never averages
a rate across shards.

## A visit ends after 30 minutes without activity

A visit, called a session in the code, is a run of events from one visitor id. The
Worker assigns each event to a visit in `assignSessions` in
[`packages/core/src/ingest.ts`](../packages/core/src/ingest.ts), with `SESSION_GAP` set to
30 minutes:

| Rule | Effect |
| --- | --- |
| An event comes within 30 minutes of the visit's last activity | It joins that visit. Engagement pings count as activity, so a visitor who reads one page for an hour keeps one visit. |
| An event comes more than 30 minutes after the last activity | A pageview or a custom event starts a new visit. An engagement ping is dropped. |
| A visit is open at 00:00 UTC | In the first 30 minutes of a UTC day the Worker also computes the visitor's id under yesterday's salt, so the visit carries on. Each event keeps its own day's id. If the site moved to another shard at that midnight, the visit splits in two. |
| A later event in the visit has a new referrer or new UTM tags | It stays in the visit and takes the visit's source, channel, referrer, and UTM values. A new campaign doesn't start a new visit. |

A visit takes its source, channel, referrer, UTM tags, hostname, location, browser,
operating system, device, screen, and language from its first event, and keeps them.
Reports read these columns of the visit, which the Worker updates as events arrive:

| Column | Meaning |
| --- | --- |
| `entry_path` | The path of the visit's first event. The `entry_page` dimension reads it. |
| `exit_path` | The path of the visit's latest pageview. The `exit_page` dimension reads it. |
| `pageviews` | The visit's pageviews. |
| `events` | The visit's interactive custom events, which is all that bounce rate needs. |
| `duration_ms` | The time from the first event to the latest pageview or custom event. |

Payments never change a visit. A `Payment` or `Refund` row joins the visit's visitor id
only when the payment comes on the UTC day of the visit. Otherwise its `visitor_id` is
empty and no visitor count includes it.

## A bounce is a visit with one pageview and no interaction

A visit is a bounce when it has at most one pageview and no interactive custom event.
The SQL test is `pageviews <= 1 AND events = 0` on the visit's row.

| Event in the visit | Ends the bounce |
| --- | --- |
| A second `pageview` | Yes |
| A custom event | Yes |
| A custom event sent with `interactive: false` (`i: false` on the beacon) | No |
| `Outbound link`, `Download`, `Form sent`, or `404` from the tracker | Yes, always. `interactive: false` has no effect on them. |
| `engagement` (engaged time, scroll, Web Vitals, clicks) | No |
| `Payment` or `Refund` from a webhook | No |

Under a `page` filter, bounce rate counts only the visits that entered on a matching page,
in the numerator and in the denominator. A page row in a breakdown takes its bounce rate
from the visits that entered on that page.

Imported history from Google has no bounces, so misomoon counts a session that Google
didn't mark as engaged as a bounce.

## Visit duration and time on page measure different things

| | Visit duration (`visit_duration`) | Time on page (`time_on_page`) |
| --- | --- | --- |
| Where it shows | KPI tiles, and breakdown rows of visit dimensions, pages, and goals | Page breakdown rows |
| Measured from | The visit's events | The engagement pings of each page |
| What counts | The time from the visit's first event to its latest pageview or custom event | Engaged time: the time the page is shown and the browser window has focus |
| Engagement pings | Keep the visit open, but don't make it longer | Carry the time |
| A visit with one pageview | Lasts `0` seconds | Has the engaged time it sent |
| Average over | Every visit in the scope, bounces included | Each visit that sent engaged time for the page |
| Unit | Whole seconds | Whole seconds |

`m.js` sends an engagement ping when the page is hidden or the route changes. It doesn't
send one for under one second of engaged time, unless a feature, such as clicks or Web
Vitals, has data to send. The Worker keeps at most 6 hours of engaged time per ping. A
visit that opens the same page twice adds the engaged time of both views. Time on page
divides the summed time of each page by the number of visits that sent time for it.

## Scroll depth is the deepest point of each visit

The tracker records the lowest point of the page that came into view: the scroll position
plus the window height, as a percent of the page height. The Worker keeps it between 0
and 100 and rounds it to a whole number. A page that fits in the window reports 100.

| Where | Value |
| --- | --- |
| `scroll_depth` on a page row | The average of each visit's deepest scroll on that page, as a whole percent. |
| The **Scroll** report, `average` | The same average for the pages in scope. |
| The **Scroll** report, `reached` | For each depth 0, 10, and up to 100, the visits whose deepest scroll is at least that depth, and their `share` of all visits that sent a scroll depth. |

Scroll depth is always on. It needs no feature box.

## Breakdown rows

`GET /api/v1/stats/breakdown?property=<name>` returns one row per value. Each row has
`key`, `visitors`, `visits`, `pageviews`, `events`, `bounce_rate`, and `visit_duration`.
What those fields count depends on the kind of property:

| Property | `visitors` | `visits` | `pageviews` | Extra fields |
| --- | --- | --- | --- | --- |
| A visit dimension, such as `source` or `country` | Distinct visitor ids of the visits that started in the period with this value | Visits with this value | Pageviews of those visits | `revenue` and `average_revenue` when a row has revenue |
| `entry_page` | The same, for visits that entered on the page | Visits that entered on the page | Pageviews of those visits | None |
| `exit_page` | The same, for visits that ended on the page | Visits that ended on the page | Pageviews of those visits | `exit_rate` |
| `page` | Distinct visitors with a pageview of the page | Visits that entered on the page | Pageviews of the page | `time_on_page`, `scroll_depth` |
| `event` | Distinct visitors who sent the event | `0` | `0` | `conversion_rate`, `revenue`, `average_revenue` |
| `prop:<key>` and `props` | Distinct visitors with an event that carries the value | `0` | Pageviews that carry the value | `conversion_rate`, `revenue`, `average_revenue` |
| `goal` | Distinct visitors who reached the goal | Visits that match the goal | Pageviews that match the goal | `kind`, `match`, `conversion_rate`, `revenue`, `average_revenue` |

`bounce_rate` and `visit_duration` on a row follow the rules for the headline metrics,
over the row's visits. On a `page` row they describe the visits that entered on that page.

| Field | Definition | Unit |
| --- | --- | --- |
| `exit_rate` | Visits that ended on the page, divided by the page's pageviews in the period. The pageviews ignore any `exit_page` filter. At most 100. `null` when the page has no pageviews in the period. | Percent, 1 decimal |
| `conversion_rate` | The row's `visitors` divided by the visitors of the period. Those visitors follow every filter except `goal`, `event`, and `prop:` filters. | Percent, 1 decimal |
| `revenue` | Net revenue of the row's events, in the site's currency. On a visit dimension, it comes from the events with an amount that carry the value. A payment carries its visit's values, so a renewal counts toward the source of its visit even when that source had no visit in the period. | Site currency, 2 decimals |
| `average_revenue` | `revenue` divided by the row's events with an amount above zero. | Site currency, 2 decimals |

These rules hold for every breakdown:

- A row with no value has the key `(none)`. The dashboard shows it as **Direct / none**
  for `source` and `referrer`, **(not set)** for the UTM dimensions, and **Unknown** for
  the rest.
- Rows sort by `visitors`, then by `pageviews`, then by key.
- Each shard returns its top 500 values. When one shard reached that cap, the response
  has `truncated: true`, and rare values may be missing.
- `limit` takes 1 to 200 rows, and `has_more` says whether another page exists.
- `search` keeps the values that contain the text. The search runs on each shard, so it
  finds values outside the top 500.

## Goals count visitors who reached them

A goal is an event name or a page path. Its row counts the visitors who sent the event or
had a pageview or custom event on a matching page. For a page goal, `events` is the
number of matching pageviews, and `revenue` is `0`. Only event goals carry revenue.
`goal==<name>` as a filter turns into the goal's `event` or `page` filter.

Goal rows read only the events misomoon collected. In a report without filters, the
visitors that `conversion_rate` divides by include imported history, so the rate reads
lower over a period with imported days. [Conversion rate](conversions.md#conversion-rate)
and [Matching rules](conversions.md#matching-rules) have the details.

## Web Vitals

`GET /api/v1/stats/vitals` and **Speed** report five Web Vitals from real visits. They
need the **Web Vitals** (`vitals`) feature
([Choose what to track](tracking.md#choose-what-to-track)).

| Vital | API name | Measures | Unit | Good | Poor |
| --- | --- | --- | --- | --- | --- |
| Largest Contentful Paint | `lcp` | The start time of the largest element painted | ms | 2,500 or less | Over 4,000 |
| Interaction to Next Paint | `inp` | The 98th percentile of the page's interaction durations, counting interactions of 16 ms or more | ms | 200 or less | Over 500 |
| Cumulative Layout Shift | `cls` | The largest burst of layout shifts that come within 1 second of each other, up to 5 seconds long. Shifts right after user input don't count. | Score, 3 decimals | 0.1 or less | Over 0.25 |
| First Contentful Paint | `fcp` | The time of the first paint of text or an image | ms | 1,800 or less | Over 3,000 |
| Time to First Byte | `ttfb` | The navigation's `responseStart` | ms | 800 or less | Over 1,800 |

A value is `good` at or under the good limit, `poor` over the poor limit, and
`needs_improvement` in between. `samples` is the number of values.

The tracker sends one set of values per page load, with the page's first engagement ping.
Route changes in a single-page app send none, and a vital the browser didn't measure is
left out. The Worker keeps times between 0 and 60,000 ms and CLS between 0 and 10.

`p75` is the 75th percentile, read from a histogram that every shard fills:

| Vital | Bin width | Values that share the last bin |
| --- | --- | --- |
| `lcp` | 50 ms | 20,000 ms or more |
| `inp` | 8 ms | 2,000 ms or more |
| `cls` | 0.005 | 10 |
| `fcp` | 50 ms | 20,000 ms or more |
| `ttfb` | 25 ms | 10,000 ms or more |

misomoon adds the bins of every shard, finds the bin where three quarters of the values
are reached, and reports the middle of that bin. `p75` is `null` without samples. The
dashboard rates a tile by its `p75` with the limits above.

## Channels

`classify` in [`packages/core/src/channel.ts`](../packages/core/src/channel.ts) gives each
visit one of 11 channels. It reads the visit's first event: the referrer host, the UTM
tags, and the page URL. The rules run in this order, and the first rule that matches
wins:

| Order | Channel | Rule |
| --- | --- | --- |
| 1 | `AI Assistants` | The referrer is a known AI assistant, or `utm_source` contains `chatgpt`, `openai`, `perplexity`, `claude`, `gemini`, or `copilot`, in any case. |
| 2 | `Email` | `utm_medium` is `email` or `newsletter`, or the referrer is a known webmail host. |
| 3 | `Affiliates` | `utm_medium` is `affiliate`. |
| 4 | `Display` | `utm_medium` is `display`, `banner`, or `interstitial`. |
| 5 | `Paid Search` or `Organic Search` | The referrer is a known search engine, or `utm_medium` contains `search`. It is `Paid Search` when the visit has a paid signal. |
| 6 | `Paid Social` or `Organic Social` | The referrer is a known social site, or `utm_medium` is `social`, `sm`, `socialmedia`, `social-media`, `social_media`, `social media`, or the same forms with `network`. It is `Paid Social` when the visit has a paid signal. |
| 7 | `Video` | The referrer is a known video site, or `utm_medium` is `video`. |
| 8 | `Paid Search` | The visit has a paid signal and no rule above matched. |
| 9 | `Referral` | The visit has a referrer host or a `utm_source`. |
| 10 | `Direct` | Nothing above matched. |

`utm_medium` is compared in lower case. A visit has a paid signal when its page URL has a
`gclid` or `msclkid` parameter, or `utm_medium` is `cpc`, `ppc`, `paidsearch`,
`paid_search`, `cpm`, `cpv`, or `cpa`, or starts with `paid`.

## Sources and referrers

The `referrer` dimension is the host of `document.referrer`, with a leading `www.` and
then a leading `m.` removed. A referrer from the page's own host, compared without `www.`,
is no referrer, so moving between pages of the site is never a referral. A link from
another subdomain of your site is a referral.

The `source` dimension is the first of these that has a value:

1. The name of a known referrer host, from the table below.
2. `utm_source`, tidied. A value equal to the first part of a known host takes that
   source's name, so `google` becomes `Google`. Other values of 3 characters or fewer
   become upper case, and longer values get a capital first letter.
3. The referrer host.
4. `Direct`.

`utm_source` reads the `utm_source` parameter of the landing URL, then `ref`, then
`source`. A known referrer wins over `utm_source`. An unknown referrer loses to it, and
the `referrer` dimension still holds the host.

Hosts without a trailing dot match the host itself and its subdomains. Hosts with a
trailing dot, such as `google.`, match any host that starts with it or contains it after a
dot, such as `google.de` and `google.co.uk`. Exact hosts are checked first, so
`gemini.google.com` is Gemini and `mail.google.com` is Gmail.

| Kind | Source names and hosts |
| --- | --- |
| Search | Google (`google.`), Bing (`bing.com`), DuckDuckGo (`duckduckgo.com`), Yahoo (`search.yahoo.`), Yandex (`yandex.`), Baidu (`baidu.com`), Ecosia (`ecosia.org`), Brave Search (`search.brave.com`), Naver (`naver.com`), Kagi (`kagi.com`) |
| AI assistant | ChatGPT (`chatgpt.com`, `chat.openai.com`), Perplexity (`perplexity.ai`), Claude (`claude.ai`), Gemini (`gemini.google.com`), Copilot (`copilot.microsoft.com`), DeepSeek (`chat.deepseek.com`), You.com (`you.com`), Phind (`phind.com`), Meta AI (`meta.ai`), Grok (`grok.com`) |
| Social | X (`t.co`, `x.com`, `twitter.com`), Facebook (`facebook.com`, `fb.me`), Instagram (`instagram.com`), LinkedIn (`linkedin.com`, `lnkd.in`), Reddit (`reddit.com`), Threads (`threads.net`), Bluesky (`bsky.app`), Hacker News (`news.ycombinator.com`), Pinterest (`pinterest.`), TikTok (`tiktok.com`), Product Hunt (`producthunt.com`), Mastodon (`mastodon.`), Discord (`discord.com`), GitHub (`github.com`) |
| Video | YouTube (`youtube.com`, `youtu.be`), Vimeo (`vimeo.com`), Twitch (`twitch.tv`) |
| Webmail | Gmail (`mail.google.com`), Outlook (`outlook.live.com`), Yahoo Mail (`mail.yahoo.com`) |

misomoon also stores the referrer URL without its query string. No report breaks it down.

## Dimensions

Every breakdown and filter takes one of these 26 dimensions
(`DIMENSIONS` in [`packages/core/src/filters.ts`](../packages/core/src/filters.ts)).
`GET /api/v1/meta/dimensions` returns them with their labels. The label is what the
dashboard's filter bar shows.

Each dimension has a scope. An event dimension is a value of each event. A visit
dimension is stored on the visit and on each of its events. An entry or exit dimension
exists only on the visit. A visit matches an event filter when any of its events match,
and an event matches an entry or exit filter when its visit does.

| API name | Label | Scope | Meaning |
| --- | --- | --- | --- |
| `page` | Page | Event | The page path, without the query string and without a trailing slash, except for `/`. A hash route (`#/pricing` or `#!/pricing`) is part of the path. A path part that looks like an email address becomes `:email`, and a part of 20 or more mixed letters and digits becomes `:token`. Up to 500 characters. |
| `entry_page` | Entry page | Entry or exit | The path of the visit's first event. |
| `exit_page` | Exit page | Entry or exit | The path of the visit's latest pageview. |
| `hostname` | Hostname | Visit | The page's host, without `www.`. Always the site's domain or a subdomain of it. |
| `event` | Event | Event | The event name: `pageview`, `engagement`, a custom name, a built-in event, `Payment`, or `Refund`. The `event` breakdown lists only custom, built-in, and payment events. |
| `source` | Source | Visit | Where the visit came from, by the rules in [Sources and referrers](#sources-and-referrers). |
| `referrer` | Referrer | Visit | The referrer host. |
| `channel` | Channel | Visit | One of the 11 [channels](#channels). |
| `utm_source` | UTM source | Visit | The `utm_source` parameter of the landing URL, else `ref`, else `source`. Up to 200 characters. |
| `utm_medium` | UTM medium | Visit | The `utm_medium` parameter of the landing URL. Up to 200 characters. |
| `utm_campaign` | UTM campaign | Visit | The `utm_campaign` parameter of the landing URL. Up to 200 characters. |
| `utm_term` | UTM term | Visit | The `utm_term` parameter of the landing URL. Up to 200 characters. |
| `utm_content` | UTM content | Visit | The `utm_content` parameter of the landing URL. Up to 200 characters. |
| `country` | Country | Visit | The two-letter ISO 3166-1 country code from Cloudflare. The dashboard shows the country's name. |
| `region` | Region | Visit | The region name from Cloudflare. |
| `city` | City | Visit | The city name from Cloudflare. |
| `continent` | Continent | Visit | The two-letter continent code from Cloudflare. |
| `timezone` | Timezone | Visit | The visitor's IANA time zone from Cloudflare. It is not the site's time zone. |
| `network` | Network | Visit | The name of the organization that runs the visitor's network (the AS organization). |
| `browser` | Browser | Visit | The browser from the user agent: Edge, Opera, Samsung Internet, Yandex, Vivaldi, Brave, DuckDuckGo, Arc, Facebook, Instagram, Line, Firefox, Chrome, Safari, or `Unknown`. For an app that uses the SDK, the app's name. |
| `browser_version` | Browser version | Visit | The browser and its major version, such as `Chrome 141`. |
| `os` | OS | Visit | Windows, iOS, Android, ChromeOS, macOS, Linux, or `Unknown`. |
| `os_version` | OS version | Visit | The operating system and the first two numbers of its version, such as `iOS 17.4` or `macOS 10.15`. Windows NT 10.0 shows as `Windows 10/11`. |
| `device` | Device | Visit | `Desktop`, `Mobile`, or `Tablet`, from the user agent. |
| `screen` | Screen | Visit | The screen width as a class: `Mobile` under 576 pixels, `Tablet` under 992, `Laptop` under 1,440, and `Desktop` from 1,440. |
| `language` | Language | Visit | The first language tag from the SDK's beacon or, for `m.js`, from the request's `Accept-Language` header, such as `en-US`. Up to 16 characters. |

These names work in some places only:

| Name | Where | Meaning |
| --- | --- | --- |
| `prop:<key>` | Breakdowns and filters | The value of one custom property. A key is 1 to 64 letters, digits, `_`, `.`, or `-`. An event keeps up to 30 properties, and a text value keeps its first 300 characters. |
| `goal` | Breakdowns and filters | A breakdown lists every goal. A filter takes goal names and becomes the goal's `event` or `page` filter. One filter can't mix page goals and event goals. |
| `props` | Breakdowns | Every custom property at once, as `key: value` rows. |
| `search_term` | Breakdowns | Google searches that led to the site, read live from Google Search Console. See [Search terms](#search-terms-come-from-google). |

A filter value of `(none)` matches events or visits without a value.
[Filters](api.md#filters) has the operators and limits.

## Other reports

### Live

`GET /api/v1/stats/realtime` and **Live** ignore the period and apply the filters.

| Field | Definition |
| --- | --- |
| `visitors` | Distinct visitors with a pageview or custom event in the last 5 minutes. |
| `pageviews` | Pageviews in the last 5 minutes. |
| `minutes` | For each minute from 30 minutes ago to the current minute, its pageviews and distinct visitors. |
| `pages`, `sources`, `countries` | The top 8 of each in the last 5 minutes, by distinct visitors. |
| `feed` | The latest 40 events of the last 30 minutes, engagement pings left out. |

Each window runs one minute past the current time, so an event from a browser whose clock
runs a little fast still shows.

### Funnels and paths

A funnel step counts the visitors who reached it, and `conversion` is that count as a
percent of the first step's visitors, to 1 decimal. `dropoff` is the previous step's
visitors minus this step's, and never below 0. `entered` counts the distinct visitors with
a pageview or custom event in the period. A visitor id lasts one UTC day, so a visitor's
steps must happen on one UTC day. Paths count pageviews in visit order, with reloads of
the same page folded into one, and each row's `share` is a percent of the visitors who
followed the path. [Funnel modes](conversions.md#funnel-modes) and
[Paths](conversions.md#paths) have the rules.

### Page interactions

`GET /api/v1/stats/behavior` reads the counts that engagement pings carry. Every count on a
ping is the change since the previous ping, so the sums are exact.

| Report | Field | Definition |
| --- | --- | --- |
| `clicks` | `clicks`, `rage`, `dead` | Clicks, rage clicks, and dead clicks, summed per element and page |
| `clicks` | `pageviews`, `visitors` | Pageviews and distinct visitors of the pages in scope, to divide the clicks by |
| `scroll` | `visits`, `average`, `reached` | See [Scroll depth](#scroll-depth-is-the-deepest-point-of-each-visit) |
| `search` | `searches` | Pageviews with a site search term |
| `search` | `visitors`, `total_visitors` | Visitors who searched, and every visitor in scope |
| `errors` | `count`, `last_seen` | Times an error happened, and when it last did |
| `forms` | `starts`, `submissions` | Page views where someone started the form, and submissions |
| `forms` | `conversion` | `submissions` divided by `starts`, as a percent, at most 100 |
| `forms` | `interactions`, `dropoffs` | Per field: page views that focused it, and page views that left the form at it without a submit |
| `media` | `plays`, `reached` | Plays, and the percent of plays that reached 25%, 50%, 75%, and the end (95%) |
| `content` | `impressions`, `clicks`, `ctr` | Times tagged content was seen and clicked, and clicks as a percent of impressions, at most 100 |

Each report's `visitors` counts distinct visitors per row, such as the visitors who hit an
error. [See what people do on a page](tracking.md#see-what-people-do-on-a-page) says what
the tracker collects for each report.

### Search terms come from Google

The `search_term` breakdown asks Google Search Console for the period when you request it,
and caches the answer for ten minutes. Its numbers come from Google, so they cover only
the days Google has processed, usually up to two or three days ago.

| Field | Definition |
| --- | --- |
| `clicks` | Clicks from Google search. The row's `visitors` repeats it. |
| `impressions` | Times the site appeared in Google results for the query |
| `ctr` | Clicks as a percent of impressions, 1 decimal |
| `position` | The average position in the results, 1 decimal. `1` is the top. |

Google can filter only by page and device. `source==Google` and
`channel==Organic Search` change nothing, because every row is Google search traffic. Any
other filter returns `400`.

## Periods follow the site's time zone

Each site has an IANA time zone. An unknown zone name falls back to UTC. misomoon looks up
the zone's offset for each instant, so a day starts at local midnight on both sides of a
daylight saving change (`time.ts` in
[`packages/core/src/time.ts`](../packages/core/src/time.ts)).

| `period` | Window | Default interval |
| --- | --- | --- |
| `realtime` | The last 30 minutes | `minute` |
| `today` | Local midnight until now | `hour` |
| `yesterday` | The local day before today | `hour` |
| `24h` | The last 24 hours | `hour` |
| `7d` | Today and the 6 local days before it | `day` |
| `28d` | Today and the 27 local days before it | `day` |
| `30d` | Today and the 29 local days before it. The default period. | `day` |
| `90d` | Today and the 89 local days before it | `day` |
| `mtd` | The first of this month until now | `day` |
| `lastmonth` | The whole of last month | `day` |
| `ytd` | January 1 until now | `week` |
| `6mo` | This month and the 5 months before it | `month` |
| `12mo` | This month and the 11 months before it | `month` |
| `all` | Local midnight of the site's first visit, or of the day the site was added when that is earlier, until now | By length |
| `custom` | `from` to `to`, both whole local days, at most 400 days | By length |

A period that ends now runs one minute past the current time. A `custom` period ends at
that point too when `to` is today.

The default interval for `all` and `custom` depends on the period's length:

| Length | Interval |
| --- | --- |
| Up to 2 hours | `minute` |
| Up to 3 days | `hour` |
| Up to 120 days | `day` |
| Up to 400 days | `week` |
| Longer | `month` |

`interval` picks another interval. Minute buckets start on UTC minutes. Hour buckets
start on local hours. Day buckets start at local midnight, week buckets on Monday at
local midnight, and month buckets on the first of the month at local midnight. A series
holds at most 1,500 buckets. A longer series returns `400` with the number of buckets and
asks for a coarser interval. Buckets without data come back as zeros.

## Imported history joins unfiltered reports

History imported from Google or from CSV files lands in each shard's `imported` table as
daily totals per dimension and value
([`packages/core/src/imported.ts`](../packages/core/src/imported.ts)). misomoon adds it to
a report only when the report has no filters. `imported=0` leaves it out. [Bring your
history](import.md) shows how to import.

| Report | Uses imported history |
| --- | --- |
| Headline metrics and the time series | Yes. A day lands in the bucket of its local midnight, so minute and hour charts show it at midnight. |
| Breakdowns of the dimensions in the next table | Yes |
| Goal rows | No. The visitors that `conversion_rate` divides by include imported visitors. |
| Revenue, Web Vitals, live, funnels, paths, page interactions, and other dimensions | No |

Imported visitors are each day's unique visitors, so adding days matches how misomoon
counts its own visitors.

| Dimension | From a CSV export | From Google |
| --- | --- | --- |
| `channel` | Derived from the source and UTM tags by the [channel rules](#channels) | Google's channel group, with Organic Video and Paid Video as `Video`, Organic Shopping as `Referral`, and Paid Shopping as `Paid Search`. Other groups go through the channel rules. |
| `source` | Yes | Yes |
| `referrer` | When the row has a referrer | When the source contains a dot |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | When set | `utm_source` is the session source, `utm_medium` the medium, `utm_campaign` the campaign, `utm_content` the ad content, and `utm_term` the ad keyword |
| `page` | With time on page and scroll depth | With time on page, no scroll depth |
| `entry_page` | Yes | Yes |
| `exit_page` | Yes | No |
| `country`, `region` | Yes | Yes |
| `city` | No | Yes |
| `browser` | Yes | Yes |
| `browser_version` | Yes | No |
| `os`, `os_version` | Yes | Yes |
| `device` | Yes | Yes |
| `event` | Yes | Yes, without Google's own `page_view`, `session_start`, `first_visit`, `user_engagement`, and `scroll` |

Google reports name metrics differently. misomoon reads them this way:

| misomoon | From Google |
| --- | --- |
| Visitors | Total users |
| Visits | Sessions |
| Pageviews | Views |
| Bounces | Sessions minus engaged sessions |
| Visit duration | User engagement duration |
| Time on page | User engagement duration of the page, divided by its sessions |
| Events | Event count |

## What misomoon drops

These events never reach a report:

| What | Rule | Where |
| --- | --- | --- |
| Your own visits | A `misomoon_ignore` key in the browser's local storage stops `m.js` from sending anything. [Exclude yourself](tracking.md#exclude-yourself) shows how to set it. | `m.js` |
| Automated browsers | `m.js` sends nothing when `navigator.webdriver` is true. | `m.js` |
| The overlay tab | A page opened with `#misomoon-overlay` sends nothing. | `m.js` |
| Verified bots | Cloudflare marks the request as a verified bot. | Worker |
| Low bot scores | Cloudflare's bot score is below 10, when the request has one. | Worker |
| Bot user agents | The user agent is missing, shorter than 20 characters, or matches `BOT_UA` in [`packages/core/src/ua.ts`](../packages/core/src/ua.ts). The pattern covers, among others, search and AI crawlers, link previews, headless and automated browsers, page speed tools, uptime monitors, and HTTP libraries. | Worker |
| Bad beacons | The body is over 16 KB or isn't JSON. The site id or the URL is missing. The URL isn't `http` or `https`. The event name is empty, over 120 characters, or holds a control character, `;`, or `|`. | Worker |
| Foreign pages | The site doesn't exist, or the page's host isn't the site's domain or a subdomain of it. | Worker |
| Excluded paths | A pageview or engagement ping on a page that the site's path rules leave out. Custom events on that page still count. [Choose what to track](tracking.md#choose-what-to-track) explains the rules. | Worker |
| Events past the daily cap | Events after the site's cap for the UTC day. [Daily ingest cap](configuration.md#daily-ingest-cap) explains the cap. | Worker and queue consumer |
| Late engagement pings | An engagement ping that comes more than 30 minutes after its visit's last activity. | Queue consumer |
| Repeats | An event whose `id` is already stored. | Queue consumer |

An event whose client timestamp is more than 5 minutes from the server's clock keeps the
event and takes the server's time instead.
[Why are my numbers lower than in Google Analytics?](faq.md#why-are-my-numbers-lower-than-in-google-analytics)
lists other reasons why counts differ between tools.

---

# Configuration reference

The API Worker (`apps/api`) reads all of its settings from `apps/api/wrangler.jsonc`
and from Worker secrets. This page lists every binding, variable, and secret it reads.
To change a variable, edit `vars` in `wrangler.jsonc` and deploy again. To set a secret,
run `wrangler secret put <NAME>` in `apps/api`. Locally, put secrets in
`apps/api/.dev.vars`, which git ignores.

## Bindings

| Binding | Type | Required | What it holds |
| --- | --- | --- | --- |
| `CONTROL` | D1 database | Yes | Accounts, sites, goals, API keys, daily salts, the shard registry, and the routing table (`migrations/control`). |
| `SHARD_0` ... `SHARD_n` | D1 database | At least one | Events, visits, and imported history (`migrations/shard`). A migrated `SHARD_*` binding registers itself on the next request. |
| `EVENTS` | Queue producer and consumer | No | Buffers beacons so the response is `202` at once. The consumer writes them in batches of up to 100. Without a queue, the Worker writes each event in `ctx.waitUntil`. |
| `ASSETS` | Static assets | Yes | The built dashboard (`apps/dashboard/dist`), served by the same Worker. |
| `STATS_LIMIT` | Rate limit | No | 100 requests per minute. It counts `/api/v1/stats/*` calls per API key, or per IP address for signed-out callers. Signed-in dashboards and shared links aren't counted. It also counts sign-up, sign-in, password reset, invitation accept, and shared-link password attempts per IP address. |
| `EMAIL` | Send email | No | Cloudflare Email Service. Sends invitations, password resets, reports, alerts, and the daily-cap notice from `EMAIL_FROM`, which must be on a domain onboarded to Email Service. Sending to any address needs the Workers Paid plan. The deploy bundle leaves it out. |
| `BROWSER` | Browser Run | No | Prints the PDF attached to weekly and monthly reports, and the PDF preview (`/reports/preview?format=pdf`). Each edition is printed once per site, whoever subscribes; a print takes a few seconds of browser time. Workers Free includes 10 minutes of browser time a day, Workers Paid 10 hours a month, then $0.09 an hour ([pricing](https://developers.cloudflare.com/browser-run/pricing/), checked 2026-10-24). Without it, or when a print fails, reports go out without the PDF. `wrangler dev` cannot print: quick actions run on Cloudflare only. The deploy bundle keeps it. |

The consumer retries a batch 5 times, then moves it to the dead-letter queue
`misomoon-events-dlq`. The cron trigger (`*/5 * * * *`) checks traffic-spike alerts and
moves data off retiring shards every 5 minutes. At minute 15 of every hour, it also
sends email reports, checks traffic-drop alerts, applies retention, and deletes old salts
and usage rows older than 400 days.

## Variables

Set these in `vars` in `apps/api/wrangler.jsonc`.

| Variable | Default | What it does |
| --- | --- | --- |
| `PUBLIC_URL` | unset | The public origin of your dashboard, for example `https://analytics.example.com`. Links in emails use it. Invitations and password resets fall back to the address of the request. Email reports are sent by the cron job, which has no request, so they fall back to `https://misomoon.com`. Set it if you send reports. |
| `SIGNUPS` | `open` | `invite` turns off open sign-up after the first account. While no account exists, one person can sign up and own the instance. After that, new people join only through an invitation from a team owner or admin. `closed` turns off sign-up completely, including the first account. Invitations still work. The deploy bundle sets `invite`. |
| `DEMO_SITE` | `demo` | The id of a public site that the dashboard opens first for people who can see it, such as signed-out visitors. The deploy bundle sets it empty, so the dashboard opens your first site. |
| `RETENTION_DAYS` | `0` | Deletes events and visits older than this many days, on every site. `0` keeps everything. A site's own **Keep stats for** setting applies when it is shorter ([privacy settings](compliance.md#privacy-settings)). |
| `SHARD_SOFT_LIMIT_MB` | `8000` | The size at which a shard stops taking new sites and starts draining. D1's hard limit is 10 GB per database. |
| `INGEST_DAILY_CAP` | unset | The most events a site can store per UTC day, unless the site has its own cap. Unset means no cap. A value that is not a positive whole number also means no cap. See [Daily ingest cap](#daily-ingest-cap). |
| `EMAIL_PROVIDER` | unset | `cloudflare` or `ses`. Unset picks the `EMAIL` binding when it is bound, then SES. A provider named here that is not set up sends nothing; email does not go out through another provider. |
| `EMAIL_FROM` | `misomoon <reports@misomoon.com>` | The sender of every email. Use an address on a domain that your provider verified. |
| `AWS_SES_REGION` | unset | Amazon SES: the region of your SES identity, for example `us-east-1`. Email goes through SES when this and both `AWS_SES_*` secrets are set. |
| `DEMO_SEED` | unset | `1` allows `POST /api/v1/sites/:id/demo`, which writes synthetic traffic. Use it only locally. |
| `CF_ZONE_ID` | unset | Managed proxy: the zone that owns `PROXY_CNAME_TARGET` and has Cloudflare for SaaS turned on. |
| `PROXY_CNAME_TARGET` | unset | Managed proxy: the fallback origin that customer hostnames point a CNAME at, for example `proxy.example.com`. |

## Secrets

| Secret | Needed for | Notes |
| --- | --- | --- |
| `AWS_SES_ACCESS_KEY_ID`, `AWS_SES_SECRET_ACCESS_KEY` | Email through Amazon SES | An IAM key that may call `ses:SendEmail`. Requests use SES v2 with SigV4 signing. |
| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | Google import and Search Console | An OAuth web client. Add `<your misomoon URL>/api/v1/google/callback` as an authorized redirect URI, using the address you open the dashboard on: misomoon builds the redirect from the request's own origin, not from `PUBLIC_URL`. In the Google Cloud project, enable the Google Analytics Data API, the Google Analytics Admin API, and the Google Search Console API. The import asks for `analytics.readonly`, Search Console for `webmasters.readonly`. [Bring your history](import.md) walks through the setup. |
| `CF_API_TOKEN` | Managed proxy | A Cloudflare API token with **SSL and Certificates: Edit** on `CF_ZONE_ID`. |

Without an email provider, the dashboard shows invitation links to copy by hand, and
reports, alerts, password resets, and the daily-cap notice are not sent.

The managed proxy is on only when `CF_API_TOKEN`, `CF_ZONE_ID`, and `PROXY_CNAME_TARGET`
are all set. [Serve the tracker from your own domain](PROXY.md) explains the proxy and its other options.

## Daily ingest cap

The cap limits how many events one site stores per UTC day, so a bot flood or a broken
script can't run up D1 writes. It counts every stored row. A pageview, a custom event, and
an engagement ping each count as one. The queue consumer applies the cap before it writes
to a shard, and keeps the earliest events of the day. Several consumers can run at once.
Each adds the room it takes to the day's count in `CONTROL` in one statement, so together
they never store more than the cap, and it gives back the room it didn't use once its write
is done. If a consumer fails before it can give the room back, the day stores a little less
than the cap, never more. A queue retry never counts an event twice or drops one that was
already stored. Once a day is full, the edge also drops beacons for that site within a
minute, before they reach the queue. A ref-only beacon is an engagement ping that carries
only payment refs. The edge drops it for a site that takes no payments. For a site that
takes payments, it counts as one stored row, not as an event, and a queue retry doesn't
count it twice. It takes room under the cap like any other row, but once queued it is never
dropped, so the payment keeps its visit. Those beacons are the one way a day can store more
than its cap: one row each, for those queued before the edge saw the day full.
Payments from webhooks are never capped. The day starts over at 00:00 UTC.

Each site has an `ingest_cap` column in the `sites` table of `CONTROL`:

| `ingest_cap` | Effect |
| --- | --- |
| `NULL` | The site uses `INGEST_DAILY_CAP`. |
| A positive number | The site may store this many events per UTC day. |
| `0` | The site is blocked. Every beacon is dropped. |

To give one site its own cap, run:

```sh
wrangler d1 execute CONTROL --remote --command "UPDATE sites SET ingest_cap = 500000 WHERE id = 'shop-com'"
```

Workers pick up the change within a minute. The first time a cap drops an event on a
given day, the team's owners and admins get one email. A block sends no email.
`GET /api/v1/sites/:id/usage` returns the cap and the counts for the last 31 days. The
`dropped` count includes only events that the consumer dropped. Beacons that the edge
dropped are not counted, because counting them would cost a write each.

## Tracker attributes

The tracker reads these attributes from its own `<script>` tag. The
[tracking guide](tracking.md) shows them in use.

| Attribute | Example | What it does |
| --- | --- | --- |
| `?s=` on the script URL | `src=".../m.js?s=shop"` | The site id. Required. The server also uses it to add the code for the site's ticked features. |
| `data-api` | `data-api="/relay/api/event"` | Where to send events. Defaults to `api/event` next to the script URL. |
| `data-disable` | `data-disable="forms,clicks"` | Turns features ticked in the site settings off on the pages that carry it. Values: `outbound`, `downloads`, `forms`, `events`, `payments`, `vitals`, `clicks`, `errors`, `fields`, `media`, `content`. |
| `data-manual` | `data-manual` | Sends no pageview on load. Call `misomoon('pageview')` yourself. |
| `data-hash` | `data-hash` | Counts `#/route` changes as pages, for hash-based routers. |
| `data-prop-<name>` | `data-prop-plan="pro"` | Adds a custom property to every event. |
| `data-download-ext` | `data-download-ext="dmg,apk"` | More file extensions to count as downloads, with Downloads ticked. |

Which paths count, the search parameters, and what the tracker collects are site settings,
not attributes: see [Choose what to track](tracking.md#choose-what-to-track). A browser
the tracker doesn't count says why in its console.

Attributes on a page's own elements (`data-misomoon-content`, `data-misomoon-media`,
`data-misomoon-id`, `data-misomoon-mask`) are in the
[tracking guide](tracking.md#see-what-people-do-on-a-page).

---

# API reference

The API Worker serves every endpoint on this page from the same origin as the dashboard.
The examples use `https://analytics.example.com`. The MCP server has its own page,
[Ask AI tools about your traffic](mcp.md).

## Authentication

Send a bearer token in the `Authorization` header:

```sh
curl -H "Authorization: Bearer mm_..." "https://analytics.example.com/api/v1/stats/aggregate?site=shop&period=7d"
```

| Prefix | What it is | How you get it |
| --- | --- | --- |
| `mm_` | API key | **Settings** > **Integrations** in the dashboard, for one site, or `POST /api/v1/keys`, for one site or all of them. A key acts with its owner's role. |
| `ms_` | Browser session | `POST /api/v1/auth/login`. The dashboard stores it. It lasts 30 days. |
| `sh_` | Shared link | `POST /api/v1/share/:slug`. Read-only, one site, with the link's segment applied to every query. |

The API reads tokens from the header only. A token in the query string is ignored, so a
key never lands in logs or browser history. Requests without a token can read public
sites, such as the demo.

### Who may call a route

The **Role** column in the tables below names the least access a route needs.

| Role | Who has it |
| --- | --- |
| Public | Anyone. No token is needed. |
| Any | Any token, or none. The answer depends on who asks. |
| Viewer | The `read` permission on the site: a team owner, admin, editor, or viewer, or a guest editor or viewer of that site. A route that needs Viewer also answers for a public site without a token, and for a shared link's site with its `sh_` token, unless the row says otherwise. |
| Editor | The `edit` permission: a team owner, admin, or editor, or a guest editor of the site. |
| Admin | The `manage` permission: a team owner or admin. |
| Owner | The `own` permission: a team owner. |
| Session | A signed-in user with an `ms_` token. An API key gets `403` with `API keys cannot do this; sign in to the dashboard`, and a request without a token gets `401`. |

A team role covers every site of the team. A guest role covers one site. The billing role
has no site permissions, so a billing member reads no stats. An API key has its owner's
role, and a key limited to one site has no role on any other site.

## Errors

Every error is JSON with one field:

```json
{ "error": "unknown property: pagee" }
```

| Status | Meaning |
| --- | --- |
| `400` | The request is invalid: an unknown period, dimension, or filter, a custom range over 400 days, a missing or malformed field, or a body that is not valid JSON. |
| `401` | No token, a token that expired, an unknown API key, or a wrong password. |
| `403` | Your role on the site or team does not allow this action, or the route needs a browser session and got an API key. |
| `404` | The site or the resource does not exist. Unknown `/api/*` paths also return `404`. |
| `405` | `GET /mcp`. The MCP server takes `POST` only. |
| `409` | A conflict: a domain or site id that is already registered, a goal name that already exists, an email that already has an account or is already on the team, a team that still has sites, a change that would leave a team without an owner, an import while the site's history moves between shards, or search terms for a site without Search Console. |
| `413` | The body is over the limit: 256 KB for a payment webhook, 64 KB for `/mcp`. `POST /api/event` drops a body over 16 KB and still answers `202`. |
| `429` | Over a rate limit. Try again after a minute. |
| `500` | An unexpected error. The body is `{"error": "internal error"}`. |
| `501` | The server lacks what the feature needs: the managed proxy without `CF_API_TOKEN`, `CF_ZONE_ID`, and `PROXY_CNAME_TARGET`, Google import and Search Console without `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, or a PDF report preview without the `BROWSER` binding. |
| `502` | Google or the Cloudflare API returned an error. The message carries theirs. |
| `503` | Email could not go out, because no email provider is set up or the provider refused the message. A PDF preview that Browser Run could not print also returns `503`. |

`/mcp` answers JSON-RPC requests with JSON-RPC errors ([Ask AI tools about your traffic](mcp.md)). A payment
webhook answers `{"error": ...}` with its own statuses, listed in
[Payment webhooks](#payment-webhooks).

## Rate limits

`/api/v1/stats/*` and `/api/v2/query` allow 100 requests per minute per API key, or per
IP address for requests without a key (`STATS_LIMIT`). Signed-in dashboards and shared
links are not limited.

`POST /api/v1/share/:slug`, `POST /api/v1/auth/signup`, `POST /api/v1/auth/login`,
`POST /api/v1/auth/forgot`, `POST /api/v1/auth/reset`, and
`POST /api/v1/invitations/:token/accept` use the same limit per IP address, counted
separately for each route. Over it, they return `429` with `too many attempts, wait a minute`.

## Query parameters

All `GET /api/v1/stats/*` endpoints accept these parameters.

| Parameter | Values | Default |
| --- | --- | --- |
| `site` | A site id. `site_id` is accepted as an alias. | Required |
| `period` | `realtime`, `today`, `yesterday`, `24h`, `7d`, `28d`, `30d`, `90d`, `mtd`, `lastmonth`, `ytd`, `6mo`, `12mo`, `all`, `custom` | `30d` |
| `from`, `to` | `YYYY-MM-DD` in the site's time zone. Required with `period=custom`. Both days are included. At most 400 days. | |
| `filters` | See [Filters](#filters) | None |
| `compare` | `previous` (the period of the same length before), `year` (the same dates a year earlier), `true` or `1` (the same as `previous`), or `0`. Any other value compares nothing. | `0` |
| `interval` | `minute`, `hour`, `day`, `week`, `month` | Picked from the period |
| `imported` | `0` leaves imported history out | Imported history is included in unfiltered reports |

Days, weeks, and months follow the site's time zone, including daylight saving changes.

## Filters

A filter string holds up to 8 filters separated by `;`. Each filter is a dimension, an
operator, and up to 6 values separated by `|`. A query holds at most 16 values in total.

```text
country==US|CA;page~/blog;browser!=Safari
```

| Operator | Matches |
| --- | --- |
| `==` | The value is one of the values |
| `!=` | The value is none of the values. Rows with no value match too, unless `(none)` is one of the values. |
| `~` | The value contains one of the values |
| `!~` | The value contains none of the values |

In `==` and `!=`, `*` is a wildcard: `page==/blog/*`. The value `(none)` matches rows
with no value, for example `referrer==(none)`.

Dimensions: `page`, `entry_page`, `exit_page`, `hostname`, `event`, `goal`, `source`,
`referrer`, `channel`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`,
`utm_content`, `country`, `region`, `city`, `continent`, `timezone`, `network`,
`browser`, `browser_version`, `os`, `os_version`, `device`, `screen`, `language`, and
`prop:<name>` for a custom property. A property name is 1 to 64 letters, digits, `_`,
`.`, or `-`. `GET /api/v1/meta/dimensions` returns the full list as `key` and `label`
pairs, without `goal`. It is Public.

`goal==Signup` filters by the saved goal named `Signup`: its page or its event. One goal
filter can't mix page goals and event goals.

`channel` takes one of `Direct`, `Organic Search`, `Paid Search`, `AI Assistants`,
`Organic Social`, `Paid Social`, `Email`, `Video`, `Affiliates`, `Display`, and
`Referral`.

## Stats endpoints

Every stats endpoint needs Viewer on the site.

### GET /api/v1/stats/aggregate

The headline metrics for the period.

```json
{
  "current": { "visitors": 3361, "visits": 4286, "pageviews": 9332, "views_per_visit": 2.18, "bounce_rate": 48.9, "visit_duration": 96, "events": 1830, "revenue": 5192, "average_revenue": 40.9 },
  "previous": { "visitors": 2453, "...": "..." },
  "change": { "visitors": 37.2, "bounce_rate": 2.2, "...": "..." }
}
```

`visitors` counts unique visitors per day. `bounce_rate` is a percentage of visits.
`visit_duration` is in seconds, from the first to the last pageview or custom event of a
visit. `change` is the percent change of each metric, except `bounce_rate`, which
changes in percentage points. `previous` and `change` are `null` without `compare`. The
response also has `site` and `window` (`from` and `to` in milliseconds).

### GET /api/v1/stats/timeseries

All headline metrics per time bucket. Returns `interval`, `window` (`from` and `to` in
milliseconds), `points`, and `previous` (`null` without `compare`). Each point has `t`,
the bucket start in milliseconds, and the same fields as `current` above. Empty buckets
are returned as zeros.

### GET /api/v1/stats/breakdown

The top values of one dimension. Extra parameters:

| Parameter | Values | Default |
| --- | --- | --- |
| `property` | A dimension, `goal` (conversions per goal), `props` (every custom property as `key: value` rows), or `search_term` (Google Search Console) | `page` |
| `limit` | 1 to 200. Up to 1000 for `search_term`. | `10` |
| `page` | 1 and up | `1` |
| `search` | Only values that contain this text | None |

Returns `property`, `rows`, `total_visitors`, and `has_more`. Each row has `key`,
`visitors`, `visits`, `pageviews`, `events`, `bounce_rate`, and `visit_duration`. Rows of
`page` also have `time_on_page` (seconds) and `scroll_depth` (percent). Rows of
`exit_page` also have `exit_rate`. Rows of `event`, `goal`, `props`, and `prop:<name>`
also have `conversion_rate`, `revenue`, and `average_revenue`. Goal rows also have `kind`
and `match`. Rows of visit dimensions, such as `source`, have `revenue` and
`average_revenue` when the visits had revenue.

`search_term` rows have `key`, `clicks`, `impressions`, `ctr` (percent), `position` (the
average position, 1 is the top), and `visitors`, which holds the clicks. They come from
Google, live, and stay cached for ten minutes. For a site without
[Search Console](#google-search-console), `search_term` returns `409`.

A response with `truncated: true` came from a shard that had more rows than its cap of
500, so the rarest rows may be missing.

### GET /api/v1/stats/realtime

Visitors in the last 5 minutes, pageviews per minute for the last 30 minutes, the top
pages, sources, and countries right now, and a feed of recent events. It ignores `period`.

### GET /api/v1/stats/vitals

For each Core Web Vital (`lcp`, `inp`, `cls`, `fcp`, `ttfb`): the 75th percentile, the
number of samples, and the counts rated good, needs improvement, and poor. LCP, INP, FCP,
and TTFB are in milliseconds.

### POST /api/v1/stats/funnel

Runs a funnel over the period. The body takes the query parameters as JSON fields (`site`,
not `site_id`), plus `steps` (2 to 8) and `mode`:

```json
{
  "site": "shop",
  "period": "30d",
  "mode": "sequential",
  "steps": [
    { "kind": "page", "match": "/" },
    { "kind": "page", "match": "/pricing" },
    { "kind": "event", "match": "Signup", "label": "Signed up" }
  ]
}
```

Each step has `kind` (`page` or `event`), `match` (a path or an event name, cut to 200
characters), and an optional `label` (cut to 80). In place of `steps`, `funnel` takes the
id of a [saved funnel](#funnels) and runs its steps and mode. A `mode` in the body
overrides the saved one.

| Mode | A visitor completes a step when |
| --- | --- |
| `sequential` | The steps happen in order. Other pages and events may come between them. |
| `strict` | The steps happen in order with nothing between them. |
| `flexible` | The middle steps happen in order. The last step counts anyone who reached it after the first. |

A missing or unknown `mode` is `sequential`. Returns `mode`, `entered`, `completed`, and
`steps`. Each step has `label`, `visitors`, `conversion` (percent of the first step), and
`dropoff`.

### GET /api/v1/stats/journeys

The next or previous page after a path. Extra parameters: `path` (comma-separated pages,
for example `/,/pricing`), `direction` (`forward` or `backward`), and `limit` (1 to 50,
default 12). Rows include `(exit)` and `(entrance)` for the ends of a visit. Reloads of the
same page count once.

### GET /api/v1/stats/behavior

What people did on pages, from the engagement beacon
([tracking guide](tracking.md#see-what-people-do-on-a-page)). Extra parameters: `report`
(required), `page` (one path without `;` or `|`, which replaces any page filter), and
`limit` (default 50, at most 500 rows).

| `report` | Returns |
| --- | --- |
| `clicks` | `pageviews`, `visitors`, `clicks`, `rage`, `dead`, and `elements`: `page`, `selector`, `label`, `clicks`, `visitors`, `rage`, `dead` |
| `scroll` | `visits`, `average` (percent), and `reached`: for each depth 0, 10 … 100, the `visits` that scrolled at least that far and their `share` |
| `search` | `searches`, `visitors`, `total_visitors`, and `terms`: `term`, `searches`, `visitors` |
| `errors` | `count`, `visitors`, and `errors`: `message`, `source`, `count`, `visitors`, `last_seen`, up to 5 `pages` and `browsers` |
| `forms` | `forms`: `form`, `starts`, `submissions`, `conversion`, `visitors`, and `fields` in page order: `field`, `interactions`, `dropoffs`, `position` |
| `media` | `media`: `name`, `type`, `plays`, `visitors`, and `reached`, the percent of plays that got to 25, 50, 75% and the end |
| `content` | `content`: `name`, `impressions`, `clicks`, `ctr`, `visitors` |

```sh
curl -H "Authorization: Bearer $KEY" \
  "https://app.misomoon.com/api/v1/stats/behavior?site=shop&period=30d&report=clicks&page=/pricing"
```

A response with `truncated: true` came from a shard that had more rows than the cap, so
the rarest rows may be missing.

### GET /api/v1/stats/export

A ZIP file with one CSV file per report for the period and filters. The file is named
`misomoon_<site>_<from>_<to>.zip`, with the first and last day of the period.

| File | Columns |
| --- | --- |
| `visitors.csv` | `date`, `visitors`, `visits`, `pageviews`, `views_per_visit`, `bounce_rate`, `visit_duration`, `events`, `revenue`. One row per day, week, or month, from `interval`. `minute` and `hour` give days. |
| `pages.csv` | `name`, `visitors`, `pageviews`, `bounce_rate`, `time_on_page`, `scroll_depth` |
| `entry_pages.csv` | `name`, `visitors`, `visits`, `bounce_rate`, `visit_duration` |
| `exit_pages.csv` | `name`, `visitors`, `visits`, `exit_rate` |
| `custom_events.csv` | `name`, `visitors`, `events`, `conversion_rate`, `revenue`, `average_revenue` |
| `conversions.csv` | `name`, `visitors`, `events`, `conversion_rate`, `revenue`, `average_revenue`, one row per goal. It holds the top 10 goals by visitors, or `limit` goals when the request sets `limit` (at most 200). |
| `channels.csv`, `sources.csv`, `referrers.csv`, `utm_sources.csv`, `utm_mediums.csv`, `utm_campaigns.csv`, `utm_contents.csv`, `utm_terms.csv`, `countries.csv`, `regions.csv`, `cities.csv`, `browsers.csv`, `browser_versions.csv`, `operating_systems.csv`, `operating_system_versions.csv`, `devices.csv`, `screens.csv`, `languages.csv` | `name`, `visitors`, `visits`, `pageviews`, `bounce_rate`, `visit_duration` |

Each breakdown file holds at most 1000 rows.

## Stats API v2

`POST /api/v2/query` takes one JSON query and returns rows. It supports no dimension, one
time dimension, or one property dimension. It needs Viewer on the site.

```json
{
  "site_id": "shop",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "7d",
  "dimensions": ["visit:source"],
  "filters": [["is", "visit:country", ["US", "CA"]]],
  "order_by": [["visitors", "desc"]],
  "pagination": { "limit": 20, "offset": 0 }
}
```

| Field | Values |
| --- | --- |
| `site_id` | Required. A site id or the site's domain. |
| `metrics` | Required. Any field of the [aggregate](#get-apiv1statsaggregate), timeseries, or breakdown rows, such as `visitors`, `visits`, `pageviews`, `views_per_visit`, `bounce_rate`, `visit_duration`, `events`, `revenue`, `conversion_rate`, or `time_on_page`. `total_revenue` reads `revenue`, and `percentage` and `group_conversion_rate` read `conversion_rate`. A metric the rows lack returns `null`. |
| `date_range` | Required. One of `day` (today), `24h`, `7d`, `28d`, `30d`, `91d` (the `90d` period), `month` (month to date), `6mo`, `12mo`, `year` (year to date), and `all`, or a pair of days such as `["2026-01-01", "2026-01-31"]`. Any other name returns `400`. |
| `dimensions` | At most one. `time`, or `time:minute`, `time:hour`, `time:day`, `time:week`, or `time:month`, for one row per bucket. Or one property dimension from the list below. |
| `filters` | A list of `[operator, dimension, values]`. `["and", [filter, ...]]` groups filters. Every filter applies. |
| `order_by` | A list of `[metric or dimension, "asc" or "desc"]`. The first pair sorts first. |
| `include` | `imports: false` leaves imported history out. `total_rows: true` adds `meta.total_rows`. `time_labels: true` adds `meta.time_labels` for a time dimension. |
| `pagination` | `limit` (1 to 10000, default 10000) and `offset` (default 0). |

Property dimensions: `event:page`, `event:hostname`, `event:name`, `event:goal`,
`visit:entry_page`, `visit:exit_page`, `visit:source`, `visit:referrer`,
`visit:channel`, `visit:utm_source`, `visit:utm_medium`, `visit:utm_campaign`,
`visit:utm_content`, `visit:utm_term`, `visit:device`, `visit:browser`,
`visit:browser_version`, `visit:os`, `visit:os_version`, `visit:country`,
`visit:region`, `visit:city`, `visit:screen`, and `event:props:<name>`.
`visit:country_name`, `visit:region_name`, and `visit:city_name` return the same values
as `visit:country`, `visit:region`, and `visit:city`. A property dimension returns at most
the top 200 values by visitors.

Filter operators are `is`, `is_not`, `contains`, `contains_not`, `matches_wildcard`, and
`matches_wildcard_not`. Filters take the same dimensions. `matches_wildcard` is `is` with
`*` as a wildcard, as in [Filters](#filters).

The response is `{"results": [{"dimensions": [...], "metrics": [...]}], "meta": {...}, "query": {...}}`.
`metrics` follow the order of the query's `metrics`. A time dimension's label is the
bucket start in UTC, as `YYYY-MM-DD HH:MM:SS` for `time:minute` and `time:hour` and as
`YYYY-MM-DD` otherwise.

## Sites

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites` | Any | Lists the sites you can read, each with your `role` on it. Without a token, the public sites with `role` set to `null`. With a shared link, its one site, also with `role` set to `null`. |
| `POST /api/v1/sites` | Session | Adds a site. See [Add a site](#add-a-site). Returns `201` and the site. |
| `GET /api/v1/sites/:id` | Viewer | One site. |
| `PATCH /api/v1/sites/:id` | Editor | Changes `name`, `timezone`, `currency`, `public`, `features`, `search_params`, `include_paths`, `exclude_paths`, `exclude_ips`, `privacy_signals`, or `retention_days`. `features` is the list of what the tracker collects beyond pageviews: any of `outbound`, `downloads`, `forms`, `events`, `payments`, `vitals`, `clicks`, `errors`, `fields`, `media`, `content`, `search` ([Choose what to track](tracking.md#choose-what-to-track)). `search_params` lists up to 10 URL parameters that hold the site search term. An empty list restores `q`, `s`, `search`, `query`, `keyword`. `include_paths` and `exclude_paths` take up to 20 paths each, starting with `/`, where `*` matches within one part of the path and `**` across. An empty list removes them. `exclude_ips` takes up to 50 IPv4 or IPv6 addresses or CIDR ranges, such as `203.0.113.7` or `2001:db8::/32`, whose visits never count; an empty list or `null` removes them. `privacy_signals` is `true` to drop visits from browsers that send Global Privacy Control or Do Not Track. `retention_days` is a whole number of days from 30 to 3650 after which the site's events and visits are deleted, or `null` to keep them as long as the server's `RETENTION_DAYS` does ([Privacy settings](compliance.md#privacy-settings)). The site object carries the lists as comma-separated strings, `null` for the defaults. Returns the site. |
| `DELETE /api/v1/sites/:id` | Admin | Deletes the site and all of its data on every shard, and its managed proxy hostname. Returns `204`. |
| `GET /api/v1/sites/:id/usage` | Viewer | The site's daily ingest cap and what it stored per UTC day over the last 31 days: `{"cap": 500000, "blocked": false, "days": [{"day": "2026-10-23", "events": 812, "stored": 1544, "dropped": 0, "capped": false}]}`. `cap` is `null` without a cap. `events` counts pageviews and custom events, and `stored` counts every row, engagement pings too. A public dashboard or a shared link doesn't open it. |
| `POST /api/v1/sites/:id/demo` | Admin | Writes synthetic traffic through the real write path, for local development. Off unless `DEMO_SEED=1`, and `403` otherwise. The optional body takes `days` (default 35, at most 120), `perDay` (default 140, at most 2000), and `seed` (default 7). Returns `{"site": ..., "events": <rows written>}`. |

A site object has `id`, `domain`, `name`, `timezone`, `currency`, `team_id`, `public`
(`0` or `1`), `ingest_cap`, `features`, `search_params`, `include_paths`,
`exclude_paths`, `exclude_ips`, `privacy_signals` (`0` or `1`), `retention_days`, and
`created_at` in milliseconds.

### Add a site

`POST /api/v1/sites` takes:

| Field | Meaning |
| --- | --- |
| `domain` | Required. The server lowercases it and strips `http://`, `https://`, `www.`, and any path. A port, such as `localhost:5173`, stays. |
| `id` | 2 to 40 characters of `a-z`, `0-9`, and `-`. Without it, the id comes from the domain: each run of other characters becomes `-`, for example `shop-example-com`. |
| `name` | At most 80 characters. Defaults to the domain. |
| `timezone` | An IANA name. Defaults to `UTC`. |
| `currency` | An ISO 4217 code. Defaults to `USD`. |
| `public` | `true` lets anyone read the stats without a token. |
| `team` | The team that owns the site. You need to be its owner, admin, or editor, or the request returns `403`. |

Without `team`, the site goes to the first team you joined as owner, admin, or editor. If
you have none, the server makes a team named `My sites` with you as owner. API keys can't
add sites. A domain or id that is already taken returns `409`.

### Goals

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/goals` | Viewer | Lists the goals: `id`, `site_id`, `name`, `kind`, `match`. |
| `POST /api/v1/sites/:id/goals` | Editor | Adds a goal. Returns `201` and the goal. |
| `DELETE /api/v1/sites/:id/goals/:goal` | Editor | Deletes a goal. Returns `204`. |

The body takes `kind` (`event` or `page`, required), `match` (required: the event name,
or the page path, where `*` is a wildcard), and `name`. `match` is cut to 200 characters.
`name` is cut to 80 and defaults to `match`. A site has at most 50 goals, and the 51st
returns `400`. A name the site already uses returns `409`.

### Funnels

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/funnels` | Viewer | Lists the saved funnels: `id`, `name`, `steps`, `mode`. |
| `POST /api/v1/sites/:id/funnels` | Editor | Saves a funnel. Returns `201` with its `id`. |
| `PUT /api/v1/sites/:id/funnels/:funnel` | Editor | Replaces a funnel's name, steps, and mode. `404` for an unknown funnel. |
| `DELETE /api/v1/sites/:id/funnels/:funnel` | Editor | Deletes a funnel. Returns `204`, or `404` for an unknown funnel. |

The body takes `name` (required, cut to 80 characters), `steps` (at least 2, and only the
first 8 are kept), and `mode` (`sequential`, `strict`, or `flexible`, default
`sequential`). Steps take the same fields as in
[POST /api/v1/stats/funnel](#post-apiv1statsfunnel).

### Segments

A segment is a saved filter string. A site segment is shared with everyone who can read
the site. A personal segment is visible to its author only, so a viewer can save one.

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/segments` | Viewer | Lists the site's segments and your personal ones, by name: `id`, `name`, `filters`, `personal` (`0` or `1`). |
| `POST /api/v1/sites/:id/segments` | Editor, or Viewer with a session for a personal segment | Saves a segment. Returns `201` with `id`, `name`, `filters`, and `personal`. |
| `DELETE /api/v1/sites/:id/segments/:segment` | Editor for a site segment, the author for a personal one | Deletes a segment. Returns `204`, also for a segment that doesn't exist. |

The body takes `name` (required, cut to 80 characters), `filters` (required, a
[filter string](#filters)), and `personal` (`true` for a personal segment). A segment
with the same name and owner gets the new filters and keeps its id.

### Annotations

Notes on the chart, such as deploys.

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/annotations` | Viewer | Lists up to 500 annotations by time: `id`, `ts`, `text`, `source`. `from` and `to` are milliseconds. `from` defaults to 0, `to` to a day from now. |
| `POST /api/v1/sites/:id/annotations` | Editor | Adds an annotation. Returns `201` and the annotation. |
| `DELETE /api/v1/sites/:id/annotations/:annotation` | Editor | Deletes an annotation. Returns `204`. |

The body takes `text` (required, cut to 200 characters), `ts` (milliseconds or an ISO
date, default now), and `source` (cut to 40 characters, default `manual`). An API key
whose owner is an editor may post one, so CI can mark deploys:

```sh
curl -X POST "https://analytics.example.com/api/v1/sites/shop/annotations" \
	-H "Authorization: Bearer $MISOMOON_KEY" -H "Content-Type: application/json" \
	-d '{"text": "Deployed v2.3.0", "source": "ci"}'
```

### Shared links

A shared link opens a read-only dashboard of one site, with an optional password,
segment, and expiry.

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/shared` | Editor | Lists the links: `slug`, `name`, `protected`, `segment_id`, `expires_at`, `created_at`. |
| `POST /api/v1/sites/:id/shared` | Editor | Makes a link. Returns `201` with `slug`, `name`, `protected`, `segment_id`, and `expires_at`. |
| `DELETE /api/v1/sites/:id/shared/:slug` | Editor | Deletes a link. Returns `204`. |
| `GET /api/v1/share/:slug` | Public | `{"name": ..., "protected": true}`, so the page knows to ask for a password. `404` for a link that expired or was removed. |
| `POST /api/v1/share/:slug` | Public | Trades the link, and its `password` when it has one, for a `sh_` token: `{"token": ..., "site": ..., "name": ..., "expires_at": ...}`. The token lasts 7 days, or until the link expires if that is sooner. A wrong password returns `401`. |

The body of `POST /api/v1/sites/:id/shared` takes `name` (cut to 80 characters, default
`Shared link`), `password`, `segment_id` (a segment applied to every query through the
link), and `expires_days` (at most 3650). Without `expires_days`, the link never expires.

### Email reports and alerts

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/reports` | Editor | `{"subscriptions": [...], "sending": true}`. Each subscription has `id`, `email`, `kind`, `threshold`, `last_sent_at`. `sending` is `false` without an email provider. |
| `POST /api/v1/sites/:id/reports` | Editor | Subscribes an email. Returns `201` with `{"ok": true}`. |
| `DELETE /api/v1/sites/:id/reports/:report` | Editor | Deletes a subscription. Returns `204`. |
| `GET /api/v1/sites/:id/reports/preview` | Editor | The report as it would go out now, as HTML. `kind` is `weekly` (default) or `monthly`. `format=pdf` returns the PDF attachment instead, which needs the `BROWSER` binding (`501` without it, `503` when the print fails). |
| `POST /api/v1/sites/:id/reports/test` | Editor | Sends the report now to `email` (required), with `kind` `weekly` (default) or `monthly`. Returns `{"ok": true}`, or `503` when the email could not go out. |

The body of `POST /api/v1/sites/:id/reports` takes `email` (required), `kind`
(required), and `threshold`, a whole number. A threshold out of range returns `400`. A
second subscription for the same email and kind replaces the threshold.

| `kind` | What it sends | `threshold` |
| --- | --- | --- |
| `weekly` | The last full week, Monday to Sunday, in the site's time zone | Not stored |
| `monthly` | The last full month | Not stored |
| `spike` | An alert when the visitors online in the last 5 minutes reach the threshold. Checked every 5 minutes, at most once in 12 hours. | Visitors online, 1 or more. Default 10. |
| `drop` | An alert when the site has had no pageview for the threshold, if it had pageviews the week before. Checked hourly, sent once until traffic returns. | Hours without a pageview, 1 to 168. Default 12. |

### Imports

Imported history from a CSV export or a Google Analytics property. Unfiltered reports
add it to the site's own data. Every route needs Editor.

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/imports` | Editor | Lists the imports, newest first: `id`, `site_id`, `source` (`csv` or `google`), `label`, `from_day`, `to_day`, `status` (`importing`, `done`, or `failed`), `error`, `rows`, `created_at`. |
| `POST /api/v1/sites/:id/imports` | Editor | Imports a CSV export. Returns `201` and the import. |
| `DELETE /api/v1/sites/:id/imports/:import` | Editor | Deletes the import and its rows on every shard. Returns `204`. |
| `POST /api/v1/sites/:id/imports/google/connect` | Editor | Starts Google sign-in. Returns `{"url": ...}`, the Google consent page. |
| `GET /api/v1/sites/:id/imports/google/properties` | Editor | The Google Analytics properties the signed-in Google account can read, for `grant=<grant id>`: `id` (`properties/123`), `name`, `account`. |
| `POST /api/v1/sites/:id/imports/google` | Editor | Starts a Google import in the background. Returns `202` with `{"id": ..., "status": "importing"}`. |

`POST /api/v1/sites/:id/imports` takes `multipart/form-data` with one or more `file`
fields: a ZIP of the export, or its CSV files. A file counts when its name is
`imported_<table>.csv` or `imported_<table>_YYYYMMDD_YYYYMMDD.csv`. The tables read are
`visitors`, `sources`, `pages`, `entry_pages`, `exit_pages`, `locations`, `browsers`,
`operating_systems`, `devices`, and `custom_events`. A request with no such file returns
`400`. While the site's history moves between shards, an import returns `409`. Try again
a few hours later.

For a Google import, open the URL from `POST /api/v1/sites/:id/imports/google/connect`.
Google returns the person to the dashboard settings with `google=<grant id>` in the URL.
Google sign-in must finish within an hour of the connect call. `POST /api/v1/sites/:id/imports/google`
takes `grant` (required), `property` (required, `properties/123`), `from` and `to`
(`YYYY-MM-DD`, default the earliest day Google serves and yesterday in UTC), and
`label`. The server deletes the grant when the import finishes. Without Google configured,
these routes return `501`.

### Google Search Console

The connected Search Console property feeds `property=search_term` in
[GET /api/v1/stats/breakdown](#get-apiv1statsbreakdown). Every route needs Editor.

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/search-console` | Editor | `{"available": true, "connected": {"property": ..., "created_at": ..., "connected_by": <name>}}`. `available` is `false` without Google configured. `connected` is `null` until a property is connected. |
| `POST /api/v1/sites/:id/search-console/connect` | Editor | Starts Google sign-in. Returns `{"url": ...}`. Google returns the person to the dashboard settings with `search=<grant id>`. |
| `GET /api/v1/sites/:id/search-console/properties` | Editor | The properties the Google account can read, for `grant=<grant id>`: `property` and `matches` (whether it is the site's domain). Matching properties come first. Unverified ones are left out. |
| `PUT /api/v1/sites/:id/search-console` | Editor | Connects a property. Takes `grant` and `property`, which must be one of the listed properties. Returns the same object as `GET`. |
| `DELETE /api/v1/sites/:id/search-console` | Editor | Disconnects the property and revokes the Google token. Returns `204`. |

### Payment webhooks

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/revenue` | Editor | `{"sources": [...], "last_30_days": {"payments": 12, "attributed": 9}}`. Each source has `provider`, `webhook_url`, `created_at`, `last_event_at`, `last_test_at`, and `last_error`. |
| `PUT /api/v1/sites/:id/revenue/:provider` | Editor | Connects a provider: `stripe`, `polar`, `dodo`, `lemonsqueezy`, or `custom`. Returns `provider` and `webhook_url`. Also turns on the site's `payments` feature. |
| `DELETE /api/v1/sites/:id/revenue/:provider` | Editor | Disconnects a provider. Returns `204`. |
| `POST /api/webhooks/:provider/:site` | Public, signed by the provider | Takes the provider's webhook. Returns `{"ok": true, "counted": 2}`, or `{"ok": true, "test": true, "counted": 0}` for a test event. |

`PUT` takes `{"secret": "whsec_..."}`, the signing secret, which `stripe`, `polar`, and
`dodo` require. For `lemonsqueezy` and `custom`, a secret is optional and needs at least
16 characters. Without one, the server makes a secret and returns it once as `secret`.
An unknown provider returns `404`.

The webhook returns `404` for an unknown provider or a site without that webhook, `413`
for a body over 256 KB, `401` when the signature does not match the saved secret, and
`400` for a body it can't read. [Connect payments](revenue.md) lists the events each
provider sends and the body for `custom`.

### Managed proxy

The site's own subdomain, such as `stats.example.com`, pointed at misomoon with a CNAME
([Serve the tracker from your own domain](PROXY.md)). Every route needs Editor.

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/sites/:id/proxy` | Editor | `{"available": true, "target": <CNAME target>, "domain": {...}}`. `domain` has `hostname`, `status`, `ssl_status`, `active`, `records` (the DNS records to add: the CNAME and any TXT records), and `script` (the tracker URL on the hostname). It is `null` without a hostname. While the hostname is not active, each call refreshes its state from Cloudflare. |
| `PUT /api/v1/sites/:id/proxy` | Editor | Sets the hostname: `{"hostname": "stats.example.com"}`. It must be a subdomain of the site's domain, other than `www`. A new hostname replaces the old one. Returns the same object as `GET`. |
| `DELETE /api/v1/sites/:id/proxy` | Editor | Removes the hostname. Returns the same object as `GET`, with `domain` set to `null`. |

Without Cloudflare for SaaS configured, `PUT` returns `501` and `available` is `false`.
A Cloudflare API error returns `502`.

## Accounts and teams

Roles, from most to least access: owner, admin, editor, viewer, and billing.
[Architecture](ARCHITECTURE.md#auth-and-team-roles) lists what each role can do.

### Sign-in

| Method and path | Role | What it does |
| --- | --- | --- |
| `POST /api/v1/auth/signup` | Public | Creates an account and a team. |
| `POST /api/v1/auth/login` | Public | Starts a browser session. Takes `email` and `password`. Returns `token`, `expires_at`, and `user`. A wrong email or password returns `401`. |
| `POST /api/v1/auth/logout` | Any | Ends the `ms_` session in the header. Returns `204`. |
| `POST /api/v1/auth/forgot` | Public | Emails a password reset link for `email`. |
| `POST /api/v1/auth/reset` | Public | Sets a new password from a reset link. |

`POST /api/v1/auth/signup` takes `email`, `password`, and `name` (cut to 80 characters,
default the part of the email before `@`). It creates a team named `<name>'s sites` with
you as owner, and returns `201` with `token`, `expires_at`, and `user`. An email that
already has an account returns `409`. Whether sign-up is open depends on `SIGNUPS`
([Variables](configuration.md#variables)):

| `SIGNUPS` | Sign-up |
| --- | --- |
| unset or `open` | Open to anyone. |
| `invite` | Open only while the server has no account, so the first person can claim it. After that it returns `403`, and people join through an invitation. |
| `closed` | Always `403`, the first account included. Invitations still work. |

A password has 10 to 200 characters. `POST /api/v1/auth/forgot` always returns
`{"ok": true, "sending": ...}`, whether or not the email has an account. `sending` is
`false` without an email provider. The link works for an hour and replaces any earlier
link. `POST /api/v1/auth/reset` takes `token`, the code from the link, and `password`. It
signs out every other session of the account and returns a new `token` and `expires_at`.
An expired link returns `400`.

### Your account

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/me` | Any | Who you are, and what you can open. |
| `PATCH /api/v1/me` | Session | Changes `name` (cut to 80 characters), or `password` with `current_password`. Returns `id`, `email`, and `name`. A wrong `current_password` returns `401`. |
| `DELETE /api/v1/me` | Session | Deletes your account. Takes `{"password": "..."}`; a wrong or missing password returns `401`. The teams only you are in are deleted with their sites and all of their data; you leave your other teams, lose guest access, and your sessions, API keys, saved segments, pending invitations and email reports go too. If you are the only owner of a team with other members, it returns `409` until you make one of them an owner. Returns `204`. |

`GET /api/v1/me` returns:

| Field | Meaning |
| --- | --- |
| `kind` | `user`, `key`, `share`, or `anonymous` |
| `user` | `id`, `email`, and `name` of the signed-in user or the key's owner, or `null` |
| `teams` | Your teams with `id`, `name`, and your `role`. Empty except for a browser session. |
| `sites` | The same list as `GET /api/v1/sites` |
| `demo` | The public demo site's id (`DEMO_SITE`), or `null` |
| `signups` | Whether `POST /api/v1/auth/signup` is open |
| `imported` | The ids of your sites with a finished import |
| `search` | The ids of your sites with Search Console connected |
| `share` | For a shared link, `slug` and `segment` (its filter string). Otherwise `null`. |

### API keys

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/keys` | Session | Your keys, newest first: `id`, `name`, `prefix`, `site_id`, `created_at`, `last_used_at`. |
| `POST /api/v1/keys` | Session | Makes a key. Takes `name` (cut to 80 characters, default `API key`) and `site`, which limits the key to one site you can read. Returns `201` with `id`, `name`, `key`, `prefix`, and `site_id`. `key` is shown once. |
| `POST /api/v1/keys/:key/rotate` | Session | Gives a key a new secret and returns it once. The name and site stay, and the old secret stops working at once. |
| `DELETE /api/v1/keys/:key` | Session | Deletes a key. Returns `204`. |

### Teams and members

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /api/v1/teams` | Session | Your teams: `id`, `name`, your `role`, and the number of `members` and `sites`. |
| `POST /api/v1/teams` | Session | Makes a team with you as owner. Takes `name` (cut to 80 characters, default `My team`). Returns `201` with `id`, `name`, `created_at`, and `role`. |
| `PATCH /api/v1/teams/:team` | Session, team owner or admin | Renames the team. Takes `name`. |
| `DELETE /api/v1/teams/:team` | Session, team owner | Deletes the team. A team that still has sites returns `409`. Returns `204`. |
| `GET /api/v1/teams/:team/members` | Session, team owner or admin | `{"members": [...], "guests": [...], "invitations": [...]}`. Members have `id`, `email`, `name`, `role`, `created_at`. Guests of the team's sites have `id`, `email`, `name`, `role`, `site_id`. Pending invitations have `id`, `email`, `role`, `site_id`, `expires_at`, `created_at`. |
| `PATCH /api/v1/teams/:team/members/:user` | Session, team owner or admin | Changes a member's `role` to `owner`, `admin`, `editor`, `viewer`, or `billing`. |
| `DELETE /api/v1/teams/:team/members/:user` | Session, team owner or admin, or the member themselves | Removes a member, or leaves the team. Returns `204`. |
| `POST /api/v1/sites/:id/transfer` | Session, owner of the site's team | Moves the site to `team`, where you need to be owner or admin. Guests who are members of the new team stop being guests, and the site's pending invitations are deleted. |

A `:user` who is not on the team returns `404`. An admin can't make an owner, change
an owner's role, or remove an owner (`403`). A change that would leave the team without an
owner returns `409`.

### Invitations

| Method and path | Role | What it does |
| --- | --- | --- |
| `POST /api/v1/teams/:team/invitations` | Session, team owner or admin. For a guest, Admin on `site`. | Invites `email` and returns `201` with `id`, `email`, `role`, `site_id`, `url`, and `sent`. |
| `DELETE /api/v1/teams/:team/invitations/:invitation` | Session, team owner or admin | Withdraws an invitation. Returns `204`. |
| `GET /api/v1/invitations/:token` | Public | What the invitation is for: `email`, `role`, `team`, `site`, `invited_by`, and `has_account`. `404` for an invitation that expired or was withdrawn. |
| `POST /api/v1/invitations/:token/accept` | Public, or Session as the invited email | Joins the team, or the site as a guest. Returns `site` (the guest site, or the team's first site) and `team`. |

`POST /api/v1/teams/:team/invitations` takes `email`, `role`, and `site`:

- Without `site`, it invites a team member. It needs a session that is team owner or
  admin, and `role` is a team role. Only an owner can invite an owner. An email that is
  already on the team returns `409`.
- With `site`, it invites a guest to that one site. It needs Admin on the site, which must
  belong to the team, and `role` is `editor` or `viewer`.

A new invitation for the same email and site replaces the earlier one. The link in `url`
works for 7 days. The server emails it and sets `sent` to whether the email went out, so
the link can be passed on another way.

To accept, a person signed in with the invited email sends no body. Signed in with another
email, the request returns `403`. Without a session, the body takes `name` and `password`,
and the server creates the account for the invited email and also returns `token` and
`expires_at`.

### Guests

| Method and path | Role | What it does |
| --- | --- | --- |
| `PATCH /api/v1/sites/:id/guests/:user` | Admin | Changes a guest's `role` to `editor` or `viewer`. |
| `DELETE /api/v1/sites/:id/guests/:user` | Admin, or the guest themselves | Removes a guest from the site, or leaves it. Returns `204`. |

## Event ingestion

`POST /api/event` takes one event as JSON. The tracker sends it as `text/plain` so the
browser makes no preflight request. The response is always `202`, even for an event that
is dropped, so the endpoint reveals nothing about which sites exist. Events past a site's
daily cap are dropped too ([Daily ingest cap](configuration.md#daily-ingest-cap)). It is
Public. `OPTIONS /api/event` answers a preflight with `204`.

| Field | Meaning |
| --- | --- |
| `s` | Site id. Required. |
| `n` | Event name: `pageview`, `engagement`, or a custom name of 1 to 120 characters, without control characters, semicolons, or vertical bars. Without it, a beacon with `e` is an engagement and one with `w` a pageview, as `m.js` sends them. |
| `u` | The full page URL, `http` or `https`. Required. Its hostname must be the site's domain or a subdomain of it. |
| `r` | `document.referrer` |
| `t` | `document.title` |
| `w`, `h`, `vw` | Screen width and height, viewport width |
| `l` | `navigator.language`. Without it, the request's `Accept-Language` |
| `p` | Custom properties: an object of strings, numbers, and booleans. The server keeps the first 30 whose keys are 1 to 64 letters, digits, `_`, `.`, or `-`, and cuts strings to 300 characters. |
| `$` | Revenue: `{ "a": 19, "c": "USD" }`, or `{ "amount": 19, "currency": "USD" }` |
| `k` | Payment keys: a ref, or a list of checkout ids. At most 4 are kept. |
| `i` | `false` keeps a custom event from ending a bounce |
| `e`, `d`, `v` | Engagement only: engaged milliseconds, deepest scroll percent, and Web Vitals |
| `q` | Pageview only: the site search term. Kept only when the site tracks `search`. Without it, the server reads the term from the page URL's search parameters. |
| `c`, `x`, `f`, `g`, `m`, `o` | Engagement only: what happened on the page since the last beacon, as lists of arrays. `c` clicks `[selector, label, clicks, rage, dead]` (at most 30), `x` errors `[message, source, count]` (5), `f` forms `[form, started, submitted]` (10), `g` form fields `[form, field, position, touched, dropped]` (50), `m` media `[name, type, played, 25%, 50%, 75%, 95%]` (10), and `o` content `[name, seen, clicked]` (20). Numbers are counts since the last beacon. |
| `ts` | Client timestamp in milliseconds. The server uses it when it is within 5 minutes of the server's clock, and its own time otherwise. |
| `id` | A UUID for the event. A second event with the same id is not stored, so a client can resend after a lost response. The server picks an id when it is missing or not a UUID. |

The server removes emails, ids, tokens, and numbers of 6 or more digits from `q` and from
the text in the interaction lists. Form fields carry names and flags, never values.
Pageviews and engagements on a path that the site's `include_paths` or `exclude_paths`
leave out are dropped.

Bodies over 16 KB are dropped. Bots are dropped by Cloudflare's bot signals and by
user-agent patterns.

A server that sends events for a visitor sets `X-Misomoon-Ip` to the visitor's address
and `User-Agent` to the visitor's user agent. `X-Misomoon-Country`, `-Region`, `-City`,
`-Continent`, and `-Timezone` carry the location, URL-encoded. These are the headers a
[first-party proxy](PROXY.md) sets. An app sends a user agent of the form
`MisomoonApp/<sdk version> (<platform>) <app name>/<app version>`, and reports show the
app name in place of the browser. [The SDK guide](sdk.md) covers both.

`GET /api/health` returns `200` with `{"ok": true}` when the Worker is up.

## Tracker files

| Method and path | Role | What it does |
| --- | --- | --- |
| `GET /m.js` | Public | The tracker. `?s=<site id>` adds the code for the features the site turned on in its settings. Without a known site, it is the core alone, which counts nothing. Browsers cache it for 5 minutes with `s` and for an hour without. |
| `GET /overlay.js` | Public | Draws clicks and scroll depth on the site's own page. `m.js` loads it only on a page opened with `#misomoon-overlay` in the URL. Browsers cache it for an hour. |

On a managed proxy hostname, the Worker serves `/m.js`, `/overlay.js`, and `/api/event`
only. Every other path returns `404`.

## MCP endpoint

`POST /mcp` takes JSON-RPC 2.0 requests from MCP clients, with the same bearer tokens as
the API. A batch holds at most 20 requests, and a body over 64 KB returns `413`. `GET /mcp`
returns `405`, because the server does not stream. [Ask AI tools about your traffic](mcp.md) lists the tools and
the client setup.

---

# misomoon analytics — architecture

Privacy-first web analytics built entirely on Cloudflare: Workers for compute, D1 for
storage, Queues for buffered ingest, static assets for the dashboard.
`dupuu-api/services/analytics` was the reference for metric
definitions (visits, bounce, funnels, goals); nothing is shared with it at runtime.

```
                       ┌──────────────────────────── apps/api (Worker) ───────────────────────────┐
 site ──m.js──▶ POST /api/event ─▶ enrich (cf geo, UA, bot, salt hash) ─▶ Queue ─▶ consumer ─┐   │
                       │                                   (no queue bound → write inline)     │   │
                       │                                                                       ▼   │
                       │   CONTROL D1  sites · shard_map · shards · api_keys · goals · salts   SHARD_0..N D1
                       │                                                                    events · sessions
 dashboard ─▶ /api/v1/stats/*  ─┐                                                                   ▲
 MCP client ─▶ /mcp           ─┴─▶ query planner ─▶ fan out to shard ranges ─▶ merge ─────────────┘
                       └──────────────────────────────────────────────────────────────────────────┘
 apps/landing  SvelteKit SSR on Workers (marketing site, live demo link)
 apps/dashboard  Svelte 5 SPA, built with Vite+ (`vp dev`), served from the api Worker's assets
```

## Packages

| Path | What it is |
| --- | --- |
| `packages/core` | Pure TypeScript shared by every runtime: event schema, UA parsing, channel classification, filter grammar, SQL builders, shard planning and result merging. Unit tested against `node:sqlite`. |
| `packages/tracker` | `m.js`, the core tracker, under 1 KB gzipped, and the feature parts in `src/x/` that the Worker adds to it per site. No cookies; it only reads the `misomoon_ignore` key from localStorage. `overlay.js` draws clicks and scroll on a page the dashboard opens. |
| `packages/sdk` | `@misomoon/sdk`, published to npm: `m.js` for bundled browser apps and React, and a client for React Native and servers. |
| `packages/brand` | Design tokens (`tokens.css`), logo, fonts. Used by landing and dashboard. |
| `apps/api` | The single Worker: ingest, queue consumer, stats API, MCP server, dashboard assets. |
| `apps/dashboard` | Svelte 5 SPA. |
| `apps/landing` | SvelteKit with `adapter-cloudflare`. |

## Sharding

D1 databases cap out (10 GB each) and a single database serialises writes, so event
data never lives in one database.

* **Control database** (`CONTROL`) holds small, hot, relational data: sites, keys,
  goals, funnels, daily salts, the shard registry and the routing table.
* **Shard databases** (`SHARD_0` … `SHARD_n`) hold `events`, `sessions` and
  `imported`. Their count is one number: `SHARD_COUNT=<n> pnpm run deploy`
  (`apps/api/scripts/deploy.ts`). Growing creates the missing D1 databases, binds them
  in `wrangler.jsonc`, migrates every database and deploys; a bound shard registers
  itself in `shards` once its schema is there, and never before. Shrinking marks the
  extra shards `retiring`. Every five minutes the Worker closes their sites' open
  ranges onto other shards, then copies each closed range (settled for two days) to
  another shard, switches `shard_map`, and deletes the old copy two cache lifetimes
  later (`src/moves.ts`, progress in `shard_moves`, resumable). Running the same deploy
  again unbinds each retiring shard once it holds nothing. Databases are never deleted
  by the script. Without `SHARD_COUNT` the deploy keeps the current count.
* **What is config and what is data.** Workers can't bind a D1 database at runtime, so
  the shard list is deploy-time config. Everything that changes at runtime is a row in
  `shards`: `weight`, `status` (`active`, `draining`, `readonly`, `retiring`) and
  `size_bytes`, so draining a shard or pinning a tenant needs no deploy. Two vars tune
  it: `SHARD_SOFT_LIMIT_MB` (when a shard drains, default 8000 of D1's 10 GB) and
  `RETENTION_DAYS`.
* **Routing is per site *and* per time range.** `shard_map(site_id, from_day, to_day,
  shard)` is a directory: it says where a site's data for a span of UTC days lives. A
  new site is placed by weighted rendezvous hashing, where each shard's weight is
  scaled by its free space (`shards.size_bytes`, refreshed hourly), so a fresh shard
  takes most new sites and a full one takes none. When a shard grows past its soft
  limit (`SHARD_SOFT_LIMIT_MB`) it is marked `draining`; the next write for each of
  its sites closes the open range at the end of today (tomorrow when today ends
  within two cache lifetimes, so no isolate still routes by a stale map) and opens a
  range on another shard. A day never straddles two shards, and old data only
  moves when a shard is retired. The close and the open are one conditional batch,
  so racing isolates can't open two ranges.
* **Reads fan out.** The planner intersects the query window with the site's ranges,
  clamps each sub-query to its range, runs them in parallel and merges. Ranges always
  split on UTC day boundaries, and visitor ids rotate daily (see below), so unique
  visitor counts from disjoint ranges add up exactly. Ratios (bounce rate, duration,
  views per visit) are merged from their numerators and denominators, never averaged.
  Reads go through a D1 session (`withSession`), so once read replication is enabled
  on a shard, dashboard scans run on replicas instead of queueing behind ingest on the
  single-threaded primary.
* **Deletes are chunked** (`purge` in `control.ts`, 5,000 rows a statement): a single
  huge DELETE would pass D1's 30 s limit and stall every write to the shard.
* **Large tenants** can be pinned to a dedicated shard by writing their `shard_map`
  row by hand; nothing else changes. One D1 database is single-threaded, so a site
  that outgrows a whole shard's write rate would need its days split further by
  `visitor_id` hash. That stays additive (a visitor and their sessions live on one
  shard) but is not built yet.

Next steps when volume demands it: hourly rollup tables per shard written by a cron
trigger (queries over long ranges then read rollups plus today's raw rows), D1 read
replication with the Sessions API for dashboard reads, and an R2 archive for raw
events past the retention window.

## Ingest

1. `m.js` sends `pageview`, `engagement` (on hide: engaged time, max scroll depth,
   Core Web Vitals), and custom events with `navigator.sendBeacon`.
2. The Worker drops bots (Cloudflare bot signals, UA patterns, headless hints),
   resolves geo from `request.cf` (country, region, city, continent, timezone, ASN
   organisation), parses the UA, classifies the channel, and computes
   `visitor_id = sha256(daily_salt ‖ site ‖ ip ‖ ua)[0..16]`. The IP is never stored.
   Salts are random per UTC day and deleted after two days, so ids cannot be linked
   across days. The salt rotates at 00:00 UTC, not at the site's local midnight, so a
   unique count over a local day that spans 00:00 UTC can count one person twice.
   Behind a first-party proxy the connection belongs to the proxy, so the IP and geo
   come from forwarded headers instead (`edgeFromRequest` in `core/src/proxy.ts`,
   see [Serve the tracker from your own domain](PROXY.md)).
3. With a Queue bound, the event is enqueued and the response is `202` immediately;
   the consumer batches by shard. Without one (local dev), or when the send fails, it
   is written inline in `ctx.waitUntil`.
4. Sessions: an event joins the visitor's session when the session's last activity is
   within 30 minutes; otherwise it opens a new one. `sessions` is upserted on every
   event, which makes bounce, duration, entry and exit pages single-table reads.
   A visit open at 00:00 UTC stays one visit: in the first 30 minutes of a UTC day the
   Worker also computes the visitor's id under yesterday's salt, and the event joins an
   open session under either id, as long as yesterday wrote to the same shard (when the
   site moved shards at midnight, the visit splits). The continued session records the
   new id in `next_visitor_id`, so it keeps matching after that half hour. Each event
   keeps its own day's id, and only visits that were active across midnight link the
   two days' ids, through their shared session.
5. Every event carries a random, unique `event_id` (index `events_event_id`). Events
   are written with `INSERT OR IGNORE` and the session upsert only runs when that
   insert added a row (`WHERE changes() > 0`), so a queue retry after a partial write
   stores nothing twice and counts nothing twice. The SDK picks the id on the client
   (`id` in the payload), so its resend after a lost response is deduplicated the same
   way. `m.js` sends no id: `sendBeacon` never resends.
6. Revenue is kept with its ISO 4217 currency. Each site has one reporting currency
   (`sites.currency`, USD by default); revenue totals count events in that currency
   and events sent without one, never a sum across currencies.

### Ingest cap

Each site may store at most its daily cap of events per UTC day (`sites.ingest_cap`, else
`INGEST_DAILY_CAP`; none when both are unset, and `0` blocks the site). The code is in
`apps/api/src/usage.ts`. The cap counts stored rows, engagement pings included, because
the cost is D1 writes: about 15 rows written per event, against 1 more per site per batch
for the count.

* **Counting.** After each shard batch, `writeEvents` reads `meta.changes` of every event
  insert and adds the new rows to CONTROL `usage_daily(site_id, day)`. A replayed queue
  batch inserts nothing, so it counts nothing. `events` holds pageviews and custom events,
  which is what a plan counts; `stored` holds every row. A failed count is tried once
  more and then logged as `usage count failed`, without failing the batch: a retry would
  find the events stored already and count nothing.
* **Enforcing.** `writeEvents` reads each site's cap. For each shard group, `Budget.plan`
  runs `assignSessions` on copies first, to see which rows the shard would store. An
  engagement ping outside any visit stores nothing, and an event the shard holds already
  (a retried batch) is stored once, so neither takes room. Room for the rest is taken in
  one statement per site and day: an upsert adds what fits under the cap to `stored` and
  returns it as `last_grant`. Every `SET` reads the row as it was, so two consumers can't
  both take the last of it. The earliest rows that fit are kept, and the sessions are
  built again without the dropped ones. Once the group is written, its count adds what the
  shard inserted less the room taken, which gives back what went unused, also when the
  shard write fails. A consumer that fails before that leaves `stored` too high, so the
  day stores less than its cap, never more. Payments come through `revenue.ts` and are
  never capped.
* **The edge.** `acceptBeacon` drops a beacon once the day's count, read through the
  isolate cache (60 seconds), reaches the cap. A flood then stops costing queue
  operations within a minute. Sites without a cap skip the read.
* **Payment refs.** A ref-only beacon (an engagement ping that only carries payment refs,
  no event row) is dropped at the edge for a site that takes no payments. For a site that
  takes payments, its refs count as one stored row, marked by event id in `usage_refs`, so
  a queue retry counts it once. It takes room when there is some, and is kept when there
  is none, so the payment keeps its visit. Only these beacons, queued before the edge saw
  the day full, take a day past its cap.
* **Telling people.** The first drop of a site's day sets `capped_at` and emails the team's
  owners and admins once. A block sends nothing. Rows older than 400 days are deleted.
  Maintenance also deletes `usage_refs` rows older than 2 days.

The alternatives cost more per beacon. A Durable Object per site counts exactly but adds a
billed call and a round trip to every beacon. The rate-limiting binding takes its limit
from `wrangler.jsonc`, so it can't hold a limit per site. KV charges $5 per million
writes.

### Payments

Payment webhooks (`POST /api/webhooks/:provider/:site`, `apps/api/src/revenue.ts`) become
`Payment` and `Refund` events on the site's shard. Parsing and signature checks live in
`packages/core/src/payments.ts`. A payment finds its visit through keys, strongest first:
a ref from `misomoon.ref()` or a tagged payment link, a checkout id that the server read
from the success page's URL, then `provider:kind:id` links (subscription, customer, order) that
an earlier payment of the same buyer taught. Tracker keys must match `REF_PATTERN`, which
has no colon, so a beacon can't forge a link.

The visit's columns are kept in CONTROL `attribution` (30 days for tracker keys, 400 for
links), so the lookup reads no shard. When two visits claim a key, the earlier one keeps
it. A payment with no visit is written unattributed, and its keys go to `payment_keys`. A
payment credited through a weaker key keeps its stronger keys there. When one of those
keys arrives, or the key that credited a payment leads to another visit, `settle()`
updates the event row in place, re-points the links the payment taught
(`attribution.source`), and settles the payments credited through them, such as its
refunds. It goes on only while a payment's visit actually changes, claims a key again
only when the key leads to a new visit, and writes the payment's own row
(`attributed_by`, `visit`) last, so a queue or webhook retry redoes a pass that failed
part way. One pass moves at most 200 payments. Past that it throws, and the retry carries
on from the moves already written. Final attribution doesn't depend on the order in which
webhooks and beacons arrive. A payment's event id is `$provider:site:id`, because one
provider account can feed two sites on one shard. `visitor_id` and `session_id` are copied only when the visit
is on the payment's UTC day; otherwise the row has `visitor_id ''`, which every unique
count skips with `NULLIF`. Breakdowns by a session dimension read revenue from events
directly, so a renewal still counts toward its source when the source had no visit in
the range.

## Data captured beyond page views

Engaged time (while the page is shown and has focus), max scroll depth, LCP / INP / CLS / FCP / TTFB,
browser and OS versions, viewport and screen class, language, timezone, continent,
ASN organisation, outbound link clicks, file downloads, form submits, revenue,
and arbitrary custom properties. Everything is opt-out per site in tracker options.

### Page interactions

The engagement beacon also carries what happened on the page since the last beacon:
clicks per element (with rage and dead clicks), JavaScript errors, the form fields a visit
used and the one it would leave at, media plays and milestones, and impressions and clicks
of tagged content. The server reads a pageview's site search term from its URL
(`searchTermFromUrl` in `packages/core/src/features.ts`), so the tracker sends none. `eventDetail` in
`packages/core/src/ingest.ts` cleans and caps these lists, and the row keeps them as JSON in
the nullable `events.detail` column (shard migration `0002_event_detail.sql`).

Every number on the beacon is a delta, so the beacons of one page view add up. A form
field's `dropped` flag is +1 while the field is where the visit would leave the form and -1
once it isn't, so a visit that moves on cancels its earlier drop. The reports in
`packages/core/src/queries.ts` (`clickMap`, `scrollMap`, `siteSearch`, `errorReport`,
`formReport`, `mediaReport`, `contentReport`) sum the lists with `json_each` on each shard
and merge the shards in TypeScript. Visitor counts per row are distinct per shard and add
across shards, like every other unique count. No new table, so moves and purges cover
`detail` as they cover the rest of the row.

### The tracker and its features

`m.js` holds only pageviews (with history and hash routing), engaged time, scroll depth,
script-wide props, the queue and the public API, and stays under 1 KB gzipped; a test in
`packages/tracker/test/m.test.ts` fails the build at 1,000 bytes. Everything else is a
feature a site ticks in its settings: outbound links, downloads, form submits, tagged
events, payments, Web Vitals, clicks, errors, form fields, media, content, and site
search. The control database stores them in `sites.features`, with `search_params`,
`include_paths` and `exclude_paths` beside them (control migrations
`0004_site_features.sql` and `0005_site_paths.sql`). `NULL` features means the default:
every feature. `LIGHT_FEATURES` is the Light preset the dashboard offers.

The script tag loads `m.js?s=<site>`. The Worker answers with `m.js` followed by the parts
the site ticked (`browserParts` in `packages/core/src/features.ts`), read from
`packages/tracker/dist/parts.min.js`: one minified source per file in
`packages/tracker/src/x/`. Browsers cache it for five minutes. Each part registers through
`misomoon.x(fn)` and hooks the engagement beacon and soft navigations, so `m.js` doesn't
know which parts exist; a browser the tracker doesn't count runs none of them.

The server does what the tracker would otherwise carry code for. `acceptBeacon` in
`apps/api/src/ingest.ts` reads the site search term and a success page's checkout ids
from the page URL, and drops the views and time of pages the path rules leave out.
`buildEvent` names the tracker's unnamed beacons (an engagement carries `e`, a pageview
`w`), takes the language from `Accept-Language`, rounds and caps the scroll depth, and
reads revenue as `{ amount, currency }` or `{ a, c }`.

The overlay never carries a token. The dashboard opens the page with `#misomoon-overlay`;
`m.js` then tracks nothing and loads `overlay.js` from next to its own URL, never from a URL
in the page. `overlay.js` asks `window.opener` for the data by `postMessage`, and the
dashboard answers only the window it opened, and only when the message's origin is on the
site's domain.

## Query surface

The dashboard, the Stats API and the MCP tools (`apps/api/src/tools.ts`) all call the
same query functions in `apps/api/src/stats.ts`, so an answer in an MCP client matches
the dashboard number.

* `GET /api/v1/stats/{aggregate,timeseries,breakdown,realtime,vitals,funnel}`.
  With `compare`, `change` is the percent change per metric, except `bounce_rate`,
  which changes in percentage points.
* `GET /api/v1/stats/export`: a zip of CSVs (one per report).
* `GET|POST /api/v1/sites`, `GET|POST|DELETE /api/v1/sites/:id/goals`, `.../segments` (saved filters),
  `GET|POST /api/v1/sites/:id/funnels`, `PUT|DELETE /api/v1/sites/:id/funnels/:funnel`,
  `GET|POST /api/v1/keys`, `DELETE /api/v1/keys/:id`
* `GET /api/v1/stats/journeys?path=/,/pricing&direction=forward|backward`: the next (or
  previous) page after a path, with `(exit)` and `(entrance)` for visit ends. Reloads fold.
* `POST /api/v2/query`: Stats API v2 (metrics, dimensions, filters,
  date_range, order_by, pagination).
* `.../imports` (CSV upload, Google OAuth import), `.../shared` (shared links),
  `.../reports` (email reports and alerts), `.../annotations` (chart notes; any
  non-shared API key may post, so CI can mark deploys).
* Stats endpoints are rate limited per API key, or per IP without one (`STATS_LIMIT`).

### Imported history

CSV exports and Google reports land in each shard's `imported` table, one row per
local day, dimension and key. Rows route to shards by
day like events, so the window fan-out stays the same. They are added only to unfiltered
reports (filters can't be applied to pre-aggregated rows) and `imported=0` hides them.

### Google Search Console

Editors connect a Search Console property per site through Google OAuth (the same client
as the Google import, `apps/api/src/google.ts`). The `search_term` breakdown, the dashboard's
Sources → Search terms tab and the MCP `get_search_terms` tool read Google live
(searchAnalytics.query, cached ten minutes): clicks, impressions, CTR and position. Only
page and device filters can be passed to Google; source==Google is implied, and other
filters are refused rather than silently ignored.

### Shared links, reports, alerts

A shared link trades its slug (and password, PBKDF2-hashed) for a 7-day HMAC token. The
token reads one site, with the link's segment forced on every query; settings are off. The cron runs every 5 minutes: spike alerts every run; weekly and monthly
reports and drop alerts at minute 15, through the email provider (`sendEmail` in `reports.ts`:
Cloudflare Email Service or Amazon SES). With the `BROWSER` binding, `reportPdf`
prints each edition once per run through a Browser Run quick action (`printReport` in
`packages/core/src/report.ts` lays the sheets out as pages) and attaches it; a failed print
sends the email without it.

Metric definitions: visit duration runs from the first to the
last pageview or custom event (engagement pings don't stretch it), a custom event sent
with `interactive: false` doesn't end a bounce, bounce rate under a page filter counts
visits that entered on that page, time on page is engaged time per visit, scroll depth
averages each visit's deepest scroll, exit rate is exits over the page's pageviews, and
funnels count each day's visitor (sequential, strict or flexible).
* `POST /mcp` — stateless MCP (Streamable HTTP, JSON responses), bearer API key.

Filters use one grammar everywhere: `country==US;page~/blog;browser!=Safari`. The
operator is the first one in the text, so values may contain `==`; they cannot contain
`;` or `|`. At most 8 filters, 6 values each, 16 values in total.

Periods are resolved in the site's IANA timezone, per instant: day, week and month
buckets start at local midnight even across a DST change (`time.ts`, `offsetSegments`).
A series has at most 1500 buckets; asking for more is a 400 that names a coarser
interval.

## Auth and team roles

People sign in with email and password (PBKDF2). A session is a random `ms_` token
stored hashed in `sessions`; an unlocked shared link gets an `sh_` token in the same
table, so deleting the link ends every session for it. API keys (`mm_`) belong to a user,
can be limited to one site, and act with that user's role, so a key loses access when its
owner does.

Teams own sites. Each member holds one role on every site of the team:

| Role | Can |
|---|---|
| owner | everything: team settings, moving sites between teams, other owners |
| admin | people (except owners), adding and deleting sites, all settings |
| editor | goals, funnels, segments, imports, shared links, reports, annotations, proxy, adding sites |
| viewer | stats, personal segments |
| billing | no stats. It grants the `billing` permission, which no route checks yet, because misomoon has no plans |

Guests are invited to one site as editor or viewer. The rules live in
`packages/core/src/roles.ts`; `authorize(env, who, site, permission)` in
`apps/api/src/auth.ts` is the only gate, used by the REST API, Stats API v2 and MCP
alike. Public sites (the demo) are readable signed out. A team always keeps an
owner. Invitations are `mi_` links, emailed when an email provider is set up and returned
to the inviter either way; `SIGNUPS=invite` closes open sign-up.

The Worker runs first for every path (`run_worker_first: true`) and serves the
dashboard assets itself, so a customer's proxy hostname answers only the tracker and
the event endpoint, never the app.

---

# How misomoon compares

This page compares misomoon with other analytics tools. The facts about other products
come from their own pricing pages, docs, repositories, and license files, checked on
**2026-10-24**. Prices, plans, and features change. Follow the links to confirm before
you decide. If you find a fact that is wrong or out of date, open an issue or a pull
request with the source, and we will fix it.

"Their claim" marks a statement that a vendor makes about itself, such as whether a
consent banner is needed. This page is not legal advice.

## Where misomoon is different

misomoon runs entirely on Cloudflare in your own account: a Worker, D1 databases, and a
queue. Nothing to rent, patch, or keep running. Other self-hosted tools need a server
with Docker and a database such as Postgres or ClickHouse. misomoon needs a Cloudflare
account and one deploy.

Every feature is in the one free version: funnels, journeys, revenue, Core Web Vitals,
email reports, and Google import. It also has a built-in MCP server, so Claude, Cursor,
and other MCP clients can read your numbers directly.

The trade-off is that misomoon depends on Cloudflare. If you can't use Cloudflare, or you
need a tool that runs on your own hardware, a Docker-based option fits better.

## Self-hosted and open-source tools

| | misomoon | Plausible CE | Umami | Matomo | PostHog | Rybbit |
| --- | --- | --- | --- | --- | --- | --- |
| License | MIT | AGPL-3.0 | MIT | GPL-3.0 | MIT, except the proprietary `ee/` folder | AGPL-3.0 |
| What self-hosting needs | A Cloudflare account | Docker, Postgres, ClickHouse, 2 GB RAM | Node.js and Postgres | PHP 8.1+, MySQL or MariaDB, a web server | Docker with ClickHouse, Postgres, Kafka, Redis, MinIO; 4 vCPU and 16 GB RAM | Docker, ClickHouse, 2 GB RAM |
| Servers to maintain | None | Yes | Yes | Yes | Yes | Yes |
| Self-hosted edition limits | None | No funnels, journeys, or revenue goals | No email reports | Funnels and Web Vitals are paid plugins | Paid features are cloud-only. Self-hosting is "officially unsupported". | No email reports or Pages view |
| Cookieless by default | Yes | Yes (their claim) | Yes (their claim) | No. Cookies are on until you turn them off. | No. Cookieless mode is opt-in. | Yes (their claim) |
| Funnels | Yes, 3 modes | Cloud Business plan | Yes | Paid plugin | Yes | Yes |
| Revenue | Yes, per-site currency | Cloud Business plan | Yes | Yes | Yes | Not checked |
| Core Web Vitals | Yes | Not in docs | Yes | Paid plugin | Yes | Yes |
| Official MCP server | Yes, built in | No (third-party only) | Yes | Yes | Yes | Yes |
| Import from Google | Yes | Yes | No | Yes | Manual, through BigQuery | No |
| First-party proxy | Managed subdomain or self-run, with one-click deploys | Self-run (managed on Enterprise) | Self-run | Self-run | Managed on their cloud | Self-run |
| Tracker size, gzipped | 998 bytes core, 1.8 KB with the Light preset, 4.8 KB with every feature (measured) | 1.3 KB for `script.js`, 2.5 KB for the current per-site script (measured) | 2.3 KB (measured) | 28 KB (measured) | 106 KB (measured, full bundle) | 11 KB (measured) |
| GitHub stars | New | 29.6k | 39.6k | 22.0k | 40.4k | 13.2k |

"Measured" means we downloaded the script with gzip on 2026-10-24. Sizes depend on the
version and configuration.

## Hosted tools

| | misomoon | Google Analytics 4 | Fathom | Simple Analytics | Cloudflare Web Analytics |
| --- | --- | --- | --- | --- | --- |
| Where your data lives | Your Cloudflare account | Google | Fathom (EU collection, then US) | The Netherlands | Cloudflare |
| Open source | Yes (MIT) | No | No (the old Fathom Lite is MIT and no longer developed) | No (only the tracker scripts) | No |
| Price | Cloudflare's own pricing for Workers, D1, and Queues | Free | From $15/month for 100k pageviews | Free for 5 sites with a 1-month history; from $20/month | Free |
| Cookies | None | `_ga` cookies for 2 years. Google's EU policy requires consent where the law requires it. | None (their claim) | None (their claim) | None |
| Funnels | Yes | Yes | Not found | Multi-step goals on some plans | No |
| Revenue | Yes | Yes | Yes | Not found | No |
| Core Web Vitals | Yes | No built-in report | Not found | Not found | Yes |
| Custom events and UTM | Yes | Yes | Yes | Yes | No |
| Official MCP server | Yes | Yes, "Experimental" | No (community only) | No | A general Cloudflare GraphQL server |
| Data retention | You choose, per site or for the whole server | 2 or 14 months for explorations | While you subscribe | By plan | 6 months, sampled after 7 days |
| Tracker size, gzipped | 998 bytes core, 1.8 KB with the Light preset, 4.8 KB with every feature (measured) | 157 KB (measured, `gtag.js`) | 2.1 KB (measured) | 3.9 KB (measured) | 10 KB (measured) |

## Tracker size, feature for feature

A new misomoon site gets every feature. The **Light** preset under **Settings** >
**Install** > **What to track** keeps what Plausible's script does: pageviews with
single-page app and hash routing, engaged time and scroll depth, custom events with props
and revenue, outbound links, file downloads, form submissions, and tagged events.

| Script | Gzipped |
| --- | --- |
| misomoon, core only | 998 bytes |
| misomoon, Light preset | 1,846 bytes |
| misomoon, every feature | 4,763 bytes |
| Plausible, `script.js` (pageviews only) | 1,280 bytes |
| Plausible, `script.outbound-links.file-downloads.tagged-events.js` | 2,069 bytes |
| Plausible, the per-site `pa-` script on plausible.io | 2,475 bytes |

Measured on 2026-10-24 with Node's `zlib.gzipSync` at its default level, on the files
served by `plausible.io/js/` and on misomoon's build. Plausible's current per-site script
turns outbound links, downloads and form submissions on and off from its dashboard, so it
carries their code on every site ([script extensions](https://plausible.io/docs/script-extensions),
page updated 2026-08-14).

## Data processing agreements

A self-hosted misomoon needs no agreement with the misomoon project: the data stays in
your Cloudflare account, under Cloudflare's DPA. The hosted service at app.misomoon.com
has its own [data processing agreement](dpa.md). Bracketed values in it are drafts.

| | app.misomoon.com | Plausible | Fathom | Simple Analytics | Umami Cloud | Matomo Cloud | PostHog |
| --- | --- | --- | --- | --- | --- | --- | --- |
| How you get it | Part of the terms, nothing to sign | Part of the terms, nothing to sign | Sign the PDF and email it | None; they review yours | Part of the terms, nothing to sign | Accept at sign-up or in the admin | Generate and sign it in the app |
| Breach notice | Within [48] hours | Within 48 hours | Without undue delay | Not stated | Without undue delay | Without undue delay | Without undue delay |
| Notice of a new sub-processor | [30] days, object or leave with a refund | No day count, object and leave | 14 days, leave | Not stated | 15 days, object or leave with a refund | 30 days, object | 14 days, object or leave |
| Audits | Reports first, then once a year | No clause | Third-party audit results | Not stated | Reports first, then once a year | Certificates, documents, and interviews | At your cost |
| Deletion after you leave | [30] days, backups [30] days | Without undue delay, backups 30 days | Within 24 hours | 90 days after cancelling | No day count | 30 days, backups 60 days | On request |
| Transfers outside the EU | Standard contractual clauses | Not in the DPA | Not in the DPA | Not stated | Standard contractual clauses | Adequacy or standard contractual clauses | Standard contractual clauses and the Data Privacy Framework |

Checked on 2026-10-25: Plausible's [DPA](https://plausible.io/dpa) (updated September
2026), Fathom's [DPA](https://usefathom.com/legal/dpa) (2025-06-20), Simple Analytics'
[DPA page](https://www.simpleanalytics.com/data-processing-agreement) and
[terms](https://www.simpleanalytics.com/terms), Umami's [DPA](https://umami.is/dpa)
(2026-08-02), Matomo's [Cloud DPA](https://matomo.org/matomo-cloud-dpa/) (2025-10-09), and
PostHog's [DPA](https://posthog.com/dpa).

## Privacy tools in the product

| | misomoon | Plausible | Fathom | Simple Analytics | Umami Cloud | Matomo | PostHog |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Retention you set per site | Yes, 30 days to 10 years | By plan | Kept while you subscribe | By plan | By plan | Yes | By plan |
| Exclude IP addresses | Yes, IPv4 and IPv6 ranges | Yes | Yes | IPv4 | Pro plan | Yes | Internal users filter |
| Global Privacy Control | Optional, per site | No | No | No | No | No | Read in its code, off by default |
| Do Not Track | Optional, per site | No | Optional | On by default | Optional | Off by default | Off by default |
| Opt-out button for visitors | Yes, in the dashboard | A downloadable opt-out page | A flag set from the console | No | A flag set by the site | An opt-out form and API | An API |
| Privacy policy text for your site | Written from your settings | Guidance only | Yes | Yes | No | Yes, a fill-in paragraph | No |
| Consent banner guidance by country | EU, France, Germany, UK, US | General | EU and UK | Partial | Partial | EU country by country | General |
| Legitimate interest and Article 30 templates | Yes | No | No | No | No | Article 30 help | No |
| Delete your own account | Yes, at once | Yes | Yes | Yes | Yes | After cancelling | Yes |
| Two-factor sign-in | No | Yes | Yes | No | Yes | Yes | Yes |
| Audit log | No | No | No | No | Enterprise plan | Yes | Paid plans |
| SOC 2 or ISO 27001 | No (Cloudflare has both) | No | No | Unclear | No | ISO 27001 | SOC 2 Type 2 |

Checked on 2026-10-25, on each vendor's own pages: Plausible's
[docs](https://plausible.io/docs) (opt-out, 2FA, account deletion; pages updated June to
October 2026) and [security page](https://plausible.io/security) (August 2026); Fathom's
[docs](https://usefathom.com/docs) and [compliance guides](https://usefathom.com/legal/compliance)
(September 2026); Simple Analytics' [docs](https://docs.simpleanalytics.com) and
[security page](https://www.simpleanalytics.com/security); Umami's
[docs](https://docs.umami.is) and [security page](https://umami.is/security) (22 October
2026); Matomo's [FAQ](https://matomo.org/faq/), [consent guide](https://developer.matomo.org/guides/tracking-consent),
and [ISO 27001 announcement](https://matomo.org/blog/2025/09/matomo-iso-27001-certification-2025/)
(24 September 2025); PostHog's [privacy docs](https://posthog.com/docs/privacy),
[activity logs](https://posthog.com/docs/settings/activity-logs), and
[trust center](https://trust.posthog.com). Simple Analytics calls itself SOC 2 certified
on one page and "in progress" on another.

## Sources

Checked on 2026-10-24.

- Google Analytics: [cookie usage](https://support.google.com/analytics/answer/11397207),
  [EU user consent policy](https://www.google.com/about/company/user-consent-policy/),
  [data retention](https://support.google.com/analytics/answer/7667196),
  [MCP server](https://github.com/googleanalytics/google-analytics-mcp)
- Plausible: [self-hosted vs cloud](https://plausible.io/self-hosted-web-analytics),
  [Community Edition](https://github.com/plausible/community-edition),
  [data policy](https://plausible.io/data-policy),
  [Google import](https://plausible.io/docs/google-analytics-import),
  [proxy](https://plausible.io/docs/proxy/introduction),
  [script extensions](https://plausible.io/docs/script-extensions)
- Umami: [install](https://docs.umami.is/docs/install), [pricing](https://umami.is/pricing),
  [Web Vitals](https://docs.umami.is/docs/performance), [MCP](https://docs.umami.is/docs/mcp),
  [import](https://docs.umami.is/docs/cloud/import-data)
- Matomo: [requirements](https://matomo.org/faq/on-premise/matomo-requirements/),
  [cookies](https://matomo.org/faq/general/faq_157/), [funnels](https://matomo.org/docs/funnels/),
  [SEO Web Vitals](https://matomo.org/docs/seo-web-vitals/),
  [MCP plugin](https://plugins.matomo.org/McpServer),
  [Google importer](https://plugins.matomo.org/GoogleAnalyticsImporter)
- PostHog: [self-host](https://posthog.com/docs/self-host),
  [persistence](https://posthog.com/docs/libraries/js/persistence),
  [Web Vitals](https://posthog.com/docs/web-analytics/web-vitals),
  [MCP](https://posthog.com/docs/model-context-protocol),
  [Google migration](https://posthog.com/docs/migrate/google-analytics)
- Rybbit: [self-hosting](https://rybbit.com/docs/self-hosting),
  [self-host vs cloud](https://rybbit.com/docs/self-host-vs-cloud), [MCP](https://rybbit.com/docs/mcp),
  [import](https://rybbit.com/docs/data-import)
- Fathom: [pricing](https://usefathom.com/pricing), [compliance](https://usefathom.com/compliance),
  [data](https://usefathom.com/data), [Fathom Lite](https://github.com/usefathom/fathom)
- Simple Analytics: [pricing](https://simpleanalytics.com/pricing),
  [compliance](https://docs.simpleanalytics.com/compliance)
- Cloudflare Web Analytics: [product page](https://www.cloudflare.com/web-analytics/),
  [FAQ](https://developers.cloudflare.com/web-analytics/faq/),
  [Core Web Vitals](https://developers.cloudflare.com/web-analytics/data-metrics/core-web-vitals/)
- Star counts and licenses: the GitHub API, read on 2026-10-24.

---

# Frequently asked questions

## Privacy

### What does misomoon store about a visitor?

It stores the page, the referrer, UTM tags, the country, region, and city, the browser,
the operating system, the screen size, the language, the network operator, and the events that the page
sends. It doesn't store the IP address.

To count unique visitors, the Worker makes an id from a hash of a daily random salt,
the site, the IP address, and the user agent. It keeps 16 characters of that hash. The
salt changes every day at 00:00 UTC and is deleted after two days. After that, nobody
can link a visitor's id from one day to the next, or work back to the IP address.

### Does the tracker use cookies or local storage?

No. `m.js` sets no cookies and stores nothing on the device. The only exception is the
`misomoon_ignore` key, which you set yourself to [exclude your own visits](tracking.md#exclude-yourself),
or a visitor sets with the [opt-out button](compliance.md#let-visitors-opt-out).

### Do I need a cookie banner?

misomoon sets no cookies, stores nothing on the visitor's device, and never stores IP
addresses, which are the usual reasons for a consent banner. Whether you need one depends
on your country, on the features you turn on, and on what else your site does. Clicks,
JavaScript errors, site search, form fields, and payments collect more than pageviews do;
the [data processing agreement](dpa.md) lists what each one keeps.
[Use misomoon within privacy law](compliance.md#do-you-need-a-consent-banner) goes through
the rules in the EU, France, Germany, the UK, and the US. This isn't legal advice. Ask
someone who knows the law where you operate.

### Where is the data?

Self-hosted, in your own Cloudflare account, in D1 databases that you control. Nobody
else, including the misomoon project, can see it. On app.misomoon.com, in our Cloudflare
account, under the [data processing agreement](dpa.md). To choose where D1 stores the data, see
[D1 data location](https://developers.cloudflare.com/d1/configuration/data-location/).

## Running it

### Is this self-hosted?

misomoon runs in your own Cloudflare account, not on your own hardware. You own the
data, the code, and the deploy, and Cloudflare runs it. You don't maintain a server.
The trade-off is that it needs Cloudflare. There is no Docker version today.

### What does it cost?

misomoon is free. You pay Cloudflare for what the Worker uses. Small sites fit in the
Workers Free plan. Busier sites need the Workers Paid plan. The
[self-hosting guide](self-hosting.md#before-you-start) links the pricing pages.

### How much traffic can it handle?

Each shard is a D1 database of up to 10 GB, and you can add shards as you grow. Reads
run on every shard in parallel and merge the results.
[Scale the shards](upgrading.md#scale-the-shards) explains how.

### Can I keep data for a limited time?

Yes. Set **Keep stats for** in **Settings** > **Install** > **Privacy** for one site, or
`RETENTION_DAYS` for every site on your server. The hourly job deletes events and visits
older than the shorter of the two. By default, everything is kept
([privacy settings](compliance.md#privacy-settings)).

### Can I export my data?

Yes. The dashboard and the API export a ZIP of CSV files for any period
([API reference](api.md#get-apiv1statsexport)). The raw data is also in your D1
databases, so you can query it with `wrangler d1 execute`.

## Numbers

### Why are my numbers lower than in Google Analytics?

Some reasons:

- Ad blockers block Google Analytics too, but they block different things. To lose
  fewer events to blockers, [serve misomoon from your own domain](PROXY.md).
- misomoon drops bots before it counts them.
- Google Analytics fills gaps with modeled data when visitors decline consent. misomoon
  counts only real requests.

### Why is a visitor unique only for one day?

The visitor id changes every day, so misomoon can't know that today's visitor came
yesterday too. A "visitors" number for a month is the sum of the unique visitors of
each day. This is the price of not storing anything on the device.

### Can I import my history from Google Analytics?

Yes. In **Settings**, connect Google and import a property's history, or upload a CSV
export. Imported numbers show in unfiltered reports, next to the data misomoon
collects. The Google import needs the Google OAuth secrets
([configuration](configuration.md#secrets)).

## Features

### Does it work with single-page apps?

Yes. The tracker counts each `pushState` and `popstate` route change as a pageview. For
`#/route` routers, add `data-hash`.

### Can AI tools read my analytics?

Yes. misomoon has an MCP server for Claude, Cursor, and other clients. See
[Ask AI tools about your traffic](mcp.md).

### Can I share a dashboard?

Yes. Create a shared link in **Settings** > **Sharing**. A shared link can have a
password, an expiry date, and a saved filter. You can also make a site public through the
API, so anyone with its dashboard URL can read it. [Share a dashboard](sharing.md) covers
both.

---

# misomoon brand: "Miso Print"

The repo had no existing brand, so this defines it. Tokens live in
`packages/brand/tokens.css`; both apps import them.

**Idea.** A risograph poster, not a glowing SaaS page. Warm newsprint, heavy ink, and
one loud vermilion, with cobalt, leaf, plum and mustard as spot colours. Everything
looks printed: solid ink edges, hard offset shadows (never blurred), halftone dots
instead of gradients. The moon is a halftone disc whose phase follows the light.

## Type

| Role | Face | Notes |
| --- | --- | --- |
| Display | Archivo, 68% width, 800 | Uppercase, tight (`.display` / `.serif`). Emphasis is vermilion, never italic. |
| UI | Archivo, 100% width | 13–15px in the dashboard; numbers tabular, 700 for KPI values. |
| Mono | Martian Mono, 87.5% width | Labels, eyebrows (`[01] COLLECT`), code, receipts, tickers. |

## Colour

- Paper is the default theme (`:root`); Ink is `:root[data-theme='dark']`.
- Spot inks: vermilion `#E8461A` (brand, primary action), cobalt `#2B45E0`,
  leaf `#0E8A55`, plum `#B0389B`, mustard `#F2B416`, paper `#F2ECDF`, ink `#17140F`.
- Text on vermilion (primary buttons, the selected tab or choice) is white,
  `--on-vermilion`, in both themes.
- Highlighter `--highlight` for marked phrases; status good/warn/bad reuse leaf,
  mustard and a red, always with a label or icon.
- Categorical chart order, validated (CVD separation, lightness band, contrast) with
  the dataviz validator:
  - Paper (on `#FBF7EE`): `#E8461A` `#2B45E0` `#0E8A55` `#B0389B` `#B98300`
  - Ink (on `#1C1915`): `#EE5526` `#6077F5` `#1F9C62` `#C952B2` `#B98510`

## Marks

- Logo: "Reflection". A vermilion half moon rises on an ink horizon line, and its
  reflection breaks into rows of dots below, fading with depth: moonlight on water, and a
  dot plot. At 28px and under the mark switches to a compact cut (5, 3, 1 larger dots) so it
  holds as a favicon. The wordmark "misomoon" (Archivo 800) draws the two o's of "moon" as
  a moon rising on the horizon, then full. Files in `packages/brand/` (`mark.svg`,
  `logo.svg`); earlier explorations are in `packages/brand/explorations/`.
- Hero: the same idea at full size. Tonight's real moon phase (computed from the date in
  `apps/landing/src/lib/edition.ts`) rises over the horizon, and the reflection is
  misomoon's own visitors for the last 30 days, one column per day, hoverable.
- Cards: 1.5–2px ink edge, `--shadow` = 3px 3px 0 ink (6px for overlays). Buttons press
  down into their shadow on click.
- Charts: 2–2.5px vermilion line over a halftone dot fill, dashed previous period.
- Landing devices: the page is a daily edition. An edition strip (issue number, date,
  tonight's moon, countdown to the next edition at midnight UTC) and a "yesterday" line
  written from the site's real numbers. Plus a thermal receipt and perforated shard tickets.
  Avoid generic template moves (marquee tickers, spinning stickers, tape bands): every
  decorative element should carry real data or a real fact.

---

# Use misomoon within privacy law

This guide is for site owners who use misomoon. It covers what misomoon collects, the
privacy settings, the text for your privacy policy, an opt-out button, when a consent
banner may still be needed, and templates for the records the GDPR asks you to keep.

This isn't legal advice. The law depends on your country, your visitors' countries, and
the features you turn on. Ask someone who knows the law where you operate.

## What misomoon collects

misomoon sets no cookies, stores nothing on the visitor's device, and never stores IP
addresses. To count unique visitors, it hashes a random salt that changes every day, the
site, the IP address, and the user agent, and keeps 16 characters of the hash. The salt is
deleted after two days, so nobody can link a visitor from one day to the next or work back
to the address ([Architecture](ARCHITECTURE.md#ingest)).

Every pageview carries the page path, the referrer without its query, campaign tags, the
country, region and city, the network operator, the browser, operating system, device
type, screen size class, and language, and the time on page and scroll depth. What more
it collects depends on the features you tick under **Settings** > **Install** > **What to
track**. Annex 1 of the [data processing agreement](dpa.md#annex-1-details-of-the-processing)
lists each feature's data.

Before anything is stored, misomoon removes what tends to identify someone:

- In page paths, segments that look like an email address or a long token become `:email`
  and `:token`.
- In free text, such as error messages and search terms, email addresses, ids, tokens,
  query strings, and runs of six or more digits are replaced.
- Outbound links, downloads, and error sources lose their query string.
- Form fields send which field was used, never what was typed.

You still decide what your own custom events and properties carry. Don't put names, email
addresses, or other details that identify a person in them.

## Privacy settings

**Settings** > **Install** > **Privacy** holds three settings for each site. The API sets
them on [`PATCH /api/v1/sites/:id`](api.md#sites).

| Setting | What it does | API field |
| --- | --- | --- |
| **Keep stats for** | Deletes the site's visits and events once they are older than this. The hourly job deletes them, so they go within an hour or so of the limit. **Keep everything** keeps them until you delete the site. If the server's `RETENTION_DAYS` is shorter, that applies instead ([Configuration](configuration.md)). | `retention_days`: 30 to 3650 days, or `null` |
| **Never count these IP addresses** | Drops every beacon from these addresses or ranges before it is stored or counted, for example your office or your own servers. Up to 50 IPv4 or IPv6 addresses or CIDR ranges. Behind a proxy, misomoon matches the visitor's address that the proxy passes on ([proxy](PROXY.md)). | `exclude_ips` |
| **Respect Global Privacy Control and Do Not Track** | Drops every beacon from a browser that sends `Sec-GPC: 1` or `DNT: 1`. Those visitors don't appear in any report, and a payment they make isn't linked to their visit. The tracker carries no code for it: browsers send both headers with the beacon. A proxy must pass the headers on. | `privacy_signals` |

Older settings help too:

- Fewer features collect less. The **Light** preset collects what most privacy-focused
  tools do ([Choose what to track](tracking.md#choose-what-to-track)).
- **Never count these paths** leaves out pages such as an account area.
- `data-disable` on the script tag turns a feature off on one page, such as checkout.

Deleting a site deletes all of its data at once ([Sites](dashboard.md#sites)), and
deleting your account deletes the teams only you are in
([Delete your account](teams.md#delete-your-account)).

## Add misomoon to your privacy policy

Your privacy policy should say that you use misomoon, what it records, why, for how long,
and how to object. **Settings** > **Install** > **Privacy** > **Text for your privacy
policy** writes that section from the site's saved settings: it lists only the features
you ticked, your retention, whether browser signals are respected, and where the data is
kept. Copy it again after you change a setting.

For a site on app.misomoon.com with the **Light** preset, 13 months of retention, and
browser signals respected, the text reads:

```md
## Analytics

To see how example.com is used, we use misomoon, a privacy-friendly analytics tool. It sets no cookies and stores nothing on your device.

To count unique visitors, misomoon makes an identifier from your IP address and browser with a random value that changes every day, and keeps only that identifier. Your IP address is never stored. The identifier can’t be followed from one day to the next or across sites.

It records:

- the page address, the site that sent you, and campaign tags
- your country, region and city, read from your IP address, and your network operator
- your browser, operating system, device type, screen size and language
- how long a page was open and how far you scrolled
- actions we count, such as a sign-up or a purchase, with the details we attach to them
- links you follow to other sites, without their query string
- files you download, without their query string
- forms you send, by the form’s name, never what you typed
- buttons and links we marked as events

These statistics are counted together; we don’t use them to identify you or to show you ads. misomoon processes these statistics for us under a data processing agreement, on Cloudflare’s network, and stores them in the European Union.

We keep these statistics for 395 days.

We rely on our legitimate interest in understanding and improving our site (Article 6(1)(f) of the GDPR).

If your browser sends Global Privacy Control or Do Not Track, misomoon records nothing. To stop being counted in this browser, use the opt-out button on this page.
```

On your own server, the text says the statistics stay in your Cloudflare account instead.

## Let visitors opt out

Most guidance asks that visitors can object to analytics. **Settings** > **Install** >
**Privacy** > **Opt-out button** gives a snippet for your privacy page:

```html
<button type="button" id="misomoon-opt-out"></button>
<script>
  (function (button) {
    function out() { try { return !!localStorage.misomoon_ignore } catch (e) { return false } }
    function show() { button.textContent = out() ? 'Count my visits again' : 'Stop counting my visits' }
    button.onclick = function () {
      try { out() ? localStorage.removeItem('misomoon_ignore') : localStorage.setItem('misomoon_ignore', 'true') } catch (e) {}
      show()
    }
    show()
  })(document.getElementById('misomoon-opt-out'))
</script>
```

The button sets `misomoon_ignore` in the visitor's browser, the same key you use to
[exclude yourself](tracking.md#exclude-yourself). While it is set, `m.js` sends nothing
and the console says `misomoon skipped: ignored`. A second press removes it. The choice
holds for one browser and one domain: localStorage isn't shared between `example.com` and
`www.example.com`, so put the button on each host the visitor uses. The key is written
only when the visitor asks for it.

## Do you need a consent banner?

misomoon avoids the usual reasons for a banner: cookies, identifiers stored on the device,
and IP addresses kept with the data. Whether that's enough depends on where you are.

- **European Union.** Article 5(3) of the ePrivacy Directive needs consent to store or
  read information on a visitor's device, unless it is strictly necessary. The EDPB's
  [Guidelines 2/2023](https://www.edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-22023-technical-scope-art-53-eprivacy-directive_en)
  (version 2.0, published 16 October 2024) read this broadly, so a script that makes the
  browser send information can fall under it even without cookies. National regulators
  apply it differently.
- **France.** The CNIL lets audience measurement run without consent when it only
  produces anonymous statistics for the site's own use, isn't combined with other data,
  doesn't follow visitors across sites, keeps data for at most 25 months, and visitors are
  told about it ([CNIL, audience measurement](https://www.cnil.fr/fr/cookies-et-autres-traceurs/regles/cookies-solutions-pour-les-outils-de-mesure-daudience),
  dated 4 July 2025). With misomoon, set **Keep stats for** to 25 months or less, mention
  it in your privacy policy, and add the opt-out button. Features beyond audience
  measurement, such as payments, are harder to fit.
- **Germany.** Section 25 of the TDDDG follows Article 5(3) and has no exception for
  analytics. Many German sites ask for consent for any analytics.
- **United Kingdom.** The Data (Use and Access) Act 2025 added an exception to PECR for
  storage and access used only to collect statistics that improve a service, as long as
  visitors get clear information and an easy way to object
  ([ICO, the exceptions](https://ico.org.uk/for-organisations/direct-marketing-and-privacy-and-electronic-communications/guidance-on-the-use-of-storage-and-access-technologies/what-are-the-exceptions/)).
  The privacy policy text and the opt-out button cover both.
- **United States.** Laws such as California's CCPA give visitors the right to opt out of
  the sale or sharing of their data, and Global Privacy Control is a valid opt-out. misomoon
  neither sells nor shares data for advertising. To honour the signal anyway, tick
  **Respect Global Privacy Control and Do Not Track**.

Every feature beyond pageviews adds to what you need to explain. Clicks, JavaScript
errors, site search, form fields, and payments collect the most. The **Light** preset is
the easiest to justify.

## Answer a visitor's request

Under the GDPR, a visitor can ask to see or delete their data. misomoon keeps nothing
that finds one person: no IP address, no cookie, and a visitor id that changes every day.
In most cases you can answer that analytics data can't be linked to them (GDPR
Article 11). If the visitor gives you something that identifies their visits, such as a
payment's id from your payment provider, contact us (on app.misomoon.com) or search the
data yourself (on your own server), and delete what you find.

## Legitimate interest assessment

If you rely on legitimate interest, the GDPR expects you to weigh it against your
visitors' interests and keep a record. Copy this, fill in the brackets, and keep it with
your records.

```md
# Legitimate interest assessment: website analytics

Date: [date]. Reviewed by: [name, role].

## Purpose
We measure how [site] is used (visits, pages, sources, and [features]) to improve its
content and performance.

## Necessity
Aggregate statistics are the least intrusive way to know which pages work. We use
misomoon, which sets no cookies, stores nothing on the device, keeps no IP addresses, and
uses a visitor id that changes daily. We collect only [features].

## Balancing
- Visitors expect a site to count its visits; the data is aggregate and not used to
  identify anyone, for advertising, or combined with other data.
- Risks: [none identified / list].
- Safeguards: no cookies or IP addresses stored; emails, ids, and long numbers removed
  from free text; data kept for [retention]; excluded IP addresses [list or none];
  Global Privacy Control and Do Not Track [respected / not respected]; an opt-out
  button on our privacy page; processed by misomoon under a data processing agreement
  [or: in our own Cloudflare account].

## Outcome
Our interest is not overridden by visitors' interests or rights. We review this when we
change features or every [12] months.
```

## Record of processing

The GDPR asks most organizations to keep a record of processing (Article 30). This is the
entry for misomoon.

| Field | Entry |
| --- | --- |
| Name of the processing | Website analytics on [site] |
| Controller | [your organization and contact] |
| Purpose | Measure and improve how the site is used |
| Legal basis | Legitimate interest, Article 6(1)(f) GDPR [or consent] |
| Data subjects | Visitors to [site] |
| Data | See [What misomoon collects](#what-misomoon-collects), for the features [list] |
| Recipients | misomoon and Cloudflare as processors ([sub-processors](dpa.md#annex-3-sub-processors)) [or: Cloudflare, in our own account] |
| Transfers outside the EEA | [none / standard contractual clauses, per the DPA] |
| Retention | [retention_days] days |
| Security measures | [Annex 2 of the DPA](dpa.md#annex-2-technical-and-organizational-measures) |

## Legal documents for app.misomoon.com

- [Data processing agreement](dpa.md)
- [Privacy policy](privacy.md), for your account and our own sites
- [Terms of service](terms.md)
- [Security](security.md), including how to report a vulnerability

A self-hosted misomoon runs in your own Cloudflare account, so these documents don't
apply. Cloudflare's own terms and data processing agreement do.

---

# Data processing agreement

This data processing agreement (DPA) covers the hosted service at app.misomoon.com. It is
part of the terms of service, and it applies from the day a customer adds a site, without
anything to sign. To get a copy countersigned, email [privacy@misomoon.com](mailto:privacy@misomoon.com).

If you run misomoon in your own Cloudflare account, the misomoon project never sees your
data, and this agreement doesn't apply to you. Cloudflare processes it for you under the
[Cloudflare DPA](https://www.cloudflare.com/cloudflare-customer-dpa/), which is part of
your Cloudflare account. If you host misomoon for clients, you are their processor, and
you can use this agreement as a starting point for your own.

**Draft.** Items in square brackets need filling in, and a lawyer should review the whole
agreement before it is published.

## 1. Parties

- **Customer**: the person or organization that adds a site to app.misomoon.com. The
  Customer is the controller.
- **Provider**: [legal name], [registered address], [registration number]. The Provider
  is the processor.

If the Customer itself processes the data for someone else, such as an agency for its
client, the Customer is the processor and the Provider is its sub-processor, under the
same terms.

For account data (the names and emails of the Customer's users, sign-ins, and billing),
the Provider is the controller, and its privacy policy covers it, not this agreement.

## 2. Terms

Words such as personal data, processing, controller, processor, data subject, and
personal data breach mean what they mean in the General Data Protection Regulation
(EU) 2016/679 (GDPR). "Data protection law" means the GDPR, the UK GDPR, and any other
data protection law that applies to the processing.

"Customer data" means the personal data that the Provider processes for the Customer
through the service: what the tracker, the SDK, the Customer's payment provider, and the
Customer's imports send about the visitors of the Customer's sites.

## 3. What the Provider processes, and on whose instructions

1. The Provider processes Customer data only to provide the service, and only on the
   Customer's documented instructions. The terms of service, this agreement, and the
   Customer's settings in the dashboard (the features the Customer turns on, path rules,
   retention, and connected providers) are those instructions.
2. If the Provider believes an instruction breaks data protection law, it tells the
   Customer and doesn't have to follow it until the Customer confirms or changes it.
3. If a law requires the Provider to process Customer data in another way, the Provider
   tells the Customer first, unless that law forbids it.
4. The Provider doesn't sell Customer data, doesn't use it for its own purposes or to
   train AI models, and doesn't combine it with data from other customers or other
   sources.
5. If a public authority asks the Provider for Customer data, the Provider refers it to
   the Customer, tells the Customer about the request unless the law forbids it, and
   gives only what the law makes it give.
6. Annex 1 lists the subject matter, nature, purpose, and duration of the processing,
   and the types of data and data subjects.

## 4. The Customer's part

The Customer decides which features to turn on and which properties to send, and is
responsible for having a legal basis for the processing, for telling visitors about it
in its privacy notice, and for getting consent where the law where it operates requires
it. The Customer doesn't send names, email addresses, or other direct identifiers in
event names, properties, or page paths, and doesn't send special categories of personal
data (GDPR Article 9), such as health or religion.

## 5. Confidentiality

Only people who need Customer data to run or support the service can access it, and each
of them is bound by a duty of confidentiality.

## 6. Security

The Provider keeps the technical and organizational measures in Annex 2. It may change
them over time, but never so that they protect Customer data less.

## 7. Sub-processors

1. The Customer authorizes the Provider to use the sub-processors in Annex 3.
2. The Provider tells the Customer about a new or replaced sub-processor at least
   [30] days before it starts processing Customer data, by email to the account owner
   and in the change log under Annex 3. Anyone else can ask for these emails at
   [privacy@misomoon.com](mailto:privacy@misomoon.com). The Customer can object in that time on reasonable data protection
   grounds. If the parties can't resolve the objection, the Customer can close its
   account and the Provider refunds any prepaid fees for the time left.
3. The Provider puts each sub-processor under data protection obligations at least as
   protective as this agreement, and stays responsible to the Customer for how each one
   performs them.

## 8. Where the data is, and transfers

1. The Provider stores Customer data in Cloudflare D1 databases created in the EU
   jurisdiction, which Cloudflare runs and stores only in the European Union. Tracker
   requests are answered by the Cloudflare data center nearest the visitor, which may be
   outside the EU.
2. Where Customer data leaves the European Economic Area, the UK, or Switzerland,
   including access by the Provider's staff from [country of the Provider], the transfer
   relies on the European Commission's standard contractual clauses (Decision
   (EU) 2021/914), Module 2 (controller to processor) between the Customer and the
   Provider, and Module 3 (processor to processor) or the EU-US Data Privacy Framework
   between the Provider and its sub-processors. The clauses are part of this agreement by
   reference; for the UK, the UK Addendum applies, and for Switzerland, the clauses with
   the changes the Swiss FDPIC requires. [Choose the governing law and courts for the
   clauses (Clauses 17 and 18).]

## 9. Personal data breaches

The Provider tells the Customer about a personal data breach that affects Customer data
without undue delay, and within [48] hours of becoming aware of it. The notice says what
happened, which data and roughly how many data subjects it affects, the likely effects,
and what the Provider has done and will do about it. The Provider adds what it learns
later as it learns it.

## 10. Helping the Customer

1. **Requests from data subjects.** The service has no personal identifiers to look a
   visitor up by: visitor ids change every day and IP addresses are never stored. Where a
   request can be met, the Provider helps the Customer meet it, and passes on any request
   it receives directly.
2. **Impact assessments and regulators.** The Provider gives the Customer the
   information it reasonably needs for a data protection impact assessment, or to consult
   a supervisory authority.

## 11. Audits

The Provider makes available the information needed to show that it meets this agreement,
including this page, the [security page], and Cloudflare's current SOC 2 report and
ISO 27001 certificate. If that isn't enough, or a regulator asks for it, the Customer may
audit the Provider once a year, with [30] days' notice, during business hours, through an
auditor bound by confidentiality who doesn't work for a competitor, at the Customer's
cost.

## 12. Deletion and return

1. Deleting a site in the dashboard deletes its events, visits, imports, and payment
   records at once, from every database that holds them. Deleting an account deletes
   the teams only that account is in, with their sites, the same way.
2. Before closing its account, the Customer can export its data from the dashboard or the
   Stats API.
3. Within [30] days after the account closes, the Provider deletes all remaining Customer
   data, unless a law requires it to keep some, and confirms the deletion in writing if the
   Customer asks. Backups that Cloudflare keeps to restore D1 databases expire within
   [30] days.

## 13. Liability, term, and order

1. Each party's liability under this agreement is subject to the limits in the terms of
   service, except where data protection law doesn't allow a limit.
2. This agreement lasts as long as the Provider processes Customer data for the Customer.
3. If this agreement and the terms of service conflict, this agreement wins on data
   protection. If the standard contractual clauses conflict with either, the clauses win.
4. This agreement is governed by [governing law], and the courts of [place] decide
   disputes, except where the standard contractual clauses say otherwise.

## Annex 1: Details of the processing

**Subject matter and purpose.** Web and app analytics for the Customer's sites: counting
visits and pageviews, where visitors come from, what they do on the site, and which
visits led to a payment.

**Nature.** Collecting, storing, aggregating, and deleting.

**Duration.** While the Customer has an account, then until deleted under section 12.

**Data subjects.** Visitors of the Customer's sites and apps. Buyers who pay through the
Customer's payment provider, if the Customer connects one.

**Retention.** Events and visits are kept for the period the Customer sets for each site
(**Keep stats for**, 30 days to 10 years), or until the Customer deletes the site if it
sets none[, and never longer than [the server retention period]]. The daily salt behind visitor ids is replaced every
day and deleted after two days. A payment ref is kept for 30 days and a customer link for
400 days, so that a later renewal or refund finds its visit.

**Types of data.** The Provider never stores IP addresses, never sets cookies, and stores
nothing on the visitor's device. Free text is scrubbed before it is stored: emails, ids,
tokens, links' query strings, and long numbers are removed.

| Collected | Always, or with which feature | Data |
| --- | --- | --- |
| Pageviews and visits | Always | Page path (emails and tokens in it masked), referrer without its query, UTM tags, country, region, city, continent, timezone, network operator (ASN organization), browser, operating system, device type, screen size class, language, and a visitor id: a hash of a daily salt, the site, the IP address, and the user agent, which can't be followed from one day to the next |
| Engagement | Always | Time the page was in view and had focus, and how far it was scrolled |
| Custom events | Always | Event names, properties, and revenue amounts that the Customer's site sends |
| Outbound links, downloads, form submits, tagged events | Each its own feature | The link's address without its query string, the form's id or name, and the tagged element's properties |
| Web Vitals | Web Vitals | Loading and responsiveness timings |
| Clicks | Clicks | Where on the page an element was clicked, and the visible text of links and buttons, or the label the site gave an element. Never other text on the page |
| JavaScript errors | JavaScript errors | Error messages, scrubbed, and the script's address without its query |
| Form fields | Form fields | Which fields of a form were used and where a visit stopped. Never what was typed |
| Video and audio | Video and audio | The media's name and how far it played |
| Content blocks | Content blocks | Which elements the site marked were seen and clicked |
| Site search | Site search | The search term from the page address, scrubbed |
| Payments | Payments, and a connected payment provider | A random ref per page view, the provider's checkout, payment, subscription, and customer ids, amounts, currencies, and the visit each payment came from. Never names, emails, or card details |

## Annex 2: Technical and organizational measures

- **Encryption.** All traffic uses HTTPS. Cloudflare encrypts D1 databases at rest with
  AES-256 and protects traffic inside its network with TLS.
- **Less data.** No IP addresses, cookies, or device storage. Visitor ids come from a
  salt that is replaced daily and deleted after two days. Free text is scrubbed of
  emails, ids, tokens, query strings, and long numbers before it is stored. Path rules
  let the Customer leave pages out completely, and the Customer can drop visits from
  chosen IP addresses and from browsers that send Global Privacy Control or Do Not
  Track. Cloudflare's per-request invocation logs are turned off, and the service's own
  logs hold no IP addresses.
- **Access.** Dashboard roles (owner, admin, editor, viewer) and per-site guests decide
  who sees what. Passwords are hashed with PBKDF2-SHA256 and a per-user salt; session
  tokens and API keys are stored only as hashes. Sign-in and the Stats API are
  rate-limited.
- **Separation.** Every row is stored and queried by site id; a request can only read
  the sites its user or key may read.
- **Integrity.** Payment webhooks are accepted only with a valid signature from the
  provider.
- **Staff.** [Who at the Provider can reach production data, how access is granted and
  removed, and how it is logged.]
- **Incidents.** [How the Provider detects and handles incidents, and who is on call.]
- **Resilience.** D1 keeps point-in-time recovery for [30] days; the ingest queue retries
  failed writes.

## Annex 3: Sub-processors

| Sub-processor | What it does | Where |
| --- | --- | --- |
| Cloudflare, Inc. | Runs the service: Workers, D1 databases, Queues, email, and the browser that prints report PDFs | Databases in the EU; requests served at the data center nearest the visitor |
| [Amazon Web Services EMEA SARL, if email goes through Amazon SES] | Sends report, alert, invitation, and password-reset emails to the Customer's users. Visitor data is never in them beyond the totals in a report | [EU region] |

Google receives nothing from the service unless the Customer connects Search Console or
imports a Google Analytics property, and then only the requests for the Customer's own
Google data. Payment providers send webhooks to the service on the Customer's behalf and
are the Customer's own processors.

### Changes to the sub-processors

- [date]: first list.

Last updated [date].

---

# Privacy policy

This policy covers the personal data that [legal name] ("we") keeps as the controller:
your account on app.misomoon.com, and visits to misomoon.com and its docs. It doesn't
cover the visitors of the sites our customers measure. For that data, each customer is
the controller and we are its processor, under the
[data processing agreement](dpa.md).

A self-hosted misomoon sends nothing to us. This policy doesn't apply to it.

**Draft.** Items in square brackets need filling in, and a lawyer should review the
policy before it is published.

## Who we are

[Legal name], [registered address], [registration number]. For anything about your data,
email [privacy@misomoon.com](mailto:privacy@misomoon.com).

## What we keep, and why

| Data | Why | Legal basis | How long |
| --- | --- | --- | --- |
| Your email address, name, and a PBKDF2 hash of your password | To run your account | Contract (GDPR Article 6(1)(b)) | Until you delete your account |
| Your teams, roles, guest access, sites, and settings | To run the service | Contract | Until you delete them or your account |
| Sign-in sessions and API keys, stored only as hashes, with when a key was last used | To keep you signed in and let your tools read your stats | Contract | Sessions 30 days; keys until you revoke them |
| Invitations: the invited email address, the role, and who invited | To add someone to a team | Legitimate interest of the team that invites (6(1)(f)) | Until accepted or withdrawn; the link works for 7 days |
| Password reset links, stored as hashes | To let you back in | Contract | One hour |
| Email addresses that receive reports and alerts | To send them | Contract | Until the report is removed |
| Tokens for Google Search Console or Google Analytics, and payment provider webhook secrets, when you connect them | To import your own data | Contract | Until you disconnect, or delete the site |
| Your IP address, when you sign in, sign up, or reset a password | To slow down password guessing | Legitimate interest in security | Not stored: it is a key for a one-minute rate limit |
| Emails you send us | To answer you | Legitimate interest | [retention] |
| [Billing details: name, address, VAT number, invoices] | [To bill you] | [Contract and legal obligation (6(1)(c))] | [As tax law requires] |

We don't sell your data, use it for advertising, or use it to train AI models.

## Our own sites

misomoon.com counts its own visits with misomoon, without cookies and without storing IP
addresses ([how misomoon counts](compliance.md#what-misomoon-collects)). Our basis is our
legitimate interest in knowing which pages help. To opt out, use your browser's Global
Privacy Control or Do Not Track setting, or the opt-out button on this page:
[opt-out button].

The dashboard keeps your session token, your theme, and the tabs you last picked in your
browser's local storage. They are needed for the dashboard to work, and signing out
removes the token. We set no cookies.

## Who receives it

| Who | What for | Where |
| --- | --- | --- |
| Cloudflare, Inc. | Hosting, databases, and email | Databases in the EU; requests at the data center nearest you |
| [Amazon Web Services EMEA SARL] | [Email, if we send it through Amazon SES] | [EU region] |
| Google | Only when you connect Search Console or Google Analytics, to fetch your own data | Google's servers |
| [Payment processor] | [Billing] | [Where] |

Where data leaves the European Economic Area, the transfer relies on the European
Commission's standard contractual clauses or an adequacy decision.

## Your rights

You can see, correct, export, and delete your data, object to processing based on
legitimate interest, and complain to your data protection authority.

- Change your name or password in **Settings** > **Account**.
- Export your stats from the dashboard or the [API](api.md#get-apiv1statsexport).
- Delete your account in **Settings** > **Account** > **Delete account…**. It deletes
  your account at once, with the teams only you are in and their data
  ([Delete your account](teams.md#delete-your-account)). Backups that could still hold
  it expire within [30] days.
- For anything else, email [privacy@misomoon.com](mailto:privacy@misomoon.com). We answer within one month.

## Security

[Security](security.md) describes how we protect data and how to report a vulnerability.

## Changes

We date every change here, and email account owners [30] days before a change that
affects their rights.

- [date]: first version.

---

# Terms of service

These terms cover the hosted service at app.misomoon.com. The misomoon software is open
source under the MIT license, and running it yourself is governed by that license and by
your agreement with Cloudflare, not by these terms.

**Draft.** Items in square brackets need filling in, and a lawyer should review the terms
before they are published.

## 1. Who we are

[Legal name], [registered address], [registration number] ("we"). Contact:
[support@misomoon.com](mailto:support@misomoon.com).

## 2. Your account

You need to be at least 16, and old enough to make a contract where you live. Keep your
password and API keys safe; you are responsible for what is done with them. A team's
owners are responsible for the people they invite.

## 3. Your data

Your sites' statistics belong to you. We process them only to run the service, under the
[data processing agreement](dpa.md), which is part of these terms. You can export them at
any time. [Privacy policy](privacy.md) covers your account data.

## 4. What you may not do

- Track people without the notice or consent the law where you operate requires.
- Send names, email addresses, or other details that identify a person in events,
  properties, or page paths, or special categories of data such as health or religion.
- Measure a site you have no right to measure.
- Break, overload, or probe the service, other than under the
  [vulnerability disclosure policy](security.md#report-a-vulnerability).
- Use the service for anything unlawful.

We may stop accepting data for a site that breaks these rules, and tell you why.

## 5. Plans and payment

[Plans, prices, billing period, taxes, and what happens when you go over a plan's limit.
Prices may change with [30] days' notice; a change applies from your next billing
period.]

## 6. Availability and changes

We work to keep the service running, but don't promise it is never down. Status:
[status page]. We may change or remove features; we tell you [30] days before removing
one you pay for.

## 7. Ending

You can delete your account at any time in **Settings** > **Account**. We may end the
service for you with [30] days' notice, or at once if you seriously break these terms.
After the account ends, we delete your data as the
[data processing agreement](dpa.md#12-deletion-and-return) says.

## 8. Liability

The service is provided as it is. As far as the law allows, neither party is liable for
indirect or consequential loss, and each party's total liability is limited to the fees
you paid in the 12 months before the claim. Nothing limits liability that the law doesn't
allow to be limited, such as for fraud or for death or injury caused by negligence.

## 9. Changes to these terms

We date every change here, and email account owners [30] days before a change takes
effect. If you don't agree, you can delete your account before then.

- [date]: first version.

## 10. Law

These terms are governed by [governing law], and the courts of [place] decide disputes.
If you are a consumer, you keep the protection of the law where you live.

---

# Security

This page describes how misomoon protects data, on app.misomoon.com and in the software you
can run yourself, and how to report a vulnerability.

## How data is protected

- **Less data to lose.** No cookies, no IP addresses, and a visitor id that changes
  every day. Email addresses, ids, tokens, and long numbers are removed from free text
  before it is stored ([what misomoon collects](compliance.md#what-misomoon-collects)).
  Cloudflare's per-request invocation logs are off; the Worker's own logs never hold an IP
  address.
- **Encryption.** Every request uses HTTPS. Cloudflare encrypts D1 databases at rest with
  AES-256 and protects traffic inside its network with TLS
  ([D1 data security](https://developers.cloudflare.com/d1/reference/data-security/)).
- **Accounts.** Passwords are hashed with PBKDF2-SHA256 (100,000 iterations, a random salt
  per user). Session tokens, API keys, invitation links, and reset links are stored only
  as SHA-256 hashes. Sign-in, sign-up, password resets, shared-link passwords, and the
  Stats API are rate-limited.
- **Access.** Team roles and per-site guests decide who sees what
  ([roles](teams.md#what-each-role-can-do)). Every query is scoped to the sites the user or
  key may read. An API key can be limited to one site.
- **Webhooks.** Payment webhooks are accepted only with a valid signature from the
  provider.
- **Deletion.** Deleting a site removes its data from every database at once; deleting an
  account removes the teams only it is in ([Delete your account](teams.md#delete-your-account)).
- **The code is open.** Anyone can read how data is collected and stored, in this
  repository.

## Certifications

misomoon itself holds no SOC 2 report or ISO 27001 certificate. It runs entirely on
Cloudflare, which holds both for the products misomoon uses
([Cloudflare compliance](https://www.cloudflare.com/trust-hub/compliance-resources/)).

Two-factor sign-in, single sign-on, and an audit log aren't available yet.

## Report a vulnerability

Email [security@misomoon.com](mailto:security@misomoon.com). Don't open a public issue.
The same address is in `/.well-known/security.txt` on misomoon.com.

- We confirm we received the report within [3] working days, and keep you posted until
  it is fixed.
- In scope: the misomoon code in this repository, and app.misomoon.com.
- Out of scope: denial of service, spam, social engineering, and findings in Cloudflare
  itself (report those to Cloudflare).
- Test only with accounts and sites you own, and don't read or change other people's
  data. If you follow this policy, we won't take legal action against you for your
  research.
- There is no paid bug bounty. We credit reporters in the release notes, if they want.

## Incidents on app.misomoon.com

If a personal data breach affects a customer's data, we tell the customer within the time
the [data processing agreement](dpa.md#9-personal-data-breaches) gives.