# Privatus Analytics documentation
> Privacy-first, cookieless web analytics. This file contains every page
> of https://privatusanalytics.com/docs as Markdown. The generated API reference is at
> https://privatusanalytics.com/docs/api and the OpenAPI document at https://privatusanalytics.com/openapi.json.
---
Source: https://privatusanalytics.com/docs/getting-started
# Get started with Privatus Analytics
> Set up cookieless web analytics in about five minutes: create an account, add a site, install the tracker, verify it works and see your first visitors.
Privatus Analytics is cookieless web analytics. The tracker is one small
script with no cookies, no local storage and no fingerprinting, so in most
setups you don't need a consent banner for it. This section takes you from
sign-up to your first goal.
## The five-minute version
1. [Create an account](/docs/getting-started/create-account). The Free plan
needs no card and includes 10,000 events a month.
2. [Add a site](/docs/getting-started/add-a-site): its domain and
timezone.
3. Paste the snippet into the `` of every page:
```html
```
Your site id (`pa_…`) is under **Site settings → Tracking**. It isn't a
secret: it's visible in your page source, like the domain.
4. [Verify the installation](/docs/getting-started/verify-installation). The
check fetches your page, looks for the script and warns about headers
that block it.
5. [Create your first goal](/docs/getting-started/first-goal) and
[invite your team](/docs/getting-started/invite-your-team).
Using a CMS, site builder or framework? Pick your platform in the
[install guides](/docs/install).
## What you get straight away
- **Visitors, visits, pageviews, bounce rate and visit duration** on the
[Overview](/docs/dashboard/overview).
- **Sources and channels**, including a separate channel for
[AI assistants](/docs/metrics/channels) such as ChatGPT and Perplexity.
- **Pages, entry and exit pages, locations, devices, browsers** and
**UTM campaigns**.
- **Time on page and scroll depth** from the `engage` module, which is on
by default.
- **Real-time** visitors on the [Live](/docs/dashboard/live) page.
Add [custom events](/docs/events), [goals](/docs/features/goals) and
[funnels](/docs/features/funnels) when you're ready.
## How it stays private
- No cookies, `localStorage`, `sessionStorage` or IndexedDB. The only
exception is a flag a visitor sets themselves when they
[opt out](/docs/privacy/opt-out).
- The visitor's IP address and User-Agent are used in memory to work out
the country, the device and a daily visit key, and are then dropped. They
are never written to disk or logs.
- Every visitor, including visitors from the EU, UK and Switzerland, is
processed in our US region. Only the minimized event is stored.
Read [how it works](/docs/privacy) for the full picture, and
[how visitors are counted](/docs/metrics/how-visitors-are-counted) for the
details of visits and visitors.
---
Source: https://privatusanalytics.com/docs/getting-started/create-account
# Create a Privatus Analytics account
> Sign up for Privatus Analytics with Google, GitHub or just your email (no password needed) and create a workspace for your sites and team.
## Sign up
Go to **Sign up** on the website and pick one of three options:
- **Sign up with Google** or **Sign up with GitHub**: we use the verified
email address of that account.
- **Send me a login link**: enter your email and open the link we send
you. It works once, for 15 minutes. Opening it creates your account and
signs you in. Nothing is created until you open it, so a mistyped
address leaves no account behind.
The same "Email me a login link" option on the login page also creates an
account for an email that doesn't have one yet. You can add a password, a
passkey or two-factor authentication later under **Account settings →
Security** (see [Two-factor authentication](/docs/teams/two-factor)).
Continuing with any option confirms you are 18 or older and accepts the
Terms of Service, which include our Data Processing Agreement (DPA), and
the Privacy Policy. You don't need to sign anything else to use Privatus Analytics
with personal data under the GDPR. See [Privacy & compliance](/docs/privacy).
## Your email is already verified
Google, GitHub and the email link all prove that you own the address, so
there is no separate confirmation email.
## Create a workspace
A **workspace** holds your sites, members, billing and API tokens. Most
people need one. Agencies often create one per client, or one workspace
with per-site access for each client (see [Teams](/docs/teams)).
Choose:
- **Name**: shown in the workspace switcher and in emails.
- **Default timezone**: new sites start with it. Each site can have its own.
- **Default currency**: used to total [revenue](/docs/events/revenue).
## Next
[Add your first site](/docs/getting-started/add-a-site).
---
Source: https://privatusanalytics.com/docs/getting-started/add-a-site
# Add a website to Privatus Analytics
> Add a website to Privatus Analytics: set its domain, extra domains, timezone and currency, and find the site id for the tracking snippet.
A **site** is one website you measure. Each site has its own settings,
goals, sharing and data, and a public id like `pa_7Q2K9XH3AB` that goes in
the tracking snippet.
## Fields
| Field | What it does |
|---|---|
| Domain | The main hostname, e.g. `example.com`. Hits from other hostnames are dropped unless you add them as extra domains. Subdomains (`www.`, `shop.`) of a listed domain are accepted. |
| Name | A display name. Defaults to the domain. |
| Timezone | Where "today" starts and ends in reports. Stored data is UTC. The timezone is applied when you query, so you can change it later. |
| Currency | The currency revenue is converted to. |
## Several domains
Under **Site settings → General** you can add extra domains, for example a
separate checkout domain or a docs site. Choose whether they're **combined**
(one visit can cross them) or **separate** (the hostname is part of the
visit key, so the same visitor on two domains is two visits). The
[cross-domain troubleshooting page](/docs/troubleshooting/cross-domain)
explains the trade-offs.
## Plan limits
The Free plan includes 10 sites. Paid plans have no site limit. All sites
share the workspace's monthly event allowance.
## Next
[Install the tracker](/docs/install) on your site, then
[verify the installation](/docs/getting-started/verify-installation).
---
Source: https://privatusanalytics.com/docs/getting-started/verify-installation
# Verify your analytics installation
> Check that the Privatus Analytics tracker is installed and hits are arriving, with the automatic check, the Live page or your browser's network tab.
## Automatic check
Open **Site settings → Tracking** and click **Verify installation**. We
fetch your homepage (or a URL you enter on the same domain) and report:
- whether a `
```
- Replace `pa_YOURSITEID` with your site id from **Site settings →
Tracking**. The snippet generator on that page builds the tag for you,
including any options you switch on.
- `defer` loads the script without blocking your page. The core script is
a few kilobytes and sets no cookies.
- Add options as `data-` attributes. The most common:
| You want to… | Add |
|---|---|
| Track outbound links, downloads, forms and 404s automatically | `data-modules="engage,auto"` |
| Measure Web Vitals | `data-modules="engage,vitals"` |
| Track a hash-routed single-page app | `data-spa="hash"` |
| Send pageviews yourself | `data-manual="true"` |
| Skip admin pages | `data-exclude="/admin/*"` |
The full list is in the [attribute reference](/docs/tracker/attributes).
> **Warning:** Setting `data-modules` replaces the default list. The
> `engage` module (time on page and scroll depth) is on only when you leave
> `data-modules` out or include `engage` in it.
## Choose your platform
**Websites and site builders:** [HTML](/docs/install/html) ·
[WordPress](/docs/install/wordpress) · [Shopify](/docs/install/shopify) ·
[Webflow](/docs/install/webflow) · [Squarespace](/docs/install/squarespace) ·
[Wix](/docs/install/wix) · [Framer](/docs/install/framer) ·
[Ghost](/docs/install/ghost)
**Tag managers:** [Google Tag Manager](/docs/install/google-tag-manager) ·
[Cloudflare Zaraz](/docs/install/cloudflare-zaraz)
**Frameworks:** [Next.js](/docs/install/nextjs) · [Nuxt](/docs/install/nuxt) ·
[React](/docs/install/react) · [Vue](/docs/install/vue) ·
[SvelteKit](/docs/install/sveltekit) · [Astro](/docs/install/astro) ·
[Remix](/docs/install/remix) · [Angular](/docs/install/angular)
**Static site generators:** [Hugo](/docs/install/hugo) ·
[Jekyll](/docs/install/jekyll) · [Eleventy](/docs/install/eleventy) ·
[Docusaurus](/docs/install/docusaurus)
**Other:** [AMP](/docs/install/amp) · [No-JavaScript pixel](/docs/install/pixel) ·
[Electron and browser extensions](/docs/install/electron-and-extensions) ·
[Server-side](/docs/server-side)
## After installing
[Verify the installation](/docs/getting-started/verify-installation). If
nothing arrives, work through [No data](/docs/troubleshooting/no-data).
---
Source: https://privatusanalytics.com/docs/install/html
# Add the analytics script to an HTML site
> Add privacy-friendly analytics to a hand-written or server-rendered HTML site with one script tag, turn on engagement and auto events, and track custom events.
Paste the snippet just before `` on every page. With a shared
layout or header template you only need to do this once.
```html
My site
…
```
## Recommended options
```html
```
- `engage` measures time on page and scroll depth.
- `auto` tracks outbound links, file downloads, `mailto:`/`tel:` links,
form submissions and 404 pages as events. See [Modules](/docs/tracker/modules).
## Track events in your own code
Add the [queue stub](/docs/tracker/javascript-api#queue-stub) before the
tracker if you call the API early (for example in inline scripts that run
before `pa.js` has loaded):
```html
```
Then anywhere on the page:
```js
privatus.track('Newsletter signup', { list: 'weekly' })
```
Or with no JavaScript at all:
```html
Subscribe
```
## No JavaScript?
Add the [pixel](/docs/install/pixel) inside a `` tag to count
visitors with JavaScript disabled.
---
Source: https://privatusanalytics.com/docs/install/wordpress
# Install Privatus Analytics on WordPress
> Install the Privatus Analytics WordPress plugin or add the snippet to your theme, exclude admins, track WooCommerce purchases and add an opt-out shortcode.
## With the plugin (recommended)
1. In WordPress go to **Plugins → Add New** and search for
**Privatus Analytics**. If it isn't listed in the plugin directory yet,
[contact us](/contact) for the plugin zip and upload it under
**Plugins → Add New → Upload Plugin**, or upload the
`privatus-analytics` folder to `/wp-content/plugins/`.
2. Activate it.
3. Go to **Settings → Privatus Analytics** and paste your site id (`pa_…`).
The plugin adds the tracker to every page and exposes every tracker option
(SPA mode, modules, excluded paths, masks, extra query parameters,
canonical URLs, hash routing).
It also:
- **excludes logged-in users by role** (administrators by default), so your
own visits don't count,
- tracks **WooCommerce purchases** as a `purchase` event with revenue,
currency, the number of items and whether a coupon was used. It never
sends order ids, names, emails or addresses, and masks order-specific
URLs,
- offers a **server-side purchase mode** that sends the purchase from your
server with a secret [ingest key](/docs/server-side/ingest-keys). Put the
key in `wp-config.php` to keep it out of the database:
```php
define( 'PRIVATUS_INGEST_KEY', 'pik_…' );
```
- adds a `[privatus_optout]` shortcode for your privacy page (see
[Opt-out](/docs/privacy/opt-out)),
- suggests privacy policy text under **Settings → Privacy**,
- shows your [shared dashboard](/docs/reports/sharing) in a dashboard
widget.
### Filters for developers
| Filter | Type | Use |
|---|---|---|
| `privatus_analytics_should_track` | bool | Return `false` to skip tracking on a request |
| `privatus_analytics_script_attributes` | array | Change the attributes of the script tag |
```php
add_filter( 'privatus_analytics_script_attributes', function ( $attrs ) {
$attrs['data-modules'] = 'engage,auto,vitals';
return $attrs;
} );
```
## Without the plugin
Add the snippet to your theme's `header.php` before ``, or with a
"header and footer scripts" plugin. In a child theme's `functions.php`:
```php
add_action( 'wp_head', function () {
if ( current_user_can( 'manage_options' ) ) {
return; // don't count administrators
}
echo '';
} );
```
> **Warning:** Caching and optimization plugins (WP Rocket, Autoptimize,
> LiteSpeed Cache…) sometimes combine or delay scripts. Exclude `pa.js`
> from "combine", "defer JS" and "delay JS" features. See
> [Caching plugins](/docs/troubleshooting/caching).
---
Source: https://privatusanalytics.com/docs/install/shopify
# Install Privatus Analytics on Shopify
> Add cookieless analytics to your Shopify store with the app embed or theme code, then track checkout purchases and revenue with a Shopify custom pixel.
## Storefront
1. Install the **Privatus Analytics** app. If it isn't listed in the
Shopify App Store yet, use the steps under [Without the app](#without-the-app).
2. Go to **Online Store → Themes → Customize → App embeds** and switch on
**Privatus Analytics**.
3. Enter your site id (`pa_…`) and choose modules. Engagement is on by
default. Auto events, Web Vitals and click maps are optional.
4. Save.
The embed prints the tracker in the theme's `` and masks
customer-specific order pages (`/account/orders/*`). It isn't loaded in the
theme editor, so editing your theme doesn't add visits.
### Without the app
Edit your theme (**Online Store → Themes → … → Edit code**), open
`layout/theme.liquid` and add the snippet before ``:
```liquid
```
## Checkout and purchases
Shopify's checkout doesn't run theme scripts. Use a **custom pixel** under
**Settings → Customer events → Add custom pixel**:
```js
// Privatus Analytics: purchases (runs in Shopify's sandbox)
const SITE = 'pa_YOURSITEID'
const ENDPOINT = 'https://privatusanalytics.com/api/event'
function send(body) {
fetch(ENDPOINT, {
method: 'POST', keepalive: true, credentials: 'omit',
headers: { 'Content-Type': 'text/plain' },
body: JSON.stringify(Object.assign({ s: SITE }, body))
})
}
analytics.subscribe('checkout_completed', (event) => {
const checkout = event.data.checkout
send({
t: 'event', n: 'purchase', u: event.context.document.location.href,
p: {
revenue: Number(checkout.totalPrice.amount),
currency: checkout.totalPrice.currencyCode,
items: checkout.lineItems.length
}
})
})
```
Set **Permission** to "Not required" only if your legal assessment allows
it. Privatus Analytics sets no cookies and stores nothing on the device. Never add
order ids, emails or names as properties.
Your storefront domain (`shop.example.com`) and your `myshopify.com`
domain may both appear. Add both as [extra domains](/docs/getting-started/add-a-site#several-domains)
if you want hits from both.
---
Source: https://privatusanalytics.com/docs/install/webflow
# Add Privatus Analytics to Webflow
> Add privacy-friendly analytics to Webflow through site-wide custom code, handle your webflow.io staging domain and track events with custom attributes.
1. Open your project and go to **Site settings → Custom code**.
2. Paste the snippet into **Head code**:
```html
```
3. Save and **Publish**. Custom code only runs on the published site, not
in the Designer.
## Staging domain
Your `*.webflow.io` staging domain isn't one of your site's domains, so its
hits are dropped. That's usually what you want. To measure it, add it as an
extra domain, or restrict tracking to production explicitly with
`data-domains="example.com,www.example.com"`.
## Events without code
Webflow lets you add custom attributes to any element (**Element settings →
Custom attributes**). Add:
| Name | Value |
|---|---|
| `data-privatus-event` | `Demo request` |
| `data-privatus-prop-plan` | `business` |
On a form block, the event fires when the form is submitted. See
[HTML attributes](/docs/events/html-attributes).
---
Source: https://privatusanalytics.com/docs/install/squarespace
# Add Privatus Analytics to Squarespace
> Add cookieless analytics to Squarespace with header code injection, and track purchases with revenue from the Order Status Page without sending order details.
Code injection needs a Squarespace plan that includes it (Core and above
on current plans).
1. Go to **Settings → Advanced → Code Injection** (or **Website → Pages →
Custom code → Code injection**).
2. Paste the snippet into **Header**:
```html
```
3. Save.
Squarespace 7.1 loads pages with full navigations, so the default settings
work. If you use AJAX page loading on a 7.0 template, the tracker still
follows `history.pushState` navigations (`data-spa="auto"`).
## Order confirmation
Under **Code Injection → Order Status Page**, Squarespace can run a script
after a purchase. The tracker from the header is already on that page, so
you only need the event:
```html
```
Replace the variable with the one your plan's order page offers, and never
send order numbers or customer details.
---
Source: https://privatusanalytics.com/docs/install/wix
# Add Privatus Analytics to Wix
> Add privacy-friendly analytics to a Wix site as custom code in the head, count page navigations once and set the code type to Essential for your consent banner.
Custom code requires a premium Wix plan with a connected domain.
1. In the dashboard go to **Settings → Custom code → Add custom code**.
2. Paste the snippet:
```html
```
3. Name it "Privatus Analytics", choose **All pages**, **Load code once**,
and place it in the **Head**.
4. Apply.
Wix sites navigate between pages without full reloads. The tracker follows
those navigations with its default `data-spa="auto"`, so each page counts
once.
Under **Code type**, choose **Essential** if your Wix consent banner is on:
Privatus Analytics sets no cookies and doesn't need to wait for consent. Confirm this
with your own legal assessment.
---
Source: https://privatusanalytics.com/docs/install/framer
# Add Privatus Analytics to Framer
> Add cookieless analytics to a Framer site through custom code, track single-page navigation automatically and count clicks with a data-privatus-event attribute.
1. Open your project and go to **Site settings → General → Custom code**.
2. Paste the snippet into **End of `` tag**:
```html
```
3. **Publish**.
Framer sites are single-page apps: page changes use `history.pushState`,
which the tracker follows automatically.
Your `*.framer.app` preview domain isn't one of your site's domains, so its
hits are dropped unless you add it.
## Events
Add a custom attribute in Framer (**Link → Custom attributes**, or through
a code override) named `data-privatus-event` to track clicks without code.
---
Source: https://privatusanalytics.com/docs/install/ghost
# Add Privatus Analytics to Ghost
> Add privacy-friendly analytics to a Ghost site through code injection, and count member and newsletter signups as an event without sending email addresses.
1. In Ghost Admin go to **Settings → Code injection**.
2. Paste the snippet into **Site header**:
```html
```
3. Save.
## Members and newsletter signups
Ghost's signup forms use `data-members-form`. To count signups as an event,
add this after the snippet:
```html
```
Never send the email address as a property. The
[PII scrubber](/docs/privacy/pii-scrubbing) would redact it anyway.
---
Source: https://privatusanalytics.com/docs/install/google-tag-manager
# Install Privatus Analytics with Google Tag Manager
> Load the Privatus Analytics tracker from a Google Tag Manager Custom HTML tag, set consent settings, send events from GTM triggers and avoid double counting.
If your site already loads tags through Google Tag Manager, you can load
Privatus Analytics from it. Adding the snippet directly to your pages is still more
reliable: GTM itself is blocked by many ad blockers.
## Custom HTML tag
1. In your container go to **Tags → New → Tag configuration → Custom HTML**.
2. Paste:
```html
```
3. Trigger: **Initialization - All Pages** (or **All Pages**).
4. Save, preview, and **Submit** to publish.
GTM copies the `data-` attributes onto the script it inserts, so every
[attribute](/docs/tracker/attributes) works as usual.
## Consent settings
Privatus Analytics sets no cookies and reads nothing from the device, so in GTM's
**Consent settings** for the tag you can choose **No additional consent
required** if that matches your legal assessment. See
[Privacy & compliance](/docs/privacy).
## Sending events from GTM
Create more Custom HTML tags that call the JavaScript API, fired by your
GTM triggers:
```html
```
`{{Form ID}}` here is a GTM variable. Only send values that contain no
personal data.
## Single-page apps
Don't fire the tag again on "History change" triggers. The tracker already
follows `history.pushState` navigations, so firing it twice double counts. See
[SPA double counting](/docs/troubleshooting/spa-double-counting).
---
Source: https://privatusanalytics.com/docs/install/cloudflare-zaraz
# Load Privatus Analytics with Cloudflare Zaraz
> Load the Privatus Analytics tracker through Cloudflare Zaraz with a Custom HTML tool, handle Zaraz single-page app support and send events from your site.
Zaraz loads third-party tools from Cloudflare's edge. Use a **Custom HTML**
tool to load the Privatus Analytics tracker.
1. In the Cloudflare dashboard open your zone and go to **Zaraz → Tools
configuration → Add new tool → Custom HTML**.
2. Name it "Privatus Analytics" and paste:
```html
```
3. Firing trigger: **Pageview**.
4. Save and publish.
Zaraz's "HTML" tools inject the script into the page, so it runs in the
visitor's browser like the normal snippet and supports every attribute.
Single-page app setting: if **Single Page Application support** is on in
Zaraz, it re-fires Pageview triggers on route changes. The tracker already
tracks those itself and ignores a second pageview for the same path, but
you should still use the tracker's SPA handling only: exclude the tool from
SPA re-triggering or keep Zaraz's SPA support off.
## Events
Call the JavaScript API from other Zaraz tools or from your site with
`privatus.track(…)`. Zaraz's own `zaraz.track()` doesn't forward to
Privatus Analytics.
---
Source: https://privatusanalytics.com/docs/install/nextjs
# Add Privatus Analytics to Next.js
> Add cookieless analytics to Next.js with @privatus/next or next/script, for the App or Pages Router, with server-side events.
## With `@privatus/next` (recommended)
> **Warning:** `@privatus/next` is not published on npm yet. Until it is,
> don't install a package with this name from the public registry,
> because anyone could have published it. Use the setup under
> [Without the package](#without-the-package) instead.
```sh
npm install @privatus/next
```
### 1. Add the component
App Router, in `app/layout.tsx`:
```tsx
import { PrivatusAnalytics } from '@privatus/next'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
privatus.track('Upgrade', { plan: 'pro' })}>Upgrade
}
```
`trackAsync(name, props, timeout)` returns a promise that resolves when the
hit is sent (or after the timeout), which is handy before a redirect.
## Server-side events
Track from route handlers, server actions or middleware with a secret
[ingest key](/docs/server-side/ingest-keys) in `PRIVATUS_INGEST_KEY`:
```ts
// app/api/signup/route.ts
import { trackEvent } from '@privatus/next/server'
export async function POST(request: Request) {
// … create the account …
await trackEvent(request, { name: 'Signup', props: { plan: 'pro' } })
return Response.json({ ok: true })
}
```
The helper forwards the visitor's IP and User-Agent from the request in the
body (used in memory only, never stored) and works in the Edge and Node.js
runtimes.
## Without the package
Use `next/script` in the root layout:
```tsx
import Script from 'next/script'
```
Next.js client navigations use `history.pushState`, which the tracker
follows with its default `data-spa="auto"`.
---
Source: https://privatusanalytics.com/docs/install/nuxt
# Add Privatus Analytics to Nuxt
> Add privacy-friendly analytics to a Nuxt app with the @privatus/nuxt module or a head script in nuxt.config, with route changes tracked automatically.
## With `@privatus/nuxt`
> **Warning:** `@privatus/nuxt` is not published on npm yet. Until it is,
> don't install a package with this name from the public registry,
> because anyone could have published it. Use the setup under
> [Without the package](#without-the-package) instead.
```sh
npm install @privatus/nuxt
```
```ts
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@privatus/nuxt'],
privatus: {
site: 'pa_YOURSITEID',
modules: ['engage', 'auto'],
},
})
```
The module server-renders the tracker into `` and auto-imports
`usePrivatus()`:
```vue
Download
```
## Without the package
```ts
// nuxt.config.ts
export default defineNuxtConfig({
app: {
head: {
script: [
{ src: 'https://privatusanalytics.com/js/pa.js', defer: true, 'data-site': 'pa_YOURSITEID' },
],
},
},
})
```
Vue Router uses `history.pushState`, so route changes are tracked
automatically.
---
Source: https://privatusanalytics.com/docs/install/react
# Add Privatus Analytics to a React app
> Add cookieless analytics to a React single-page app built with Vite or Create React App, using the index.html snippet or the typed @privatus/tracker client.
## Simplest: the snippet in `index.html`
For Vite or Create React App, add the snippet to `index.html`:
```html
```
React Router (and most routers) navigate with `history.pushState`, which the
tracker follows automatically. With a hash router (`#/page`), add
`data-spa="hash"`.
## With `@privatus/tracker`
> **Warning:** `@privatus/tracker` is not published on npm yet. Until it is,
> don't install a package with this name from the public registry,
> because anyone could have published it. Use the snippet in
> `index.html` above instead.
The typed loader works with any framework:
```sh
npm install @privatus/tracker
```
```tsx
// main.tsx
import { init } from '@privatus/tracker'
init({ site: 'pa_YOURSITEID', modules: ['engage', 'auto'] })
```
```tsx
import { getClient } from '@privatus/tracker'
const privatus = getClient()
export function SignupButton() {
return privatus.track('Signup click')}>Sign up
}
```
`init()` installs the [queue stub](/docs/tracker/javascript-api#queue-stub)
and injects `pa.js` once. Every function is a no-op during server-side
rendering. The client also offers `trackAsync()`, `isLoaded()`, `props()`,
`optOut()`, `optIn()` and `isOptedOut()`.
For Next.js, use the [Next.js guide](/docs/install/nextjs). For Remix, use the
[Remix guide](/docs/install/remix).
---
Source: https://privatusanalytics.com/docs/install/vue
# Add Privatus Analytics to a Vue app
> Add privacy-friendly analytics to a Vue 3 app with a snippet in index.html, track Vue Router history or hash navigation and send custom events from components.
Add the snippet to `index.html`:
```html
```
Vue Router's `createWebHistory()` uses `history.pushState`, which the
tracker follows automatically. With `createWebHashHistory()`, add
`data-spa="hash"` so hash changes count as pageviews.
## Events
```vue
```
Or use the typed client from `@privatus/tracker` (`init()` and
`getClient()`), as shown in the [React guide](/docs/install/react). For
Nuxt, see the [Nuxt guide](/docs/install/nuxt).
> **Warning:** `@privatus/tracker` is not published on npm yet. Until it is,
> don't install a package with this name from the public registry,
> because anyone could have published it. Use the snippet above
> instead.
---
Source: https://privatusanalytics.com/docs/install/sveltekit
# Add Privatus Analytics to SvelteKit
> Add cookieless analytics to a SvelteKit app in src/app.html, track client-side navigation automatically and send client and server-side events from actions.
Add the snippet to `src/app.html`, inside `` before `%sveltekit.head%`:
```html
%sveltekit.body%
```
SvelteKit's client-side navigation uses `history.pushState`, which the
tracker follows automatically. Preloading data on hover doesn't send
pageviews.
## Events
```svelte
Subscribe
```
## Server-side events
In `+page.server.js` actions or `+server.js` endpoints, use the
[server-side ingest API](/docs/server-side) with your secret ingest key.
Forward the visitor's User-Agent and IP (`event.getClientAddress()`).
---
Source: https://privatusanalytics.com/docs/install/astro
# Add Privatus Analytics to Astro
> Add privacy-friendly analytics to an Astro site with the @privatus/astro integration or an is:inline script in your layout, with view transitions supported.
## With `@privatus/astro`
> **Warning:** `@privatus/astro` is not published on npm yet. Until it is,
> don't install a package with this name from the public registry,
> because anyone could have published it. Use the setup under
> [Without the package](#without-the-package) instead.
```sh
npm install @privatus/astro
```
```js
// astro.config.mjs
import { defineConfig } from 'astro/config'
import privatus from '@privatus/astro'
export default defineConfig({
integrations: [privatus({ site: 'pa_YOURSITEID' })],
})
```
The integration adds a tiny loader to every page's `` that installs
the queue stub and injects `pa.js` once. It works with static and SSR
output and with view transitions.
## Without the package
Add the snippet to your base layout's ``:
```astro
---
// src/layouts/Base.astro
---
): void } }
}
@Injectable({ providedIn: 'root' })
export class PrivatusService {
track(name: string, props: Record = {}) {
window.privatus?.track(name, props)
}
}
```
With server-side rendering (Angular Universal / SSR), the snippet in
`index.html` still only runs in the browser, and the service's optional
call is a no-op on the server.
---
Source: https://privatusanalytics.com/docs/install/hugo
# Add Privatus Analytics to Hugo
> Add cookieless analytics to a Hugo site with a head partial that loads the tracker only in production builds, and keep your site id in the Hugo config.
Create (or edit) a partial your theme includes in ``, for example
`layouts/partials/extend_head.html` or `layouts/partials/head.html`:
```go-html-template
{{ if hugo.IsProduction }}
{{ end }}
```
`hugo.IsProduction` is true for `hugo` builds and false for `hugo server`,
so local previews aren't counted.
Keep the site id in your config instead:
```toml
# hugo.toml
[params]
privatusSite = "pa_YOURSITEID"
```
```go-html-template
{{ with site.Params.privatusSite }}
{{ end }}
```
---
Source: https://privatusanalytics.com/docs/install/jekyll
# Add Privatus Analytics to Jekyll
> Add cookieless analytics to a Jekyll site in your head include, load it only in production builds and keep the site id in _config.yml, on GitHub Pages too.
Add this to `_includes/head.html` (or your default layout's ``):
```liquid
{% if jekyll.environment == "production" %}
{% endif %}
```
And the site id to `_config.yml`:
```yaml
privatus_site: pa_YOURSITEID
```
Build with `JEKYLL_ENV=production bundle exec jekyll build`. GitHub Pages
sets the production environment for you.
With the Minima theme, override `_includes/custom-head.html` instead of
copying the whole head include.
---
Source: https://privatusanalytics.com/docs/install/eleventy
# Add Privatus Analytics to Eleventy (11ty)
> Add cookieless analytics to an Eleventy (11ty) base layout, with a global data file so the tracker loads in production builds but not in eleventy --serve.
In your base layout, e.g. `_includes/base.njk`:
```njk
{{ title }}
{% if env.production %}
{% endif %}
```
Expose `env.production` with a global data file:
```js
// _data/env.js
export default { production: process.env.ELEVENTY_RUN_MODE === 'build' }
```
`eleventy --serve` then leaves the tracker out, and production builds
include it.
---
Source: https://privatusanalytics.com/docs/install/docusaurus
# Add Privatus Analytics to Docusaurus
> Add privacy-friendly analytics to a Docusaurus docs site with the scripts config in docusaurus.config.js, and track docs feedback as custom events.
Add the script in `docusaurus.config.js`:
```js
export default {
// …
scripts: [
{
src: 'https://privatusanalytics.com/js/pa.js',
defer: true,
'data-site': 'pa_YOURSITEID',
},
],
}
```
Docusaurus is a single-page app after the first load. The tracker follows
its `history.pushState` navigations automatically.
## Track searches and feedback
Docs sites often want to know what people search for and whether a page
helped. Track those as events (never the raw text of free-form input if it
could contain personal data):
```js
window.privatus?.track('Docs feedback', { helpful: true })
```
---
Source: https://privatusanalytics.com/docs/install/amp
# Track AMP pages with Privatus Analytics
> Count pageviews on AMP pages with amp-analytics and the Privatus Analytics pixel endpoint, keep the referrer and report pages under your own domain.
AMP pages can't run custom JavaScript, so the tracker doesn't load there.
Use `amp-analytics` to call the [pixel endpoint](/docs/install/pixel)
instead.
Add the component script in ``:
```html
```
And this in ``:
```html
```
- `u=${canonicalUrl}` reports the page under your own domain, so AMP cache
domains (`cdn.ampproject.org`) don't matter.
- `r=${documentReferrer}` keeps the traffic source.
AMP pageviews use the no-JavaScript collection path, so there's no time on
page, scroll depth or events (see
[pixel limitations](/docs/install/pixel#limitations)).
---
Source: https://privatusanalytics.com/docs/install/pixel
# No-JavaScript tracking pixel
> Count pageviews without JavaScript using a 1×1 tracking pixel, with its parameters for page URL and referrer and its limits: pageviews only, no events.
`GET /api/pixel` records a pageview and returns a transparent 1×1 GIF.
```html
```
## Parameters
| Parameter | Required | Meaning |
|---|---|---|
| `s` | Yes | Site id (`pa_…`) |
| `u` | No | Full page URL. Defaults to the request's `Referer` header, which is why the example sets `referrerpolicy` so the browser sends the full URL |
| `r` | No | The page's own referrer (where the visitor came from). URL-encode it |
If your pages are rendered on the server, fill `u` and `r` in yourself:
```erb
```
Query parameters in `u` are minimized exactly like tracker hits: only UTM
parameters, `ref`, and your allowlisted parameters are kept.
## Limitations
- **Pageviews only.** No events, time on page or scroll depth.
- **Bots and proxies.** Image requests from email clients' image proxies and
from data centers are filtered as bots. Don't use the pixel to measure
email opens.
- Visits from the pixel and the JavaScript tracker are counted separately
only if both run. Inside `` they never do.
---
Source: https://privatusanalytics.com/docs/install/electron-and-extensions
# Analytics for Electron apps and browser extensions
> Count screens and events in Electron apps and browser extensions by posting to the collection endpoint with virtual URLs, without creating an identifier.
Apps and extensions don't have normal `https://` page URLs, so the browser
snippet isn't the right fit. Send hits to the public collection endpoint
yourself, using **virtual URLs on your site's domain**.
## The collection endpoint
`POST https://privatusanalytics.com/api/event` with a `text/plain` body (no CORS
preflight, no credentials):
```js
function privatusHit(type, path, extra = {}) {
return fetch('https://privatusanalytics.com/api/event', {
method: 'POST',
keepalive: true,
credentials: 'omit',
headers: { 'Content-Type': 'text/plain' },
body: JSON.stringify({
s: 'pa_YOURSITEID',
t: type, // 'pageview' or 'event'
u: 'https://app.example.com' + path, // a hostname that's one of your site's domains
l: navigator.language,
w: screen.width,
...extra, // n: event name, p: properties
}),
})
}
privatusHit('pageview', '/settings')
privatusHit('event', '/settings', { n: 'Theme changed', p: { theme: 'dark' } })
```
The short keys are documented in [What the tracker sends](/docs/tracker/payload).
## Electron
- Send hits from the renderer (so the request carries a normal browser
User-Agent), for example on each route change of your app's router.
- Electron's default User-Agent contains `Electron/…`, which our bot
filter treats as automation. Set a clean User-Agent for your window's
session, for example with `session.defaultSession.setUserAgent()`
removing the `Electron/x.y.z` token, or hits will be filtered as bots.
- Add `app.example.com` (or whatever host you use in `u`) to the site's
domains.
## Browser extensions
- Send hits from the extension's pages (popup, options page) or background
service worker. Add `https://privatusanalytics.com/*` to `host_permissions` in
`manifest.json` for Manifest V3.
- Describe the analytics in your store listing and privacy disclosures.
Chrome Web Store and Firefox Add-ons require it even for anonymous usage
data.
- Consider an in-extension opt-out that simply stops calling
`privatusHit()`.
## Privacy notes
Nothing here creates an identifier: visits are built exactly as for
websites (a daily key from the IP and User-Agent, which is never
stored). Don't put user ids, emails or file names in paths or
properties.
---
Source: https://privatusanalytics.com/docs/tracker
# Cookieless tracker reference (pa.js)
> How the cookieless pa.js tracker works and when it sends nothing, with links to every script attribute, the JavaScript API, modules, SPA support and debugging.
`pa.js` is the browser tracker. It's open source (MIT), a few kilobytes,
and it:
- sends **one small request per pageview or event** to
`https://privatusanalytics.com/api/event`, and
[retries it](/docs/tracker/payload#retries) a few times if the server
answers with an error,
- uses **no cookies, `localStorage`, `sessionStorage`, IndexedDB or
fingerprinting APIs** (canvas, WebGL, fonts, audio, battery). The one
exception is the [opt-out flag](/docs/tracker/opt-out) a visitor sets
themselves,
- makes **no request to any third party**.
```html
```
## Reference
- [Script attributes](/docs/tracker/attributes): every `data-` option.
- [JavaScript API](/docs/tracker/javascript-api): `track`, `pageview`,
`props`, `optOut`, `ready` and the queue stub.
- [Modules](/docs/tracker/modules): `engage`, `auto`, `vitals`, `clicks`.
- [Single-page apps](/docs/tracker/spa) and [manual mode](/docs/tracker/manual-mode).
- [Exclusions, masking and URLs](/docs/tracker/exclusions-and-masking):
domains, excluded paths, masks, query parameters, canonical URLs, hash
routing.
- [Debug mode](/docs/tracker/debug), [CSP](/docs/tracker/csp),
[versioning and SRI](/docs/tracker/versioning-and-sri),
[opt-out](/docs/tracker/opt-out).
- [What the tracker sends](/docs/tracker/payload): the exact request
body.
## When the tracker sends nothing
The tracker stays silent (and says why in the console with
`data-debug="true"`) when:
| Reason | Details |
|---|---|
| `missing data-site` | The script tag has no `data-site` |
| `opted out` | The visitor [opted out](/docs/tracker/opt-out) in this browser |
| `localhost` | The page is on `localhost`, `127.*`, `[::1]`, `0.0.0.0`, a `.local` host or `file://`, and neither `data-debug` nor `data-allow-local` is set |
| `domain not in data-domains` | You set `data-domains` and this hostname isn't in it |
| `automated browser` | `navigator.webdriver` is set, or PhantomJS, Nightmare or Cypress is detected |
| excluded path | The path matches `data-exclude` |
It also waits for a prerendered page to become visible before sending
anything (`prerenderingchange`), and sends a fresh pageview when a page is
restored from the back/forward cache.
## Open source
The tracker source, tests and build are public. Every file starts with a
comment naming Privatus Analytics: we don't disguise the script or offer
ways to hide it from blockers. See
[Ad blockers](/docs/troubleshooting/ad-blockers).
---
Source: https://privatusanalytics.com/docs/tracker/attributes
# Tracker script attributes reference
> Every data- attribute the pa.js tracker reads from its script tag, with defaults and examples for modules, SPA mode, domains, exclusions and masks.
Attributes are read once, from the `
```
A hash-routed app that adds the plan to every hit:
```html
```
## Not an attribute: Do Not Track and GPC
The tracker always reports whether the browser sends Do Not Track or
Global Privacy Control. Whether those hits are dropped is a site setting
(**Site settings → Privacy**): GPC is honoured by default, DNT is not. See
[DNT and GPC](/docs/privacy/dnt-gpc).
---
Source: https://privatusanalytics.com/docs/tracker/javascript-api
# Tracker JavaScript API reference
> Tracker JavaScript API reference: track custom events, send pageviews, add properties to every hit, opt out, use ready() and queue calls before pa.js loads.
Once loaded, the tracker exposes `window.privatus` (or the name in
[`data-namespace`](/docs/tracker/attributes)).
## `privatus.track(name, props?, callback?)`
Sends a custom event.
```js
privatus.track('Signup', { plan: 'pro', seats: 3 })
privatus.track('Purchase', { revenue: 49.99, currency: 'EUR', sku: 'A1' })
```
- `name`: up to 120 characters, any language. Trimmed and Unicode
normalised (NFC). Case is kept.
- `props`: up to 30 properties of type string (≤ 500 characters), number,
boolean or array of strings. `revenue` and `currency` are reserved. See
[Properties](/docs/events/properties) and [Revenue](/docs/events/revenue).
- `callback`: called once the request has completed, or straight away if
nothing is sent (opted out, excluded, debug mode). It's called after the
first attempt and never waits for a
[retry](/docs/tracker/payload#retries). The tracker adds no timeout of
its own, so add one when you navigate away:
```js
link.addEventListener('click', (e) => {
e.preventDefault()
let done = false
const go = () => { if (!done) { done = true; location.href = link.href } }
privatus.track('Outbound click', { domain: link.hostname }, go)
setTimeout(go, 300)
})
```
Requests are sent with `keepalive`, so in most cases you don't need to
wait at all: the hit survives the navigation.
You can pass the callback as the second argument when there are no
properties: `privatus.track('Logout', done)`.
## `privatus.pageview(options?)`
Sends a pageview for the **current URL**, even if the path hasn't changed.
```js
privatus.pageview()
privatus.pageview({ props: { variant: 'b' } })
```
- `options.props`: properties for this pageview only.
- The URL is always `location.href` (after exclusions, masks, canonical and
hash handling). To record a different path, change the URL first with
`history.pushState`, or use a [mask](/docs/tracker/exclusions-and-masking).
Use it with [manual mode](/docs/tracker/manual-mode) or for virtual
pageviews such as steps of a wizard that change the URL.
## `privatus.props(object)`
Adds properties to every later pageview and event on this page load.
Calls merge. Set a key to `null` to stop sending it.
```js
privatus.props({ theme: 'dark', logged_in: true })
```
Properties live in memory only and are gone on the next full page load.
## `privatus.optOut()`, `privatus.optIn()`, `privatus.isOptedOut()`
Stop or resume tracking in this browser. See [Opt-out](/docs/tracker/opt-out).
## `privatus.ready(fn)`
Runs `fn` once the tracker has loaded. Most useful with the queue stub,
where the call is queued until `pa.js` arrives.
```js
privatus.ready(() => console.log('Privatus Analytics is loaded'))
```
## Queue stub
`pa.js` loads with `defer`, so it isn't available to inline scripts that
run earlier. Put this stub **before** the tracker tag. Calls made before
the tracker loads are queued and replayed in order.
```html
```
The queue format is `window..q = [[method, [args…]], …]`.
`isOptedOut()` returns a value, so it can't be queued. Call it after
`ready()`.
If you use a custom `data-namespace`, use the same name in the stub.
## TypeScript
The npm package `@privatus/tracker` ships types and a loader (`init()`,
`getClient()`) that installs the stub for you. See the
[React guide](/docs/install/react).
> **Warning:** `@privatus/tracker` is not published on npm yet. Until it is,
> don't install a package with this name from the public registry,
> because anyone could have published it. Use the type declarations
> below instead.
```ts
declare global {
interface Window {
privatus?: {
track(name: string, props?: Record, callback?: () => void): void
pageview(options?: { props?: Record }): void
props(props: Record): void
optOut(): void
optIn(): void
isOptedOut(): boolean
ready(fn: () => void): void
}
}
}
```
---
Source: https://privatusanalytics.com/docs/tracker/modules
# Optional tracker modules
> Load optional tracker modules for time on page and scroll depth, automatic outbound link, download, form and 404 events, Web Vitals and aggregate click maps.
Modules are small separate files the tracker loads on demand, from the same
origin as the tracker (or [`data-api`](/docs/tracker/attributes)). Choose
them with `data-modules`:
```html
```
| Module | Default | What it adds |
|---|---|---|
| `engage` | On | Time on page (visible time only) and scroll depth |
| `auto` | Off | Outbound links, file downloads, `mailto:`/`tel:` links, form submits and 404s as events |
| `vitals` | Off | Web Vitals: LCP, INP, CLS, FCP, TTFB |
| `clicks` | Off | Aggregate click counts per element for click maps |
> **Warning:** `data-modules` replaces the default. `data-modules="auto"`
> turns `engage` off. Write `data-modules="engage,auto"` to keep both.
## `engage`: time on page and scroll depth
Built into `pa.js` (no extra file). It measures:
- **Engaged time**: only while the tab is visible. Switching tabs or
minimizing pauses the clock.
- **Scroll depth**: the deepest point reached, as a percentage of the
scrollable height, stored in 10% bands.
It sends an `engagement` hit when the page is hidden or closed, and before
the next SPA pageview, if at least one second of visible time has passed.
Engagement hits aren't pageviews or events: they don't count toward your
[usage](/docs/billing/usage).
Without `engage`, time on page, visit duration and the "under 10 seconds"
part of [bounce rate](/docs/metrics) can't be measured.
## `auto`: automatic events
Loads `pa.auto.js` and tracks these events:
| Event name | When | Properties |
|---|---|---|
| `Outbound Link` | A click on a link to another host | `domain` (without `www.`), `url` (origin and path, no query) |
| `File Download` | A click on a link to a file (pdf, zip, dmg, exe, csv, xlsx, docx, pptx, mp3, mp4, iso, json, svg and more) | `file` (file name), `host` |
| `Email Link` | A click on a `mailto:` link | `to_domain` (the part after `@`, never the address) |
| `Phone Link` | A click on a `tel:` link | none (the number isn't sent) |
| `Form Submit` | Any form is submitted | `form`: the form's `id`, `name` or `action` |
| `404` | The page's `` contains "404" or "not found", or the page has `<meta name="privatus-404">` | `path` |
Elements with a [`data-privatus-event`](/docs/events/html-attributes)
attribute are skipped by `auto`, so you never count one click twice.
For a reliable 404 event on pages whose title doesn't say "not found",
add the meta tag to your 404 template:
```html
<meta name="privatus-404" content="true">
```
Create [goals](/docs/features/goals) of type *Outbound click* or *File
download* to turn these into conversions.
## `vitals`: Web Vitals
Loads `pa.vitals.js`, which uses `PerformanceObserver` to measure:
| Metric | Unit |
|---|---|
| `LCP` Largest Contentful Paint | milliseconds |
| `INP` Interaction to Next Paint (the slowest interaction) | milliseconds |
| `CLS` Cumulative Layout Shift | unitless, 3 decimals |
| `FCP` First Contentful Paint | milliseconds |
| `TTFB` Time to First Byte | milliseconds |
Values are sent once, when the page is first hidden. Web Vitals hits are
**sampled** on the server at the site's sample rate (**Site settings →
Tracking**, where the Free plan allows up to 10%) and **never count toward
usage**. Results are on the [Performance](/docs/features/performance) page.
## `clicks`: click maps
Loads `pa.clicks.js`, which counts clicks per element for aggregate
[click maps](/docs/features/click-maps). For each click it sends a short CSS
selector (up to 4 levels, e.g. `nav.main > a#pricing`) of the nearest link,
button, input, label, `summary`, `[role=button]` or element with
`data-privatus-click`. Ids and classes with three or more digits in a row
(usually generated) are left out.
It never sends mouse movement, coordinates, the text of the element or
anything typed. Clicks are throttled to one per 300 ms.
Click hits don't count toward your usage.
---
Source: https://privatusanalytics.com/docs/tracker/spa
# Track single-page apps (SPAs)
> How the tracker follows single-page app navigation with the History API or hash routing, what counts as a new page, and how to avoid counting pageviews twice.
Most single-page apps (React Router, Next.js, Vue Router, SvelteKit,
Angular, Astro view transitions…) change pages with `history.pushState`.
The tracker handles them with no configuration.
## Modes (`data-spa`)
| Value | Behavior |
|---|---|
| `auto` (default) | Wraps `history.pushState` and listens to `popstate` (back/forward). Each navigation to a new path sends a pageview |
| `history` | Same as `auto` |
| `hash` | Listens to `hashchange` and keeps the `#fragment` in the path (`/#/settings`). For routers that use `#/` URLs |
| `off` | Only the initial page load is tracked. Use the [JavaScript API](/docs/tracker/javascript-api) for the rest |
With `auto`, fragment changes aren't pageviews, and `history.replaceState`
isn't tracked (routers use it for things like updating query strings).
## What counts as a new page
A pageview is sent when the **path** changes: the pathname, plus the
fragment in hash mode. Changing only the query string (`?tab=2`) doesn't
send one, and neither does navigating to the same path again. Call
`privatus.pageview()` to force one.
For each SPA navigation:
1. The engagement time and scroll depth of the page you're leaving are
sent (with the `engage` module).
2. The referrer of the new pageview is a URL on your own site, so internal
navigation never shows up as a new traffic source. The visit keeps the
source it started with.
## Double counting
If you also call `privatus.pageview()` in your router's navigation hook,
or fire the tracker again from a tag manager on history changes, each
navigation is counted twice. Pick one: the built-in SPA tracking, or
[manual mode](/docs/tracker/manual-mode) with `data-spa="off"`. See
[SPA double counting](/docs/troubleshooting/spa-double-counting).
---
Source: https://privatusanalytics.com/docs/tracker/manual-mode
# Send pageviews manually (manual mode)
> Turn off the automatic pageview with data-manual and send pageviews yourself with privatus.pageview(), for example after reading an A/B test variant at runtime.
Add `data-manual="true"` to stop the automatic pageview when the page
loads:
```html
<script defer src="https://privatusanalytics.com/js/pa.js" data-site="pa_YOURSITEID" data-manual="true"></script>
```
Then send pageviews when you decide:
```js
privatus.ready(() => {
if (!document.body.classList.contains('preview')) {
privatus.pageview({ props: { logged_in: isLoggedIn } })
}
})
```
Manual mode only turns off the **first** automatic pageview. SPA
navigation tracking still runs. Add `data-spa="off"` too if you want full
control:
```html
<script defer src="https://privatusanalytics.com/js/pa.js" data-site="pa_YOURSITEID"
data-manual="true" data-spa="off"></script>
```
## When to use it
- You want to add properties to the first pageview that aren't known until
later (for example, after reading an A/B test variant).
- Some pages shouldn't count based on runtime logic (previews, staff
sessions).
- Your router needs pageviews at a moment the History API doesn't reflect
(after data loads, or on modal "pages" that change the URL with
`replaceState`).
`privatus.pageview()` always records the current `location.href`, so
update the URL before calling it.
---
Source: https://privatusanalytics.com/docs/tracker/exclusions-and-masking
# Exclude pages and mask URLs in the tracker
> Exclude pages and mask URLs in the browser: control which hostnames and paths are tracked and which URL is recorded, including query parameters.
Everything on this page happens **in the browser**, before anything is
sent. The server applies its own rules afterwards (site domains,
[traffic rules](/docs/privacy/traffic-rules), path masks, the query
parameter allowlist and the [PII scrubber](/docs/privacy/pii-scrubbing)).
## Only some hostnames: `data-domains`
```html
data-domains="example.com,www.example.com"
```
Nothing is sent on any other hostname: staging servers, preview
deployments, translation proxies, copies of your site. The match is exact, so
list each hostname you use.
The server also drops hits whose hostname isn't one of the site's domains
(or a subdomain of one), so `data-domains` is mostly useful when your
staging hosts are subdomains of your main domain.
## Skip paths: `data-exclude`
```html
data-exclude="/admin/*,/preview/*,/account/*"
```
Comma-separated globs matched against the path (no query string). `*`
matches any characters, including `/`, so `/admin/*` excludes everything
under `/admin/`. `/admin` itself needs its own entry.
Excluded pages send nothing at all: no pageview, no events.
## Rewrite paths: `data-mask`
Group URLs that contain ids into one page, and keep ids out of your data:
```html
data-mask="/users/*/settings->/users/:id/settings,/orders/*->/orders/:id"
```
Each rule is `glob->replacement`. The first matching rule replaces the
whole path. `*` matches any characters.
Prefer **server-side path masking** (Site settings → Privacy) when you
can: it applies to every collection method (tracker, pixel, server-side
API), and its `*` matches exactly one path segment. Client-side masks are
useful when the id itself must never leave the browser.
## Keep query parameters: `data-params`
By default the tracker keeps only campaign parameters (`utm_*`, `ref`,
`via`, `source`) and click ids, and drops everything else before sending.
```html
data-params="page,category"
```
keeps `page` and `category` too. The server stores a query parameter only
if it's also on the site's **query parameter allowlist** (Site settings →
Privacy), so add it there as well. Parameters are then part of the page
path in reports: `/search?category=shoes`.
## Canonical URLs: `data-canonical`
```html
data-canonical="true"
```
Reports the `href` of `<link rel="canonical">` instead of the address bar
URL. Useful when the same content lives under several URLs (tracking
parameters, print views, pagination). Campaign parameters from the address
bar are lost when the canonical URL doesn't carry them.
## Hash routing: `data-hash`
```html
data-hash="true"
```
Keeps the `#fragment` in the path (`/#/settings`). `data-spa="hash"`
turns this on and also tracks `hashchange` navigations. Without it, the
fragment is always dropped.
---
Source: https://privatusanalytics.com/docs/tracker/debug
# Tracker debug mode
> Use tracker debug mode to log every hit to the console without sending it, send real hits from localhost, and check the /api/event request in your dev tools.
```html
<script defer src="https://privatusanalytics.com/js/pa.js" data-site="pa_YOURSITEID" data-debug="true"></script>
```
With `data-debug="true"` the tracker:
- **logs every hit** to the browser console as `[privatus] pageview {…}`,
with the exact request body,
- **doesn't send anything**, so debugging never pollutes your data,
- runs on `localhost` and `file://`,
- logs why a hit wasn't sent (`[privatus] not sent: opted out`, `…:
domain not in data-domains`, and so on).
## Sending from a local server
To send real hits while developing (for example, to test goals end to end
on a development site), use `data-allow-local="true"` instead. The site's
domains must include the hostname you use, e.g. `localhost`, or the server
drops the hits. Most people create a separate "development" site for this.
## Checking the network request
In the browser's developer tools, **Network** tab, filter for `event`.
Each hit is a `POST` to `/api/event` answered with **202 Accepted**. See
[What the tracker sends](/docs/tracker/payload) for the body.
---
Source: https://privatusanalytics.com/docs/tracker/csp
# Content Security Policy for the tracker
> The Content Security Policy directives the analytics tracker needs (script-src, connect-src and img-src), plus the setup for nonces.
If your site sends a `Content-Security-Policy` header, allow the tracker's
script and its requests:
```http
Content-Security-Policy: script-src 'self' https://privatusanalytics.com; connect-src 'self' https://privatusanalytics.com
```
| Directive | Why |
|---|---|
| `script-src https://privatusanalytics.com` | Loads `pa.js` and any [modules](/docs/tracker/modules) (`pa.auto.js`, `pa.vitals.js`, `pa.clicks.js`) |
| `connect-src https://privatusanalytics.com` | Sends hits with `fetch`/`sendBeacon` to `/api/event` |
| `img-src https://privatusanalytics.com` | Only for the [no-JavaScript pixel](/docs/install/pixel) |
Add these to your existing directives and keep everything else you already
allow.
## The queue stub and nonces
The [queue stub](/docs/tracker/javascript-api#queue-stub) is an inline
script. With a strict CSP, give it your page's nonce
(`<script nonce="…">`) or move it into a file you serve.
## Symptoms of a CSP block
In the console: *Refused to load the script…* (missing `script-src`) or
*Refused to connect to…* (missing `connect-src`). The **Verify
installation** check on Site settings → Tracking reads your CSP header and
tells you which directive is missing. See
[CSP errors](/docs/troubleshooting/csp).
---
Source: https://privatusanalytics.com/docs/tracker/versioning-and-sri
# Tracker versioning and Subresource Integrity
> How the hosted pa.js tracker is updated, and how to self-host a pinned copy with a Subresource Integrity (SRI) hash when your security policy requires it.
## One stable URL
`https://privatusanalytics.com/js/pa.js` always serves the current tracker. Updates
are backwards compatible: attributes, the JavaScript API and the request
format don't change in breaking ways under the same URL. Tracker releases
are listed in the changelog and appear as automatic
[notes](/docs/dashboard/notes) on your charts, so you can see when a
change could affect your numbers.
## Subresource Integrity (SRI)
SRI pins a script to an exact hash. Because `pa.js` is updated in place,
an `integrity` attribute on the hosted URL would break the tracker at the
next release. If your security policy requires SRI:
1. **Self-host a copy** of the tracker (and any modules you use) from your
own domain. The source is MIT licensed and published with every release.
The npm package `@privatus/tracker` doesn't pin the tracker. It's a
loader that injects the hosted `pa.js` at runtime (or the `src` you
give it) and has no `integrity` option, so its version pins the loader
code only.
2. Compute the hash:
```sh
curl -s https://privatusanalytics.com/js/pa.js -o pa.js
echo "sha384-$(openssl dgst -sha384 -binary pa.js | openssl base64 -A)"
```
3. Reference your copy with the hash and point hits at us with
`data-api`:
```html
<script defer src="/assets/pa.js"
integrity="sha384-…" crossorigin="anonymous"
data-site="pa_YOURSITEID"
data-api="https://privatusanalytics.com"></script>
```
Modules are loaded from `data-api`, not from your copy's location, and
they are loaded without an `integrity` attribute. So with the setup above,
any module you add in `data-modules` (for example `vitals` or `clicks`)
comes from `https://privatusanalytics.com/js/` and is not covered by your SRI hash.
If your policy requires every script to be pinned, leave out
`data-modules` or set it to `engage` only (engagement tracking is built
into `pa.js` and loads no extra file).
Update your copy when you want new tracker features. Old versions keep
working.
---
Source: https://privatusanalytics.com/docs/tracker/opt-out
# Let visitors opt out of analytics
> Let visitors opt out of analytics with privatus.optOut(), the only flag the tracker stores, and exclude your own visits by browser, IP range or WordPress.
## For visitors
```js
privatus.optOut() // stop sending hits from this browser
privatus.optIn() // undo
privatus.isOptedOut() // true or false
```
`optOut()` stores `privatus_optout=1` in `localStorage` on **your** domain.
It's the only thing the tracker ever writes to the device, and only
because the visitor asked for it, which makes it strictly necessary under
the ePrivacy Directive (Art. 5(3)). While it's set, the tracker sends
nothing: no pageviews, events, engagement, Vitals or clicks. Hits that
were waiting for a retry are dropped too.
The flag is per browser and per domain (subdomains have separate storage).
If storage is blocked, `optOut()` does nothing and `isOptedOut()` returns
`false`.
A ready-made button for your privacy page is in
[Opt-out snippet](/docs/privacy/opt-out). The WordPress plugin provides a
`[privatus_optout]` shortcode.
Browsers that send [Global Privacy Control](/docs/privacy/dnt-gpc) are
excluded automatically when the site honours GPC (the default).
## For you and your team
- Run `privatus.optOut()` once in the browser console on each of your
sites and browsers.
- Or block your office or VPN IP ranges in
[traffic rules](/docs/privacy/traffic-rules). The IP is checked in
memory and never stored.
- WordPress: the plugin skips logged-in administrators by default.
---
Source: https://privatusanalytics.com/docs/tracker/payload
# What the tracker sends (request payload)
> The exact POST request the tracker sends to /api/event, every field in its JSON payload, and what is never sent: no cookies, identifiers or fingerprints.
Every hit is one `POST` to `{origin}/api/event`:
- `Content-Type: text/plain`, so browsers don't send a CORS preflight,
- `credentials: 'omit'`: no cookies are sent or accepted,
- `keepalive: true`, so hits survive page navigation. `navigator.sendBeacon`
is the fallback when `fetch` throws.
The server answers **202 Accepted** with an empty body, whether or not the
hit is later kept, so the response never tells a script anything about
your settings.
## Retries
If the server answers with an error (any `4xx` or `5xx` status, including
`429` when a rate limit is hit), the tracker sends the same hit again:
- up to 5 more times, after 1 second, 10 seconds, then 60 seconds for
each of the last three,
- oldest hit first, one at a time,
- from a queue of at most 20 hits that lives in memory only. Nothing is
written to the device, so hits still waiting are lost when the page is
closed or reloaded.
A request that never gets an answer (the visitor is offline, or a content
blocker stops it) isn't retried.
A retried hit is recorded with the time it arrives, which can be a few
minutes after it happened. In rare cases the server has already recorded
a hit before the error reaches the browser, and the retry counts it a
second time.
## Body
```json
{
"s": "pa_7Q2K9XH3AB",
"t": "pageview",
"u": "https://example.com/pricing?utm_source=newsletter",
"r": "https://www.google.com/",
"l": "en-US",
"w": 1440,
"i": 0,
"p": { "plan": "pro" }
}
```
| Key | Long name | Sent with | Meaning |
|---|---|---|---|
| `s` | `site` | all | Site id |
| `t` | `type` | all | `pageview`, `event`, `engagement`, `vital` or `click` |
| `u` | `url` | all | Page URL after exclusions, masks and query parameter stripping |
| `r` | `referrer` | when present | `document.referrer`, or a URL on your own site for SPA navigations |
| `l` | `language` | all | `navigator.language` |
| `w` | `screen_width` | all | `screen.width` in CSS pixels (stored as a size bucket) |
| `i` | `interacted` | all | `1` once a real input was seen on the page, `0` before. See [Interaction flag](#interaction-flag) |
| `n` | `name` | event, vital | Event name, or the Web Vital (`LCP`, `INP`, `CLS`, `FCP`, `TTFB`) |
| `p` | `props` | pageview, event | Properties |
| `e` | `engaged_ms` | engagement | Visible time on the page in milliseconds |
| `sd` | `scroll_depth` | engagement | Maximum scroll depth, 0 to 100 |
| `v` | `value` | vital | The Web Vital value |
| `c` | `selector` | click | Short CSS selector of the clicked element |
| `h` | `hash_mode` | when on | `1` if the fragment is part of the path |
| `d` | `dnt` | when on | `1` if Do Not Track is on |
| `g` | `gpc` | when on | `1` if Global Privacy Control is on |
The server also accepts `rv`/`revenue` and `cu`/`currency` at the top
level, but the tracker puts them in `p`.
Anything larger than 32 KB is ignored.
## Interaction flag
Some bots run a real browser, load a page and leave without touching it.
To tell them from people, every hit says whether the tracker has seen a
real input on the page:
- `i` is `0` until the first pointer press or move, key press, touch or
wheel turn, and `1` from then on.
- At that first input the tracker sends one `engagement` hit straight
away, so the visit is marked even if the hit sent when the page closes
is lost.
- Scrolling alone doesn't count, and neither does input a script
generates. Both are things a bot can do without a person.
It is a yes or no. Nothing about the input is sent: not what it was, not
where the pointer was, not which key, not when. Visits are then reported
as input seen, none or unknown, see
[Visits with no input seen](/docs/server-side/bots#visits-with-no-input-seen).
## What isn't sent
No cookies, no stored identifiers, no user id, no screen height or color
depth, no installed fonts or plugins, no canvas or audio fingerprints, no
timezone, no mouse movement, no form contents.
The server receives the IP address and User-Agent because every HTTP
request carries them. They're used in memory and dropped. See
[How it works](/docs/privacy).
---
Source: https://privatusanalytics.com/docs/events
# Custom events and properties
> Track signups, purchases and other custom events with privatus.track(), HTML attributes or your server, plus naming rules, limits and how events count as usage.
A **custom event** is something that happens on a page: a signup, a
purchase, a video play. Events have a name and optional properties.
```js
privatus.track('Signup', { plan: 'pro', seats: 3 })
```
Events appear in the Conversions panel on the Overview and in the
[Events explorer](/docs/dashboard/events), and can become
[goals](/docs/features/goals) and [funnel](/docs/features/funnels) steps.
Three ways to send them:
1. **JavaScript:** `privatus.track()` ([API](/docs/tracker/javascript-api)).
2. **HTML attributes, no code:** `data-privatus-event="Signup"`
([HTML attributes](/docs/events/html-attributes)).
3. **From your server:** the [server-side ingest API](/docs/server-side).
The [`auto` module](/docs/tracker/modules#auto-automatic-events) tracks
outbound links, downloads, forms and 404s for you.
## Naming
- Up to **120 characters**, any language and script. Longer names are cut.
- Leading and trailing spaces are trimmed and Unicode is normalised (NFC),
so `Café` typed two different ways is one event.
- Case is kept for display. Pick one style and stick to it:
`Signup` and `signup` are stored as written. You can merge names later in
**Site settings → Events & properties**.
- Name the action, not the element: `Signup`, `Checkout started`,
`Invoice downloaded`, rather than `Blue button click`.
- Don't put variable data in names (`Viewed product 123`). Use a
property.
## Limits
| Limit | Value |
|---|---|
| Event name | 120 characters |
| Properties per event | 30 (extra ones are dropped) |
| Property key | 64 characters, `a-z`, `0-9`, `_` |
| String value | 500 characters |
| Array value | up to 30 strings |
| Property keys per site | 10 on Free, unlimited on paid plans |
| Request body | 32 KB |
## Usage
Every custom event counts as one event toward your monthly allowance, like
a pageview. Engagement pings, Web Vitals, click-map hits and bots don't
count. See [What counts as an event](/docs/billing/usage).
## Managing events
In **Site settings → Events & properties** you can rename events (history
is rewritten at query time), merge several names into one, hide events,
and delete an event including its history. See
[Events explorer](/docs/dashboard/events).
---
Source: https://privatusanalytics.com/docs/events/properties
# Custom event properties
> Add typed custom event properties (strings, numbers, booleans and arrays) to events and pageviews, see how keys are normalized and query them with prop filters.
Properties are key-value pairs sent with an event or pageview:
```js
privatus.track('Download', { file_type: 'pdf', size_mb: 2.4, gated: false, tags: ['guide', 'pricing'] })
```
## Types
| Type | Example | Notes |
|---|---|---|
| String | `'pro'` | Up to 500 characters. Longer values are cut |
| Number | `49.99`, `3` | Must be finite. Sum, average, median and p90 are available in the Events explorer |
| Boolean | `true` | |
| Array of strings | `['a', 'b']` | Up to 30 items. Non-string items are dropped |
`null`, `undefined`, objects and nested arrays are dropped. Dates: send an
ISO 8601 string (`'2026-09-29'`).
## Keys
Keys are normalised before storage: lowercased, any character outside
`a-z 0-9 _` becomes `_`, repeated underscores are collapsed, and the key is
cut to 64 characters. `Plan Name` becomes `plan_name`, `userType` becomes
`usertype`. Use `snake_case` to avoid surprises.
## Reserved keys
`revenue` and `currency` are taken out of the properties and stored as the
event's [revenue](/docs/events/revenue).
## Properties on every hit
```js
privatus.props({ logged_in: true, theme: 'dark' })
```
adds properties to every later pageview and event on the page load. Or
point [`data-props`](/docs/tracker/attributes) at a function that returns
them.
## Privacy
The [PII scrubber](/docs/privacy/pii-scrubbing) runs on every string value:
emails, long ids, tokens and long digit runs are replaced with
`[redacted-…]`. It's a safety net, not a license: never send names, emails,
user ids or free text typed by visitors.
## Querying properties
Use `prop:<key>` as a dimension anywhere the API or dashboard accepts one:
```text
/sites/pa_7Q2K9XH3AB/breakdown/prop:plan.json?filters=[["event","is","Signup"]]
```
or as a filter: `["prop:plan", "is", "pro"]`. See [Filters](/docs/api/filters).
---
Source: https://privatusanalytics.com/docs/events/revenue
# Revenue tracking
> Revenue tracking for custom events: attach an amount and ISO 4217 currency, report it in your site currency with ECB rates, and record refunds.
Add `revenue` (in major units: dollars, euros…) and an ISO 4217 `currency`
to any event:
```js
privatus.track('Purchase', { revenue: 49.99, currency: 'EUR', plan: 'pro' })
```
- `revenue` may be a number or a numeric string (`'49.99'`). It's stored
exactly, in minor units (cents).
- `currency` defaults to the site's currency when you leave it out.
- Both are removed from the properties and stored as dedicated fields.
## Multi-currency
Each event keeps its original currency and amount. Reports convert revenue
into the **site currency** using the European Central Bank reference rate
for the event's date (falling back to the latest earlier rate). You can
break revenue down by source, campaign, page or any property, in the site
currency.
## Revenue goals
A [goal](/docs/features/goals) can take its value from the event's
revenue, or have a fixed value (for example $50 per lead) when there's no
real revenue.
## Refunds
Send a negative amount with the same currency to record a refund as its
own event, for example `privatus.track('Refund', { revenue: -49.99, currency: 'EUR' })`,
or keep refunds out of analytics and treat revenue as gross.
## Server-side revenue
Purchases confirmed by a payment webhook are more reliable than
thank-you-page events. Send them with the [server-side API](/docs/server-side):
```json
{ "type": "event", "name": "Purchase", "url": "https://example.com/checkout", "revenue": 49.99, "currency": "EUR" }
```
---
Source: https://privatusanalytics.com/docs/events/html-attributes
# Track events with HTML attributes
> Track clicks and form submissions as custom events without writing JavaScript, using data-privatus-event and data-privatus-prop HTML attributes on any element.
Add `data-privatus-event` to any element to send an event when it's
clicked:
```html
<a href="/pricing" data-privatus-event="Pricing CTA">See pricing</a>
<button data-privatus-event="Play video" data-privatus-prop-video="intro">Play</button>
```
## Properties
Every `data-privatus-prop-<key>` attribute becomes a property. Dashes in the
key become underscores:
```html
<a href="/signup" data-privatus-event="Signup CTA"
data-privatus-prop-plan="pro"
data-privatus-prop-button-location="hero">Start free</a>
```
sends `Signup CTA` with `{ plan: 'pro', button_location: 'hero' }`.
Attribute values are always strings.
## Forms
On a `<form>`, the event fires when the form is **submitted** (clicks
inside the form don't trigger it):
```html
<form action="/contact" method="post" data-privatus-event="Contact form" data-privatus-prop-topic="sales">
…
</form>
```
Form fields are never read or sent. Only the attributes you write become
properties.
## How it works
The tracker listens for clicks and submits on the whole document (in the
capture phase), finds the nearest ancestor with `data-privatus-event`, and
sends the event. It works for elements added later, too.
- Clicking a child element (an icon inside a button) counts for the
element with the attribute.
- Elements with `data-privatus-event` are ignored by the
[`auto` module](/docs/tracker/modules#auto-automatic-events), so a
tracked outbound link isn't counted twice.
- Links navigate as usual. The request uses `keepalive` so it survives the
navigation.
## Click maps
For aggregate click maps, the `clicks` module also recognizes
`data-privatus-click` as a named click target. See
[Modules](/docs/tracker/modules#clicks-click-maps).
---
Source: https://privatusanalytics.com/docs/events/recipes
# Event tracking recipes
> Copy-paste event tracking for signups, checkout funnels, file downloads, outbound links, 404 pages, scroll milestones, video, A/B tests and user plans.
## Signup
On the page after a successful signup (or in your signup success handler):
```js
privatus.track('Signup', { plan: 'free', method: 'email' })
```
Better still, send it from the server once the account exists, so blocked
scripts and double submits don't matter. See
[server-side examples](/docs/server-side/examples).
Then create an **Event** goal named `Signup`.
## Checkout funnel
```js
privatus.track('Checkout started', { items: cart.items.length })
// …
privatus.track('Payment details entered')
// on the confirmation page:
privatus.track('Purchase', { revenue: order.total, currency: order.currency, items: order.items.length })
```
Build a [funnel](/docs/features/funnels) with the three events as steps.
Never send order ids, emails or addresses.
## File downloads
Automatically, with the `auto` module (`File Download` events with a `file`
property):
```html
<script defer src="https://privatusanalytics.com/js/pa.js" data-site="pa_YOURSITEID" data-modules="engage,auto"></script>
```
Or for a single link:
```html
<a href="/files/price-list.pdf" data-privatus-event="Price list download">Price list (PDF)</a>
```
## Outbound links
The `auto` module sends `Outbound Link` with `domain` and `url`. Create an
**Outbound click** goal for a specific domain, e.g. your app's signup page
on another domain.
## 404 pages
With the `auto` module, add this to your 404 template:
```html
<meta name="privatus-404" content="true">
```
Then look at the `404` event's `path` property to find broken links, or
use the **Not found** tab of the Pages panel. Without `auto`:
```html
<script>
window.addEventListener('load', function () {
privatus.track('404', { path: location.pathname });
});
</script>
```
## Scroll milestones
The `engage` module already reports scroll depth for every page. For an
event at a specific point (e.g. the end of an article):
```js
const end = document.querySelector('#article-end')
new IntersectionObserver((entries, observer) => {
if (entries.some((e) => e.isIntersecting)) {
privatus.track('Article finished', { section: 'blog' })
observer.disconnect()
}
}).observe(end)
```
Or create an **Engagement** goal (scroll ≥ 75% on `/blog/*`) with no code.
## Video
HTML5 video:
```js
document.querySelectorAll('video').forEach((video) => {
const name = video.dataset.name || video.currentSrc.split('/').pop()
video.addEventListener('play', () => privatus.track('Video play', { video: name }), { once: true })
video.addEventListener('ended', () => privatus.track('Video complete', { video: name }))
})
```
YouTube embeds need the YouTube IFrame API: listen to `onStateChange` and
track `YT.PlayerState.PLAYING` and `ENDED` the same way.
## Experiments (A/B tests)
Send the variant as a property on every hit, so every metric can be split
by variant:
```js
privatus.props({ experiment: 'pricing_2026_09', variant: variant })
```
with [manual mode](/docs/tracker/manual-mode) if the variant isn't known
until after load. Then break down any goal by `prop:variant`. The
[Experiments report](/docs/features/experiments) calculates conversion
rates per variant and their statistical significance.
## Logged-in state or plan
```js
privatus.props({ logged_in: true, plan: 'business' })
```
Never send a user id: it would make visitors identifiable and defeat the
cookieless design.
---
Source: https://privatusanalytics.com/docs/server-side
# Server-side ingest API
> Send pageviews and custom events from your backend with the server-side ingest API: the endpoint, ingest key authentication, event fields, limits and responses.
Send events from your server when the browser can't or shouldn't: payment
webhooks, signups confirmed by email, API products, backend jobs, or
pages served to clients without JavaScript.
## Endpoint
```http
POST https://privatusanalytics.com/api/events
Authorization: Bearer pik_…
Content-Type: application/json
```
```json
{
"events": [
{
"type": "event",
"name": "Purchase",
"url": "https://example.com/checkout",
"revenue": 49.99,
"currency": "USD",
"props": { "plan": "pro" },
"user_agent": "Mozilla/5.0 (Macintosh; …) Safari/605.1.15",
"ip": "203.0.113.7"
}
]
}
```
Authenticate with the site's secret **ingest key** (`pik_…`), either as a
Bearer token or in an `X-Ingest-Key` header. Each key belongs to one site.
See [Ingest keys](/docs/server-side/ingest-keys).
## Event fields
| Field | Required | Description |
|---|---|---|
| `type` | Yes | `pageview` or `event` (`custom` is an alias). `engagement` and `vital` are also accepted but need an existing visit |
| `name` | For events | Event name, up to 120 characters |
| `url` | Yes | Full `http(s)` URL of the page. Its hostname must be one of the site's domains (or a subdomain of one) |
| `referrer` | No | Where the visitor came from, which drives sources and channels |
| `props` | No | Up to 30 [properties](/docs/events/properties) |
| `revenue` | No | Amount in major units, e.g. `49.99` ([Revenue](/docs/events/revenue)) |
| `currency` | No | ISO 4217 code. Defaults to the site currency |
| `timestamp` | No | ISO 8601. Must be within the last **72 hours**. Otherwise (or if missing or in the future) the time of receipt is used |
| `user_agent` | In practice, yes | The **visitor's** browser User-Agent. Missing or library User-Agents are dropped as bots (see below) |
| `ip` | No | The **visitor's** IP. Used in memory for the country and the daily visit key, then dropped. Without it there's no location |
| `session_hint` | No | An opaque string that groups your server events into one visit. See [Sessions](/docs/server-side/sessions) |
| `language` | No | e.g. `en-US` |
| `screen_width` | No | Pixels, stored as a size bucket |
The short keys the browser tracker uses (`t`, `n`, `u`, `r`, `p`…) are
accepted too. See [What the tracker sends](/docs/tracker/payload).
## Limits
- Up to **100 events** per request. More returns `422`.
- The request body must be at most **32 KB**. Larger bodies are read as
empty. Split big batches.
- Everything else (property limits, name length, PII scrubbing, path
masking, traffic rules, bot filtering) works exactly as for browser hits.
## Response
`202 Accepted` with one result per event, in order:
```json
{
"data": [
{ "index": 0, "status": "accepted", "reason": null },
{ "index": 1, "status": "dropped", "reason": "bot_automation" }
]
}
```
`accepted` means the event was queued and will appear in the dashboard
within seconds. `dropped` events aren't stored and don't count toward
usage. Reasons:
| Reason | Meaning |
|---|---|
| `bad_type` | `type` isn't one of the accepted values |
| `bad_url` | `url` is missing or not an `http(s)` URL |
| `foreign_host` | The URL's hostname isn't one of the site's domains |
| `privacy_signal` | The event carried DNT/GPC (`dnt`/`gpc` fields) and the site honours it |
| `bot_empty_user_agent` | No `user_agent` |
| `bot_known_bot` | A known crawler User-Agent |
| `bot_automation` | An automation or HTTP-library User-Agent (see [Bot rules](/docs/server-side/bots)) |
| `bot_datacenter` | The `ip` belongs to a cloud or hosting network |
| `bot_referrer_spam` | The referrer is on the referrer-spam list |
| `rule_<list>` | Blocked by a [traffic rule](/docs/privacy/traffic-rules), e.g. `rule_paths` |
| `vital_sampled` | A Web Vital outside the sample rate |
| `no_visit` | An engagement or vital hit with no visit to attach to |
| `paused` | Collection is paused for the workspace by Privatus Analytics support |
| `limit_reached` | The workspace reached its monthly event limit, so pageviews and custom events are not recorded until the reset or an upgrade (see [Monthly limit](/docs/billing/overage)) |
Errors:
| Status | Body `error.code` | When |
|---|---|---|
| `401` | `unauthorized` | Missing or unknown ingest key |
| `422` | `validation_failed` | More than 100 events, or `events` isn't an array |
## Next
- [Examples](/docs/server-side/examples) in curl, Node, Python, PHP, Go and
Ruby.
- [SDKs](/docs/server-side/sdks) that batch, retry and handle timestamps
for you.
- The browser's [no-JavaScript pixel](/docs/install/pixel) for pages
without JavaScript.
---
Source: https://privatusanalytics.com/docs/server-side/ingest-keys
# Server-side ingest keys
> Create, rotate and revoke the secret ingest key that authenticates server-side events, keep it out of browser code, and see how it differs from an API token.
An ingest key (`pik_…`) lets a server send events for **one site**. Unlike
the public site id, it's a **secret**: anyone with it can send data to
your site.
## Create or rotate
**Site settings → Tracking → Server ingest key → Create key.** The key is
shown **once**. Copy it into your secret store (environment variable,
secrets manager). We only keep a SHA-256 digest and a short prefix so you
can recognize it.
Creating a key again **rotates** it: the new key works immediately and the
old one stops working. To rotate without downtime, deploy the new key
right after creating it. Events sent with the old key in between get
`401`.
**Revoke** removes the key, and server-side events are rejected until you
create a new one.
Both are also [API operations](/docs/api) (`sites.manage` permission), so
you can rotate keys from your infrastructure tooling.
## Keep it secret
- Never put an ingest key in browser code, mobile apps or public
repositories. For browsers, the public site id and `/api/event` are the
right tool.
- Store it in an environment variable, e.g. `PRIVATUS_INGEST_KEY`.
- The WordPress plugin can read it from `wp-config.php`
(`define( 'PRIVATUS_INGEST_KEY', 'pik_…' );`).
## Ingest keys vs API tokens
| | Ingest key `pik_…` | API token `pat_…` |
|---|---|---|
| Scope | One site | A member's workspace access, narrowed by permissions and sites |
| Can | Send events | Read stats, manage settings, everything in the [API](/docs/api) |
| Used at | `POST /api/events` | Every `.json` endpoint and `/mcp` |
An API token can't send events and an ingest key can't read data.
---
Source: https://privatusanalytics.com/docs/server-side/sessions
# Server-side sessions and session hints
> How server-side events are grouped into visits with the daily salted visit key and how session_hint splits or joins visits.
Server-side events join visits exactly like browser hits.
## The visit key
The visit key is an HMAC of the **daily salt**, the site, the visitor's
IP and User-Agent (and your `session_hint`, if you send one). The key lives
only in memory (Redis, no persistence) for 30 minutes of inactivity and
never past midnight UTC. The salt is random, rotates daily and is never
stored, so the key can't be recomputed later.
- Forward the **visitor's** IP and User-Agent, not your server's, or every
visitor looks like one person.
- If you send the same IP and User-Agent from the browser tracker and from
the server, server events join the visitor's browser visit: a purchase
confirmed by a webhook is attributed to the campaign that brought the
visitor. For that, the webhook needs the IP and User-Agent from the
original checkout request. Store them with the order only for as long as
the checkout takes, then delete them.
## `session_hint`
An optional opaque string, for example a cart id or a job id:
```json
{ "type": "event", "name": "Checkout step", "url": "https://example.com/checkout", "session_hint": "cart_8f2a…", "user_agent": "…" }
```
It's added to the HMAC input, so:
- events with the same hint (and the same IP/User-Agent) form one visit,
- events with different hints are separate visits, even from the same IP
and User-Agent (for example, many users behind one office proxy, or a
backend without the visitor's IP).
The hint is **never stored**: it's hashed together with the daily salt and
discarded. Still, don't use emails or user ids as hints. A random id per
cart or session is enough.
## Timestamps
A `timestamp` up to 72 hours old places the event at that time. Visits are
still keyed by the day the event happened (UTC), so late events join the
right day's visit only if that visit is still in memory (30 minutes
idle). Older back-fills create their own visits.
---
Source: https://privatusanalytics.com/docs/server-side/bots
# Bot filtering rules
> Bot filtering rules for User-Agents, crawlers and data centers, and how to send server-side events with the visitor's User-Agent and IP so they count.
Every hit, browser or server, goes through the same bot checks before it's
counted. Bots are counted in aggregate (reason, country) with **no IP
stored**, and don't count toward your usage.
## Checks, in order
1. **Empty User-Agent** → `bot_empty_user_agent`.
2. **Known crawlers** (Googlebot, Bingbot, GPTBot and the rest of our UA
list) → `bot_known_bot`.
3. **Automation and HTTP libraries** → `bot_automation`. User-Agents
containing any of: `headless`, `phantomjs`, `puppeteer`, `playwright`,
`selenium`, `webdriver`, `electron`, `slimerjs`, `lighthouse`,
`pagespeed`, `gtmetrix`, `pingdom`, `uptimerobot`, `monitage`,
`prerender`, `python`, `curl`, `wget`, `httpclient`, `okhttp`,
`go-http`, `java/`, `axios`, `node-fetch`, `scrapy`.
4. **Data-center networks** (major cloud and hosting providers, by ASN) →
`bot_datacenter`. VPN and relay networks such as iCloud Private Relay
aren't on the list, so real people behind them count.
5. **Referrer spam** domains → `bot_referrer_spam`.
## What this means for server-side events
- Always send the **visitor's** `user_agent`. If you leave it out, or your
HTTP library's default (`python-requests/2.x`, `node-fetch`, `curl/8`,
`Go-http-client`…) ends up in `user_agent`, the event is dropped.
- Send the **visitor's** `ip`, or none at all. Your server's IP is often a
cloud IP and would be filtered as a data center.
- The request's own headers don't matter: the checks use the `user_agent`
and `ip` fields in the body.
## Visits with no input seen
Some bots run a real browser with an ordinary User-Agent, so the checks
above let them through. They tend to load one page and leave without
touching it. To help you spot them, the tracker reports whether it saw any
real input during a visit: a pointer press or move, a key press, a touch or
a wheel turn. It sends a yes or no only, never what the input was (see
[What the tracker sends](/docs/tracker/payload#interaction-flag)).
Every visit then has one of three values in the `interaction` dimension:
| Value | Meaning |
|---|---|
| `seen` | Input was seen on at least one page of the visit |
| `none` | The tracker could tell, and saw none |
| `unknown` | Nothing can tell: server-side events, the no-JavaScript pixel, a self-hosted copy of an older tracker, and all data from before 1 October 2026 |
These visits are **not dropped**, and they count toward your usage like any
other. A person who opens a page and closes it without touching it also
shows as `none`, so read it as a signal, not as proof.
- **Overview → Technology → Interaction** breaks visits down by the three
values. Click a row to filter the dashboard by it.
- To leave them out of a report or an API call, filter with
`["interaction", "is_not", "none"]`. Save it as a
[segment](/docs/dashboard/filters-and-segments) to reuse it.
- **Site settings → Bots** shows how many visits in the last 30 days had no
input seen, with links to both views.
## Turning filtering off
**Site settings → Bots** lets you switch bot filtering off for a site, for
diagnostics. Everything is then counted, including crawlers. Turn it back
on when you're done.
The bot summary on the same tab shows the last 30 days by reason and
country, and the Overview's footer shows how many hits were filtered. For AI
crawler visibility (which never runs JavaScript), use the
[AI crawler logs](/docs/features/ai-crawlers).
---
Source: https://privatusanalytics.com/docs/server-side/examples
# Server-side ingest code examples
> Server-side ingest examples that send an event with curl, Node.js, Python, PHP, Go, Rails and Next.js, forwarding the visitor's User-Agent and IP.
All examples send one `Signup` event for the visitor who made the current
request. Keep the ingest key in `PRIVATUS_INGEST_KEY`.
## curl
```sh
curl -X POST https://privatusanalytics.com/api/events \
-H "Authorization: Bearer $PRIVATUS_INGEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"events": [{
"type": "event",
"name": "Signup",
"url": "https://example.com/signup",
"props": { "plan": "pro" },
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0 Safari/537.36",
"ip": "203.0.113.7"
}]
}'
```
The `user_agent` must be a real browser's: curl's own User-Agent is only on
the request, not in the event, so it doesn't matter here.
## Node.js (Express)
```js
app.post('/signup', async (req, res) => {
// … create the account …
const response = await fetch('https://privatusanalytics.com/api/events', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PRIVATUS_INGEST_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
events: [{
type: 'event',
name: 'Signup',
url: `https://example.com${req.originalUrl}`,
referrer: req.get('referer'),
props: { plan: req.body.plan },
user_agent: req.get('user-agent'),
ip: req.ip, // set app.set('trust proxy', …) behind a load balancer
}],
}),
})
const { data } = await response.json() // [{ index, status, reason }]
res.redirect('/welcome')
})
```
## Python (Django or Flask)
```python
import os
import requests
def track_signup(request, plan):
requests.post(
"https://privatusanalytics.com/api/events",
headers={"Authorization": f"Bearer {os.environ['PRIVATUS_INGEST_KEY']}"},
json={"events": [{
"type": "event",
"name": "Signup",
"url": request.build_absolute_uri(), # Flask: request.url
"props": {"plan": plan},
"user_agent": request.headers.get("User-Agent"),
"ip": request.META.get("REMOTE_ADDR"), # Flask: request.remote_addr
}]},
timeout=5,
)
```
## PHP
```php
<?php
$payload = ['events' => [[
'type' => 'event',
'name' => 'Signup',
'url' => 'https://example.com' . $_SERVER['REQUEST_URI'],
'props' => ['plan' => 'pro'],
'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? null,
'ip' => $_SERVER['REMOTE_ADDR'] ?? null,
]]];
$ch = curl_init('https://privatusanalytics.com/api/events');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('PRIVATUS_INGEST_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
```
## Go
```go
func trackSignup(r *http.Request, plan string) error {
body, _ := json.Marshal(map[string]any{
"events": []map[string]any{{
"type": "event",
"name": "Signup",
"url": "https://example.com" + r.URL.RequestURI(),
"props": map[string]any{"plan": plan},
"user_agent": r.UserAgent(),
"ip": clientIP(r), // your helper: RemoteAddr or X-Forwarded-For from a trusted proxy
}},
})
req, _ := http.NewRequestWithContext(r.Context(), http.MethodPost,
"https://privatusanalytics.com/api/events", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("PRIVATUS_INGEST_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
return nil
}
```
## Ruby (Rails)
```ruby
require "net/http"
class PrivatusEvents
URL = URI("https://privatusanalytics.com/api/events")
def self.track(request, name, props = {})
Net::HTTP.post(
URL,
{ events: [{ type: "event", name:, url: request.original_url, props:,
user_agent: request.user_agent, ip: request.remote_ip }] }.to_json,
"Authorization" => "Bearer #{ENV.fetch('PRIVATUS_INGEST_KEY')}",
"Content-Type" => "application/json"
)
end
end
# In a controller:
PrivatusEvents.track(request, "Signup", plan: "pro")
```
Consider sending from a background job so a slow network never delays your
response, but **don't put the IP or User-Agent in the job payload** if your
job store is persistent. Send in the request, or drop `ip`.
## Next.js middleware
The [`@privatus/next`](/docs/install/nextjs#server-side-events) package's
`trackPageview()` and `trackEvent()` read the IP and User-Agent from the
incoming request for you and run on the Edge runtime.
> **Warning:** `@privatus/next` is not published on npm yet. Until it is,
> don't install a package with this name from the public registry,
> because anyone could have published it. Call the ingest API
> directly, as in the examples above, instead.
---
Source: https://privatusanalytics.com/docs/server-side/sdks
# Server-side analytics SDKs
> Server-side analytics SDKs for Node.js, Python, PHP, Go and Ruby that wrap the ingest API and batch events. They are not published yet, so read the warning.
The SDKs wrap the ingest API (and the [management API](/docs/api)). They
split lists into batches of 100, convert timestamps to ISO 8601, and return
the per-event results. All are MIT licensed and never log or store the IP
and User-Agent you pass.
| Language | Install | Package |
|---|---|---|
| Node.js (≥ 18, ESM + CJS, TypeScript) | `npm install @privatus/node` | `@privatus/node` |
| Python (≥ 3.9, sync and async) | `pip install privatus` | `privatus` |
| PHP (≥ 8.1) | `composer require privatus/privatus-php` | `privatus/privatus-php` |
| Go (≥ 1.21, standard library only) | `go get github.com/privatus-analytics/privatus-go` | `privatus` |
| Ruby | `gem install privatus` | `Privatus` |
> **Warning:** These SDKs are not published yet (not on npm, PyPI,
> Packagist, the Go module proxy or RubyGems). Until they are, don't
> install packages with these names from public registries, because anyone
> could have published them. Call the ingest API directly instead, as in
> the [examples](/docs/server-side/examples).
## Node.js
```ts
import { Ingest, event } from '@privatus/node'
const ingest = new Ingest(process.env.PRIVATUS_INGEST_KEY!)
const results = await ingest.track([
event('Purchase', 'https://example.com/checkout', {
user_agent: req.get('user-agent'),
ip: req.ip,
revenue: 49.99,
currency: 'USD',
props: { plan: 'pro' },
}),
])
// [{ index: 0, status: 'accepted', reason: null }]
```
## Python
```python
from privatus import Ingest, event
ingest = Ingest(os.environ["PRIVATUS_INGEST_KEY"])
ingest.track([
event("Purchase", "https://example.com/checkout",
user_agent=request.headers.get("User-Agent"),
revenue=49.99, currency="USD", props={"plan": "pro"}),
])
```
## PHP
```php
use Privatus\Ingest;
$ingest = new Ingest(getenv('PRIVATUS_INGEST_KEY'));
$ingest->track([
Ingest::event('Purchase', 'https://example.com/checkout',
props: ['plan' => 'pro'], userAgent: $_SERVER['HTTP_USER_AGENT'] ?? null,
revenue: 49.99, currency: 'USD'),
]);
```
## Go
```go
ingest := privatus.NewIngest(os.Getenv("PRIVATUS_INGEST_KEY"))
results, err := ingest.Track(r.Context(),
privatus.CustomEvent("Purchase", "https://example.com/checkout", privatus.EventOptions{
UserAgent: r.UserAgent(),
Revenue: 49.99,
Currency: "USD",
Props: map[string]any{"plan": "pro"},
}),
)
```
## Ruby
```ruby
require "privatus"
ingest = Privatus::Ingest.new(ENV.fetch("PRIVATUS_INGEST_KEY"))
ingest.track([
Privatus::Ingest.event("Purchase", "https://example.com/checkout",
user_agent: request.user_agent, revenue: 49.99,
currency: "USD", props: { plan: "pro" })
])
```
## Mobile apps
SDKs for Swift, Kotlin, Flutter and React Native track screens as
pageviews. Their READMEs cover installation. They use the same public
collection endpoint as the browser tracker, never an ingest key.
---
Source: https://privatusanalytics.com/docs/dashboard
# Using the analytics dashboard
> A tour of the Privatus Analytics dashboard: layout, navigation, shareable URLs that hold every view, and links to each page's guide.
## Layout
- **Left sidebar:** the workspace switcher at the top, then two sections.
**Site** (shown while you view a site) has Overview, Live, Pages,
Sources, Campaigns, Goals, Funnels, Events, Segments, Notes, Journeys,
Performance, Uptime, Search, AI crawlers, Insights, Ask AI, Alerts,
Imports and Settings. **Workspace** has All sites, Dashboards, Email
reports, Alerts, Notes, Exports, Uptime, Status pages, Members, API
tokens, Webhooks, Billing, Audit log and Settings. Items your role
can't open are hidden. At the bottom are the API and MCP docs, your
account settings, the theme switch and Log out.
- **Docs link:** every page links to its guide in these docs, above the
page content. It opens in a new tab.
- **On phones** the sidebar opens from the menu button in a small top
bar, which also shows the site name and the Docs link.
Every page works down to 360 px wide, in light and dark themes.
## The URL is the state
The date range, comparison, filters and segment live in the URL. Copy it
to share exactly what you see with a teammate, bookmark a view, or add
`.json` to get the same data from the [API](/docs/api):
```text
/sites/pa_7Q2K9XH3AB/overview?period=30d&filters=[["channel","is","organic_search"]]
```
## Pages
- [All sites](/docs/dashboard/all-sites)
- [Overview](/docs/dashboard/overview)
- [Date ranges and comparisons](/docs/dashboard/date-ranges)
- [Filters and segments](/docs/dashboard/filters-and-segments)
- [Drill-down tables](/docs/dashboard/drill-down)
- [Page detail](/docs/dashboard/page-detail)
- [Live and wallboard](/docs/dashboard/live)
- [Events explorer](/docs/dashboard/events)
- [Notes](/docs/dashboard/notes)
- [Insights](/docs/dashboard/insights)
- [Ask (AI assistant)](/docs/dashboard/ask)
- [Custom dashboards](/docs/dashboard/custom-dashboards)
- [Keyboard shortcuts](/docs/dashboard/keyboard-shortcuts)
- [Site settings](/docs/dashboard/site-settings),
[workspace settings](/docs/dashboard/workspace-settings),
[account settings](/docs/dashboard/account-settings)
Goals, funnels, journeys, campaigns, performance, uptime and search have
their own section: [Goals, funnels & more](/docs/features).
---
Source: https://privatusanalytics.com/docs/dashboard/all-sites
# All sites dashboard
> The all sites dashboard lists every website in your workspace with live visitors, 30-day visitor trends and sparklines. Learn to sort, search and label sites.
The first page after signing in lists every site in the workspace that
you can access.
## Site tiles
Each site shows:
- its name and domain, and a star to make it a **favorite** (favorites
come first),
- live visitors (last 5 minutes),
- visitors in the last 30 days, with the change against the 30 days
before,
- a sparkline,
- a badge when no data has arrived recently, or while the site is waiting
for its first hit.
A **totals strip** adds up sites, visitors, the change and live visitors
across the page.
## Controls
- **Sort** by your order, name or visitors.
- **Search** by name or domain, and filter by **labels** (set labels in
Site settings → General).
- **Add site**.
---
Source: https://privatusanalytics.com/docs/dashboard/overview
# Analytics dashboard overview
> The main site dashboard explained: headline metrics like visitors and bounce rate, the main chart, comparisons, filters and breakdown panels by source and page.
## Toolbar
- **Date range** with presets (each with a [keyboard shortcut](/docs/dashboard/keyboard-shortcuts)
where shown) and a custom range. See [Date ranges](/docs/dashboard/date-ranges).
- **Compare** with the previous period, or the same period last year.
Custom comparison ranges are available through the API
(`compare=custom` with `compare_from` and `compare_to`).
- **Segment** picker and the **filter builder** (see
[Filters and segments](/docs/dashboard/filters-and-segments)).
- **Show imported data**, when the site has [imports](/docs/reports/imports).
It adds imported history for dates before your first tracked event and
is not applied while filters or a segment are active.
- **JSON**: the same view from the API.
## Headline metrics
Visitors, Visits, Pageviews, Views per visit, Bounce rate, Visit duration,
plus Revenue (when the site has revenue). Each card shows the value and the
change against the comparison period, with the previous value underneath.
Click a card to plot it on the main chart. Every metric is defined in
[Metrics & definitions](/docs/metrics).
A **Live** pill shows the current visitor count and links to
[Live](/docs/dashboard/live).
## Main chart
- **Interval:** hour, day, week or month. The API also accepts minute
(today only), quarter, year and auto.
- The comparison period is drawn as a dashed series.
- The current, incomplete period is drawn dotted.
- [Notes](/docs/dashboard/notes) in the range are listed under the chart.
## Panels
| Panel | Tabs |
|---|---|
| Sources | Channels · Referrers · URLs |
| Pages | Top · Entry · Exit · Hostnames |
| Locations | Countries · Languages |
| Technology | Devices · Browsers · OS · Screens · Interaction |
| Campaigns | Campaign · Source · Medium · Content · Term |
| Conversions | Goals · Events |
In every panel you can:
- **click a row** to filter the whole dashboard by it,
- open **View all** for the full [drill-down table](/docs/dashboard/drill-down).
More dimensions (for example `ref`, browser and OS versions) are available
in the drill-down table and through the `breakdown` API operation.
Location is country only. Regions and cities aren't collected.
---
Source: https://privatusanalytics.com/docs/dashboard/date-ranges
# Date ranges and comparisons
> Pick date range presets or custom dates, compare with the previous period or the same period last year, and choose chart intervals, all in the site's timezone.
## Presets
| Preset | API value |
|---|---|
| Today | `today` |
| Yesterday | `yesterday` |
| Last 24 hours | `24h` |
| Last 7 / 14 / 28 / 30 / 90 days (including today) | `7d`, `14d`, `28d`, `30d`, `90d` |
| Month to date | `mtd` |
| Last month | `last_month` |
| Quarter to date | `qtd` |
| Last quarter | `last_quarter` |
| Year to date | `ytd` |
| Last 12 months | `12mo` |
| Last calendar year | `last_year` |
| All time (from the first event) | `all` |
| Custom | `custom` with `from` and `to` (inclusive, `YYYY-MM-DD`) |
The default is **Last 30 days**. ◀ and ▶ (or `[` and `]`) step back and
forward by one period.
## Timezone
Ranges are calendar days in the **site's timezone** (Site settings →
General). Data is stored in UTC, so changing the timezone re-buckets
history instantly. "Last 24 hours" is a rolling window. See
[Timezones](/docs/troubleshooting/timezones).
## Comparisons
| Option | API value |
|---|---|
| Off | `none` |
| Previous period (the same length, immediately before) | `previous_period` |
| Same period last year | `previous_year` |
| Custom | `custom` with `compare_from` and `compare_to` |
**Match day of week** (`match_weekday=true`) shifts the comparison by whole
weeks (previous period) or 52 weeks (previous year), so Mondays are
compared with Mondays.
## Intervals
`auto` picks hours for one day or less, days up to 92 days, weeks up to a
year and months beyond. You can choose `minute` (ranges of one day or
less), `hour` (up to 14 days), `day`, `week`, `month`, `quarter` or
`year`.
---
Source: https://privatusanalytics.com/docs/dashboard/filters-and-segments
# Analytics filters and segments
> Filter every dashboard report by source, page, country, event or property, combine conditions with AND and OR groups, and save them as reusable segments.
## Filters
Click any row in a panel to add an `is` filter (Alt/⌥-click for `is not`),
or use **+ Filter** (`F`) to build one: choose a dimension, an operator and
one or more values. Active filters show as chips. Click a chip to change
it, **Clear** (`Esc`) to remove them all.
Filters apply to every metric, chart and panel on the page, and are kept
in the URL.
### Operators
| Operator | Meaning |
|---|---|
| `is` / `is_not` | Equals / doesn't equal |
| `any_of` / `none_of` | Equals one of a list / none of a list |
| `contains` / `not_contains` | Substring match, case-insensitive |
| `starts_with` | Prefix match |
| `regex` / `not_regex` | Regular expression (up to 200 characters) |
| `gt`, `lt`, `between` | Numbers, for numeric properties |
### AND and OR
Separate filters are combined with **AND**. Put conditions in an OR group
to match any of them: "channel is Email **or** utm_medium is newsletter".
Up to 20 conditions in total.
### What a filter selects
- **Visit dimensions** (source, channel, UTM, country, device, browser,
entry page…) select visits.
- **Page** selects visits that viewed the page, and pageview counts for
that page.
- **Event**, **goal** and **property** filters select visits in which that
event or goal happened.
The full list of dimensions and the JSON syntax used in URLs and the API
are in [Filters (API)](/docs/api/filters).
## Segments
A segment is a saved set of filters with a name, like "Paid traffic from
the US" or "Visits that saw pricing". Choose one with the **Segment**
picker (`S`). It combines with any filters you add on top.
Create one with **+ New segment**, or save the current filters. Segments
belong to the site and are shared with everyone who can see it. Use them in
the API with `segment_id=seg_…`.
---
Source: https://privatusanalytics.com/docs/dashboard/drill-down
# Drill-down report tables
> Open the full drill-down table for any dimension, switch dimensions, filter by clicking a row and export up to 1,000 rows as CSV or JSON, also through the API.
**View all** on any panel (or Pages and Sources in the navigation) opens the
full table for that dimension.
- **Paginated**, with previous and next links.
- **Switch dimension** from the list at the top.
- **Click a row** to filter by it. Page rows link to the
[page detail](/docs/dashboard/page-detail) view.
- **Export** the table as CSV (up to 1,000 rows), or open it as JSON.
The table respects the current date range, filters and segment, shown at
the top. Through the API you can also sort by visitors, visits, pageviews
or revenue.
## API
Each table is the `breakdown` operation:
```sh
curl "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/page.json?period=30d&limit=100&page=2" \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
```
Add `.csv` instead of `.json` to download the rows as CSV. See
[Stats endpoints](/docs/api/stats).
---
Source: https://privatusanalytics.com/docs/dashboard/page-detail
# Page analytics detail view
> Everything about one page in one view: visitors, entry and exit rates, time on page, scroll depth, previous and next pages, sources and Web Vitals by device.
Opens when you filter on a single page, or from a row's menu in the Pages
panel.
- **Header:** the path, a link to the live URL, the last seen page title
and the filters in use.
- **Metrics:** visitors, pageviews, entry rate, exit rate, bounce rate as an
entry page, median time on page, median scroll depth, and conversions
after viewing the page.
- **Journeys:** the top **previous pages** (including "entrance") and
**next pages** (including "exit") with their shares. Click one to step
along the path.
- **Sources:** channels and referrers of visits that entered on this page.
- **Web Vitals:** p75 values and the distribution by device (with the
`vitals` module).
- **Events** fired on this page.
- **Notes** that mention this path.
---
Source: https://privatusanalytics.com/docs/dashboard/live
# Real-time visitors and wallboard
> See real-time visitors, a live activity stream and top pages from the last 30 minutes, and put a full-screen wallboard on an office TV with a secret link.
## Live
- **Live visitors:** distinct visits seen in the last 5 minutes, with a
30-minute sparkline at one-minute resolution.
- **Activity stream:** pageviews and events as they arrive, with the
relative time, page, event name, channel, country flag, device and
browser. Pause and resume it, or show only events or only pageviews.
- **Map:** countries with hits in the last 30 minutes.
- **Right now:** top pages, referrers, events and countries in the last 30
minutes.
What you'll never see here, by design: IP addresses, cities, names, or any
trail of what one visitor did.
Hits reach the Live page in about two seconds.
## Wallboard
`/sites/<site id>/live/wallboard` shows big numbers full screen, for an
office TV:
- visitors right now, today's visitors, pageviews and bounce rate, and the
top pages, countries and referrers right now,
- rotate between several sites every N seconds,
- dark theme with slow movement so screens don't burn in.
### Wallboard links
A TV shouldn't be signed in to your account. Create a **wallboard link**
(Live → Wallboard → Links): a secret URL that shows the wallboard without
signing in. Links are read-only, limited to the sites you choose, and can
be revoked at any time.
---
Source: https://privatusanalytics.com/docs/dashboard/events
# Custom events explorer
> Explore every custom event with completions, unique visitors and conversion rate, pivot event properties, aggregate numeric values, and rename or merge events.
**Events** lists every custom event name for the range with:
- completions (total times it fired),
- unique visitors and visits with the event,
- conversion rate (visits with the event ÷ all visits),
- first and last seen.
Search the list by name. The same list is available as JSON from the
`events_list` API operation.
## Event detail
Click an event for:
- a chart over time,
- a **property pivot**: choose up to three properties as rows or columns,
- for number properties, the **sum, average, median and p90**,
- the pages where it fired and the sources of visits that fired it.
## Managing events
From Events, or **Site settings → Events & properties**:
| Action | Effect |
|---|---|
| Rename | Shows the event under a new name, for all history (applied at query time) |
| Merge | Combine several names into one (`Sign up` + `signup` → `Signup`) |
| Hide | Hide an event from lists without deleting data |
| Delete | Permanently delete the event **including its history**. Confirm by typing the name |
| Currency override | Treat an event's revenue as a given currency |
## Property settings
Click **Property settings** on the Events page, or **Site settings →
Events & properties → Manage properties**. The page lists the
[property](/docs/events/properties) keys of the site's custom events:
- every key seen in the last 30 days (up to 200), most used first, with
the number of events that carried it,
- keys you saved a setting for earlier, even when no event carried them
in the last 30 days.
Each row has three settings and its own **Save** button:
| Setting | Effect |
|---|---|
| **Label** | A display name shown in place of the key in an event's property list and pivot (up to 64 characters). Clear it to show the key again |
| **Hidden** | Leaves the key out of the property list on the [event detail](/docs/dashboard/events#event-detail) page |
| **No personal data** | Confirms the key never holds personal data. Only keys marked this way are included in raw event exports and warehouse syncs |
Labels and hiding are applied when a report is built. Stored data is not
changed, and the key itself stays the same, so filters and the API still
use it as `prop:<key>`.
> **Note:** Row-level data leaves the product without any property you
> haven't marked. To get `plan` into a raw event export (Pro and up) or
> a warehouse sync (Business), tick **No personal data** for `plan`
> first. See [Exports](/docs/reports/exports).
Seeing the page needs `analytics.read`. Changing a setting needs
`sites.manage` (Owner, Admin, Editor). Other members see the labels and
flags without the form.
Free: 10 distinct property keys per site. Paid plans: unlimited. On
Free, keys already in use keep working, and an event that brings an 11th
key is stored without that property. The list of keys in use is rebuilt
every day from the most used keys of the last 30 days, so a key you stop
sending frees its place.
## API
Events are under `/sites/<site id>/events`, with MCP tools named
`events_*` (`events_list`, `events_get`, `events_update`, `events_merge`,
`events_delete`).
Property settings are `GET /sites/<site id>/events/properties` (MCP:
`event_properties_list`, with an optional `event` to list only the keys
seen on one event name) and `PATCH /sites/<site id>/events/properties`
(MCP: `event_properties_update`, with `key`, `display_name`, `hidden` and
`export_safe`).
The [API reference](/docs/api) lists every input.
---
Source: https://privatusanalytics.com/docs/dashboard/notes
# Chart notes and annotations
> Annotate analytics charts with notes for launches, campaigns and incidents, and get automatic notes for deploys, downtime, imports and Web Vitals regressions.
Notes appear as pins on every chart. Each note has:
- a date or a date range,
- a title and optional Markdown text,
- an optional link,
- a color,
- a scope: this site, or all sites in the workspace.
Add one from the chart (click a date, or press `N`), from **Site settings →
Notes**, or through the API (for example from your deploy pipeline).
## Automatic notes
- **Deploys**: post a note with `source: "deploy"` from your CI or deploy
script. **Site settings → Notes** shows a ready-to-copy `curl` command
(it needs an API token with `content.write`).
- **Incidents**: when an [uptime check](/docs/features/uptime) linked to the
site goes down.
- **Imports**: when historical data is added, spanning the imported dates.
- **Web Vitals regressions**: when a Core Web Vital gets more than 20%
worse week over week.
---
Source: https://privatusanalytics.com/docs/dashboard/insights
# Automatic traffic insights
> Insights automatically detects notable changes in your traffic, such as a source sending more visitors or a page losing views, against your site's own history.
**Insights** looks for notable changes this week compared with the usual
pattern: a source that suddenly sends more visitors, a page whose traffic
dropped, a goal whose conversion rate moved, a country or campaign that
appeared. Each insight links to the dashboard view that shows it.
Insights compare against a baseline built from your own history, so they
get better as a site collects more data. Use
[alerts](/docs/reports/alerts) with the *anomaly* rule to be notified about
changes like these as they happen.
---
Source: https://privatusanalytics.com/docs/dashboard/ask
# Ask the AI analytics assistant
> Ask questions about your website analytics in plain language and get numbers, charts and the exact queries behind them, with zero data retention by the model.
**Ask** is a side panel on every page. Type a question such as "Which
campaigns brought the most signups last month?" and get the numbers, a
chart and a short explanation.
## How it answers
1. Your question is turned into a plan and then into queries against **our
own query API**: the same aggregate, timeseries and breakdown
operations as the [API](/docs/api/stats). It never runs raw SQL.
2. The answer includes **How I got this**, with the exact queries. Open
them as a dashboard view to check or continue.
Suggested prompts relate to the page you're on. It can also explain a
metric, draft a goal or funnel for you to confirm, write a weekly summary
and check an installation.
## Privacy
- Runs on a US LLM endpoint with **zero data retention**. Your data is
never used for training.
- Only aggregated results of your queries are sent to the model, never raw
events.
- Your prompts and answers are kept for 30 days as your history, and you
can delete them.
## Limits
Questions per month depend on your plan: 20 on Free, 300 on Pro and 2,000
on Business. See [Plans](/docs/billing/plans).
---
Source: https://privatusanalytics.com/docs/dashboard/custom-dashboards
# Custom dashboards across your sites
> Build custom dashboards from metric, chart, breakdown, goal, funnel, live visitor, uptime and Web Vitals cards, mixing any sites you can access in a workspace.
A custom dashboard is a named page of cards. Each card is a small report
for one site, and one dashboard can mix cards from any sites you can
access in the workspace, for example one dashboard per team or client.
Open **Dashboards** in the Workspace section of the sidebar. The list is
sorted by name and shows how many cards each dashboard has. Dashboards
belong to the workspace, so every member who can read analytics sees the
same list.
## Creating and editing
Click **New dashboard** (or press `N` on the list). On a dashboard, click
**Edit** (or press `E`) to change it, or **Delete** to remove it after a
confirmation.
1. Give the dashboard a **name** (required, up to 100 characters).
2. Click **Add card** and choose the card's type and site. The title is
optional (up to 80 characters). Without one, the card is headed with
its type.
3. Set the options for that type. The form shows only the options the
chosen type uses.
4. Use the arrow buttons to move a card up or down, and the remove button
to drop it. Cards appear on the dashboard in the order of the list.
5. Click **Save dashboard**.
A dashboard holds up to 40 cards. At 40, **Add card** is turned off.
> **Tip:** `N` and `E` are part of the
> [keyboard shortcuts](/docs/dashboard/keyboard-shortcuts), which you can
> turn off in your [account settings](/docs/dashboard/account-settings).
## Card types
| Type | What it shows | Options |
|---|---|---|
| **Metric** | One metric for the period, the change against the previous period and the previous value | Period, metric |
| **Chart** | One metric over time. On wide screens it takes two columns | Period, metric |
| **Breakdown** | The top 5 values of one dimension, with visitors (pageviews for pages, completions for events) | Period, breakdown |
| **Goals** | Up to 5 of the site's [goals](/docs/features/goals), most completions first, with their conversions | Period |
| **Live visitors** | Visitors in the last 5 minutes | None |
| **Funnel** | A [funnel](/docs/features/funnels)'s overall conversion rate, and the count and conversion rate at each step | Period, funnel id (optional) |
| **Uptime** | Up to 5 of the site's [uptime checks](/docs/features/uptime), with their status and uptime over the last 7 days | None |
| **Web Vitals** | The 75th percentile and rating of LCP, INP, CLS, FCP and TTFB. See [Performance](/docs/features/performance) | Period |
The **breakdown** option offers Page, Channel, Referrer, UTM source, UTM
campaign, Country, Device, Browser, Operating system, Entry page and
Event. It starts on Page.
The **funnel id** is the funnel's id, which starts with `fun_`. Leave it
empty and the card shows the site's oldest funnel.
## Periods and metrics
Each card has its own period, counted in its site's timezone. Choose any
[date range preset](/docs/dashboard/date-ranges#presets), from Today to
All time. The default is Last 30 days. Custom date ranges, filters and
segments are not part of a card.
Metric and Chart cards show one metric: Visitors (the default), Visits,
Pageviews, Views / visit, Bounce rate, Visit duration or Revenue (in the
site's currency).
The numbers come from the same reports as the site's own pages, so a card
and the site's [Overview](/docs/dashboard/overview) agree for the same
period. See [Metrics](/docs/metrics) for how each one is counted.
## Permissions
| Action | Permission | Built-in roles |
|---|---|---|
| View the list, a dashboard and its cards | `analytics.read` | Owner, Admin, Editor, Analyst, Viewer |
| Create, edit and delete dashboards | `content.write` | Owner, Admin, Editor, Analyst |
See [Roles and permissions](/docs/teams/roles) for the full matrix.
Site access applies card by card:
- The site list in the form holds only the sites you can access. Saving a
new card for any other site is refused.
- A card for a site you can't access shows "You don't have access to this
card's site." in place of its data. The rest of the dashboard works as
usual.
- When you edit a dashboard, cards that a member with wider access added
are kept, even for sites you can't see.
## How cards load
The dashboard opens at once and each card then loads by itself as it
comes into view, so a slow card never holds up the others. Until its data
arrives, a card shows its title and "Loading…".
- The site name in a card's header opens that site's overview for the
card's period.
- A card with nothing to report says "Nothing to show for this card yet.",
for example a Funnel card on a site without funnels or an Uptime card
on a site without checks.
- Cards load once per page view. Reload the page for fresh numbers.
Cards sit in one column on phones, two on tablets and three on wide
screens.
## API
Dashboards are a REST resource under
`/workspaces/<workspace id>/dashboards` and MCP tools named `dashboards_*`
(`dashboards_list`, `dashboards_get`, `dashboards_create`,
`dashboards_update`, `dashboards_delete`). Dashboard ids start with
`dash_`. The [API reference](/docs/api) lists every input.
A card is an object with a `type`, a `site_id`, an optional `title` and
`params`:
```json
{
"name": "Client: Acme",
"cards": [
{ "type": "metric", "site_id": "pa_7Q2K9XH3AB",
"params": { "period": "7d", "metric": "pageviews" } },
{ "type": "breakdown", "site_id": "pa_7Q2K9XH3AB", "title": "Countries",
"params": { "dimension": "country", "limit": 10 } }
]
}
```
| `type` | `params` |
|---|---|
| `metric` | `period`, `metric` |
| `chart` | `period`, `metric`, `interval` |
| `breakdown` | `period`, `dimension`, `limit` |
| `goal` | `period`, `limit` |
| `funnel` | `period`, `funnel_id` |
| `live` | None |
| `uptime` | `limit` |
| `vitals` | `period` |
- `limit` is the number of rows, from 1 to 10 (default 5).
- `dimension` takes any [dimension](/docs/api/filters#dimensions),
including `prop:<key>`.
- `interval` takes the chart [intervals](/docs/dashboard/date-ranges#intervals)
(default `auto`).
- Params a type does not use are dropped. A card with an unknown type,
period, metric or dimension is refused, and the error names the card's
position.
- Sending `cards` in an update replaces the whole list.
> **Note:** The form has no fields for `limit` and `interval`, so saving
> a dashboard from the form resets them to their defaults.
`GET /workspaces/<workspace id>/dashboards/<dashboard id>/cards/<index>`
(MCP: `dashboards_card`) returns the data for one card, counting from 0.
Its `status` is `ok`, `no_access` or `not_available`.
---
Source: https://privatusanalytics.com/docs/dashboard/keyboard-shortcuts
# Dashboard keyboard shortcuts
> Every keyboard shortcut in the Privatus Analytics dashboard: date range presets, comparison, filters, segments, the Live page, and how to turn hotkeys off.
Press `?` in the app to open this list. Shortcuts can be turned off in
**Account settings → Preferences**.
On the dashboard:
| Key | Action |
|---|---|
| `T` | Today |
| `Y` | Yesterday |
| `W` | Last 7 days |
| `M` | Last 30 days |
| `Q` | Quarter to date |
| `A` | All time |
| `C` | Toggle comparison |
| `F` | Add a filter |
| `S` | Segment picker (when the site has segments) |
| `L` | Live |
| `Esc` | Clear filters |
| `?` | This list |
On list pages (goals, funnels, notes, alerts and others), `N` creates a new
item. On a custom dashboard, `E` edits it.
In these docs, `/` focuses the search box.
---
Source: https://privatusanalytics.com/docs/dashboard/site-settings
# Site settings reference
> A guide to every site settings tab: domains, tracking snippet, privacy, traffic and bot rules, goals, channels, alerts, sharing, integrations and deletion.
**Settings** at the end of a site's section in the sidebar opens the
site's settings, split into 16 tabs. Opening them needs the
`sites.manage` permission (Owner, Admin and Editor). Most settings are
also [API operations](/docs/api) with the same permission.
| Tab | What's there |
|---|---|
| [**General**](/docs/dashboard/site-settings#general) | Name, primary domain, additional domains (combined or separate), timezone, currency, week start, labels, site id |
| [**Tracking**](/docs/dashboard/site-settings#tracking) | Snippet generator, platform guides, **Verify installation**, [server ingest key](/docs/server-side/ingest-keys), Web Vitals sample rate |
| [**Privacy**](/docs/dashboard/site-settings#privacy) | [DNT/GPC handling](/docs/privacy/dnt-gpc), query parameter allowlist, path masking rules, [PII scrubber](/docs/privacy/pii-scrubbing) and custom rules, redaction log (counts only), data retention |
| **Traffic rules** | Block or allow lists for hostnames, paths, referrers, countries, IP ranges, user agents and events, with a live test box. See [Traffic rules](/docs/privacy/traffic-rules) |
| **Bots** | Bot filtering on/off, 30-day bot summary by reason and country, and how many visits had [no input seen](/docs/server-side/bots#visits-with-no-input-seen). Block a spam referrer with a [traffic rule](/docs/privacy/traffic-rules). See [Bot rules](/docs/server-side/bots) |
| **Goals** / **Funnels** | Your [goals](/docs/features/goals) and [funnels](/docs/features/funnels), with links to create and manage them |
| **Events & properties** | Links to manage events (rename, merge, hide, delete) and property settings. See [Events explorer](/docs/dashboard/events#managing-events) |
| **Channels** | Custom [channel rules](/docs/metrics/channels#custom-channel-rules) with a preview |
| **Notes** | Recent [notes](/docs/dashboard/notes) and a ready-to-copy deploy note command |
| **Alerts** | This site's [alert rules](/docs/reports/alerts) and where they're sent |
| **Sharing** | [Public and password links, embeds, badges](/docs/reports/sharing), and a link to wallboard links |
| [**Integrations**](/docs/dashboard/site-settings#integrations) | [Search Console and Bing](/docs/features/search-console) connection status, plus links to webhooks, notification channels (Slack, Teams and more), API tokens, warehouse export, [AI crawler logs](/docs/features/ai-crawlers) and uptime |
| **Imports** | Recent [GA4 and CSV imports](/docs/reports/imports) and a link to start one |
| [**Access**](/docs/dashboard/site-settings#access) | Which members can see this site |
| [**Danger zone**](/docs/dashboard/site-settings#danger-zone) | Transfer the site to another workspace, reset data for a date range, delete the site |
## General
The site's identity and the defaults its reports use. One **Save** button
stores the whole tab.
| Field | What it does |
|---|---|
| **Name** | The name shown in the sidebar, on [All sites](/docs/dashboard/all-sites) and in reports. Up to 100 characters |
| **Primary domain** | The site's main hostname, for example `example.com`. A pasted URL is reduced to its hostname. A domain can belong to only one active site |
| **Timezone** | The timezone that days and date ranges are counted in. Changing it regroups all history at once. See [Timezones](/docs/troubleshooting/timezones) |
| **Currency** | A three-letter code such as `USD`. [Revenue](/docs/events/revenue#multi-currency) sent in another currency is converted to it. A new site starts with the workspace's currency |
| **Week starts on** | Monday or Sunday |
| **Additional domains** | Other hostnames that send data to this site, one per line or separated by commas |
| **Multiple domains** | **Combined** (the default): one visit can span all the domains, and reports show them together. **Separate**: each domain starts its own visits, and you compare them with a hostname filter |
| **Labels** | Comma separated tags. Filter sites by label on the All sites page |
| **Site id** | The `pa_…` id used in the snippet's `data-site` and in API paths, with a **Copy** button. It never changes |
Hits are accepted only from the primary domain, the additional domains
and any of their subdomains (`www.`, `shop.` and so on). Hits from other
hostnames are dropped. [Cross-domain and subdomains](/docs/troubleshooting/cross-domain)
explains when to combine domains and when to create separate sites.
Through the API, these are fields of `PATCH /sites/<site id>` (MCP:
`sites_update`).
## Tracking
Everything needed to get data in: the snippet, install help, a check that
it works, the key for server-side events and Web Vitals sampling.
### Snippet generator
Choose options and the snippet below them updates. Paste it into the
`<head>` of every page. Each option becomes one attribute of the script
tag:
| Option | Attribute | Effect |
|---|---|---|
| **Modules** | `data-modules` | `engage` (time on page and scroll depth, on by default), `auto` (outbound links, file downloads, form submits and 404s), `vitals` (Core Web Vitals, sampled) and `clicks` (aggregate element click counts). See [Modules](/docs/tracker/modules) |
| **Single-page apps** | `data-spa` | Automatic (history and hash, the default), History API only, Hash routing (keeps the `#fragment`) or Off. See [Single-page apps](/docs/tracker/spa) |
| **Manual pageviews only** | `data-manual` | The script sends no pageview by itself. See [Manual mode](/docs/tracker/manual-mode) |
| **Only track on hostnames** | `data-domains` | Runs the tracker only on the hostnames you list |
| **Exclude paths** | `data-exclude` | Skips matching paths, for example `/admin/*, /preview/*` |
| **Keep query parameters** | `data-params` | Sends the listed query parameters with page URLs, for example `page, ref`. They are stored only when the [Privacy](/docs/dashboard/site-settings#privacy) tab allows them too |
| **Mask paths** | `data-mask` | Rewrites paths in the browser, for example `/u/*->/u/:id` |
The last four are covered in
[Exclusions and masking](/docs/tracker/exclusions-and-masking), and
[Script attributes](/docs/tracker/attributes) lists every attribute.
> **Note:** The generator only builds a snippet. Its choices are not
> saved with the site, so the form is back on the defaults the next time
> you open the tab. What counts is the snippet on your pages.
### Platform guides
Short steps and ready code (already holding your site id) for HTML,
WordPress, Shopify, Webflow, Next.js, Nuxt, Google Tag Manager, Ghost,
Squarespace, Wix and Framer. The [install guides](/docs/install) cover
these and more platforms in detail.
### Verify installation
Enter a page URL (the homepage is filled in) and click **Verify**. We
fetch the page and report whether the script is there, whether it carries
this site's id, and whether a Content-Security-Policy or Referrer-Policy
header gets in the way. The URL must be on the site's primary or
additional domains. The section shows when the site was last verified.
See [Verify your installation](/docs/getting-started/verify-installation).
### Server ingest key
The key for sending events from your servers to `POST /api/events`.
- **Create key** shows the key once, with a ready `curl` example. We store
only a hash of it, and afterward the tab shows just the key's prefix.
- **Rotate key** replaces it. The old key stops working immediately.
- **Revoke** removes it.
See [Ingest keys](/docs/server-side/ingest-keys).
### Web Vitals sampling
**Sample rate (%)** is the share of page loads that report Core Web
Vitals when the `vitals` module is on. Free: up to 10%. Paid plans: any
rate up to 100%. If the workspace moves to a plan with a lower maximum,
that maximum applies without editing the site. Web Vitals don't count
toward your event allowance. See
[Performance](/docs/features/performance).
Through the API: `GET /sites/<site id>/tracking/snippet`
(`tracking_snippet`), `POST /sites/<site id>/tracking/verify`
(`tracking_verify`), `POST` and `DELETE /sites/<site id>/tracking/ingest_key`
(`tracking_ingest_key_rotate`, `tracking_ingest_key_revoke`), and the
`vitals_sample_rate` field of `sites_update`.
## Privacy
What is dropped, shortened or redacted before anything is stored, and how
long data is kept. The first four sections are one form with a single
**Save** button. Signals, URL rules and the scrubber apply to hits
received after you save. Stored data is not rewritten.
### Visitor signals
| Setting | Default | Effect |
|---|---|---|
| **Honor Global Privacy Control (GPC)** | On | Hits from browsers that send GPC are dropped |
| **Honor Do Not Track (DNT)** | Off | Hits from browsers that send DNT are dropped |
See [DNT and GPC](/docs/privacy/dnt-gpc).
### URLs
- **Allowed query parameters**: comma separated, for example
`page, lang`. Query strings are removed before storage, except UTM
tags, `ref` and the parameters you allow here. The tracker also removes
other parameters in the browser, so list the same names in the
snippet's
[`data-params`](/docs/tracker/exclusions-and-masking#keep-query-parameters-data-params).
- **Path masks**: rows of a pattern and a replacement. A `*` matches
exactly one path segment, so the pattern `/u/*/settings` with the
replacement `/u/:id/settings` stores every user's settings page as one
path. The first mask that matches a path is used. **Add mask** adds a
row.
Path masks are applied on our servers. The snippet's `data-mask` does
the same in the browser, before the path is sent.
### PII scrubber
**Scrub personal data** (on by default) redacts personal data from
paths, referrers and event properties before storage. The tab lists the
built-in rules, which [PII scrubbing](/docs/privacy/pii-scrubbing)
describes one by one.
**Custom redaction rules** add your own: a rule name and a regular
expression per row, for example `order_id` and `ORD-\d{6}`. Matches are
replaced with `[redacted]`. A pattern that is not a valid regular
expression is refused when you save.
### Data retention
Data older than the chosen age is deleted automatically, once a day.
| Choice | Meaning |
|---|---|
| **Plan default** | Keep data as long as the plan allows |
| 3, 6, 12, 13, 24, 36 or 60 months | Delete this site's data sooner than the plan would |
Only ages within the plan's limit are offered. Free: up to 6 months. Paid
plans keep data without a limit, so every choice is available. The age
in force is always the shorter of this setting and the plan's limit.
### Redaction log
How often each scrubber rule redacted something in the last 30 days. The
redacted values themselves are never stored.
Through the API, the privacy settings are the `honor_gpc`, `honor_dnt`,
`allowed_params`, `path_masks`, `pii_scrubber`, `redaction_rules` and
`retention_months` fields of `sites_update`.
## Integrations
This tab has nothing to save. It shows what the site is connected to and
links to the tools that work with it.
**Search Console and Bing** lists Google Search Console and Bing
Webmaster Tools, each with the connected property or "Not connected".
**Connect** (or **Open**) goes to the site's Search page for that
provider. See [Search Console and Bing](/docs/features/search-console).
**More integrations** links to:
| Link | What it is | Guide |
|---|---|---|
| **Webhooks** | Send workspace events to your own endpoint | [Webhooks](/docs/api/webhooks) |
| **Notification channels** | Email, Slack, Teams, Discord and more, used by alerts | [Alerts](/docs/reports/alerts) |
| **API tokens and MCP** | For the JSON API and AI agents | [Authentication](/docs/api/authentication), [MCP](/docs/mcp) |
| **Warehouse export** (Business) | Daily export to S3, BigQuery or Snowflake | [Exports](/docs/reports/exports) |
| **AI crawlers** | Server log ingest for AI crawler visits | [AI crawlers](/docs/features/ai-crawlers) |
| **Uptime checks** | Monitor this site and its SSL certificate | [Uptime](/docs/features/uptime) |
The first four open workspace pages, which need their own permissions.
The last two open pages of this site. Plugins for WordPress, Shopify,
Cloudflare, Google Tag Manager and more are in the
[install guides](/docs/install).
## Access
**Who can see this site**, member by member. Using it needs the
`members.manage` permission (Owner and Admin). Without it, the tab shows
a message instead of the list.
| Column | Shows |
|---|---|
| **Member** | Name and email |
| **Role** | The member's role, with "all sites" when they see every site |
| **Can see this site** | A checkbox, or **Always** for owners and admins |
- Owners and admins see every site. Their access can't be removed here.
- Other members see either all sites or only the sites granted to them.
- Ticking or clearing a checkbox saves at once.
- Clearing it for a member with "all sites" switches them to a list of
the workspace's other sites. From then on, new sites are not added to
their list automatically.
- You can't change a member who holds permissions you don't have.
A member without access to a site can't see it anywhere, including in
lists, exports and the API. See [Roles and permissions](/docs/teams/roles)
and [Teams](/docs/teams).
Through the API: `GET` and `PATCH /sites/<site id>/access` (MCP:
`sites_access_list`, `sites_access_update`).
## Danger zone
- **Transfer**: send the site to another workspace. Someone with
permission there accepts. The site id, data and settings move with it,
so the snippet doesn't change.
- **Reset data** deletes events for a date range. It can't be undone.
- **Delete site**: confirm by typing the domain. The site is soft-deleted
for 7 days (collection stops), then permanently deleted.
---
Source: https://privatusanalytics.com/docs/dashboard/workspace-settings
# Workspace settings reference
> Manage workspace settings: members and roles, security and 2FA enforcement, SSO, billing, API tokens, webhooks, the audit log and white label branding.
| Page | What's there |
|---|---|
| **General** | Name, default timezone and currency, workspace id (`ws_…`), and **Delete workspace** (7-day soft delete) |
| **Members** | Members with role, site access, 2FA status and last activity. Invite, change role, remove, transfer ownership. See [Teams](/docs/teams) |
| **Roles** | Built-in roles and, on Business, [custom roles](/docs/teams/roles#custom-roles) |
| **Security** | Enforce 2FA (Business), allowed sign-in methods, session lifetime, IP allowlist for the app (Business), support access |
| **SSO** (Business) | [SSO](/docs/teams/sso) with SAML or OIDC, email domains and [SCIM](/docs/teams/scim) |
| **Billing** (sidebar) | Plan, usage meter with forecast and per-site breakdown, change plan, payment method, billing emails, tax id, invoices, cancel. See [Billing](/docs/billing) |
| **API tokens** | Create, view last use, revoke. See [Authentication](/docs/api/authentication) |
| **Webhooks** | Endpoints, events, signing secret, delivery log with retry. See [Webhooks](/docs/api/webhooks) |
| **Audit log** | Who did what, when. See [Audit log](/docs/teams/audit-log) |
| **White label** (Business) | Brand name, logo and accent color on shared dashboards, embeds and email reports, and an option to hide Privatus Analytics branding. See [White label](/docs/reports/white-label). Custom dashboard domains and email sender domains are not available |
The DPA, subprocessor list and SCCs are on the
[legal pages](/legal). See [Privacy & compliance](/docs/privacy).
---
Source: https://privatusanalytics.com/docs/dashboard/account-settings
# Account settings and preferences
> Manage your Privatus Analytics account: profile, password, passkeys, two-factor sign-in, theme, timezone, email preferences, data download and deletion.
These settings belong to you, not to a workspace. Click your name at the
bottom of the sidebar to open them. The page has three tabs: **Profile &
preferences**, **Security** and **Affiliate program** (see
[Affiliates](/docs/billing/affiliates)).
| Section | What's there |
|---|---|
| **Profile** | Name, email and timezone. A new email address takes effect once you open the confirmation link sent to it |
| **Security** | Password, authenticator app with recovery codes, passkeys, signed-in browsers, login history and connected Google and GitHub accounts. See [Security](/docs/dashboard/account-settings#security) |
| **Preferences** | Theme (system, light or dark), the page that opens after you log in (All sites or the last site you viewed), language, keyboard shortcuts on or off, reduce motion |
| **Email** | Product updates and tips, marketing emails such as onboarding tips, and the monthly newsletter. Alerts and email reports are set up per workspace, and account and security emails are always sent |
| **Your data** | Download a copy of your account data (JSON), or delete your account |
Profile, Preferences and Email are one form on the first tab, saved with
a single **Save** button. The language applies to the app while you're
signed in. Public pages use the language in their address.
## Security
**Account settings → Security** holds everything about how you sign in.
It only works in a signed-in browser, not with an API token.
| Section | What you can do |
|---|---|
| **Password** | Change your password by entering the current one and a new one of at least 10 characters. Your other browsers are signed out when it changes. If you signed up with a login link, Google or GitHub and have no password, use **Set a password by email** |
| **Authenticator app (2FA)** | Turn on a second step at login with an app such as 1Password, Authy or Google Authenticator. When it's on, the section shows how many recovery codes you have left, **New recovery codes** replaces them, and **Turn off** asks for your password |
| **Passkeys** | Add a passkey (Touch ID, Face ID, Windows Hello or a security key) under a name of your choice. A passkey signs you in and also counts as a second factor. The list shows when each was added and last used, with **Remove** |
| **Signed-in browsers** | Every browser where you're signed in, with its browser and operating system, IP address, when it signed in and when it was last active. **Sign out** ends that session. The one you're using is marked **This browser** |
| **Login history** | The last 30 days of sign-ins (up to 50): time, browser, IP address and whether the session is still active or signed out |
| **Connected accounts** | Connect or disconnect Google and GitHub as ways to sign in, with the date each was connected |
[Two-factor authentication](/docs/teams/two-factor) walks through setting
up an authenticator app, recovery codes and passkeys.
If a workspace you belong to requires two-factor authentication and you
have neither an authenticator app nor a passkey, a notice at the top of
the page names the workspace and asks you to set one up.
> **Note:** The IP addresses on this page are your own sign-ins, kept for
> account security. Visitors' IP addresses are never stored.
## Deleting your account
**Delete account** is at the bottom of the first tab. Type your email
address to confirm. Deleting removes your login, memberships, API tokens
and passkeys.
The form lists the workspaces you own. They are deleted with your
account, and their subscriptions are canceled. If one of them has other
members, either transfer ownership to another member first (the form
links to the Members page) or tick **Also delete the workspaces I own
that have other members**.
## API
Your profile, preferences and email settings are `GET` and
`PATCH /account` (MCP: `account_get`, `account_update`). The
[API reference](/docs/api) lists every input.
Changing the email address, turning marketing emails back on, deleting
the account and everything on the Security tab need a signed-in browser.
An API token can't do them.
---
Source: https://privatusanalytics.com/docs/dashboard/help-and-feedback
# Help and feedback
> How to ask the Privatus Analytics team a question or send feedback from the dashboard, what is sent with your message, and how the reply reaches you.
**Help & Feedback** is at the bottom of the left menu on every page of the
app. It opens a small form with a subject and a message. Use it to ask a
question, report a problem or tell us what you would like to see.
## What happens when you send
1. Your message is emailed to the Privatus Analytics team at
`hello@privatusanalytics.com`.
2. You get an email right away that confirms we received it.
3. A person replies to the email address of your account.
You can send up to 10 messages a day.
## What is sent with your message
So that you don't have to explain who you are, the message includes
details of your account:
- Your name, email address and user id.
- The page you sent the message from.
- Each workspace you belong to: its name and id, your role, the plan,
the subscription and billing state, this month's usage and its sites.
Nothing about your visitors is included, and the message is not stored in
the app. It lives in our mailbox, like any other email you send us.
## From the API or an AI agent
The same operation is in the JSON API (`POST /help.json`) and is the
`support_message_send` MCP tool. Both take `subject` and `message`. See
the [API reference](/docs/api).
---
Source: https://privatusanalytics.com/docs/metrics
# Analytics metrics and definitions
> How every metric in Privatus Analytics is calculated: visitors, visits, pageviews, bounce rate, visit duration, conversions, revenue, Web Vitals and uptime.
Every metric in the app has a tooltip with its definition and a link here.
See [How visitors are counted](/docs/metrics/how-visitors-are-counted) for
how visits and visitors are built without cookies.
| Metric | Definition |
|---|---|
| **Visitors** | Unique visitors per day, summed over the days in the range ("visitor-days"). Someone who visits on Monday and Tuesday counts twice in a weekly total. We can't deduplicate visitors across days, by design |
| **Visits** (sessions) | A series of hits from one visitor with less than 30 minutes of inactivity between them, ending at midnight UTC at the latest |
| **Pageviews** | Page loads plus single-page-app route changes |
| **Views per visit** | Pageviews ÷ visits |
| **Bounce rate** | The share of visits with **one pageview, no custom event, and less than 10 seconds of engaged time**. Stricter than most tools, so a reader who spends three minutes on one article isn't a bounce |
| **Visit duration** | Engaged (visible) time across the visit, from the first hit to the last engagement ping, capped at 4 hours. Shown as the **median** |
| **Time on page** | Visible engaged time on a page, as a median. Includes the last page of a visit (measured when the page is hidden or closed) |
| **Scroll depth** | The deepest scroll on a page view, in 10% bands. Reported as the median and as the share of views reaching 25, 50, 75 and 100% |
| **Entry page / exit page** | The first / last page of a visit |
| **Entry rate** | Visits that started on a page ÷ its pageviews |
| **Exit rate** | Exits from a page ÷ its pageviews |
| **Conversions** | Visits in which a goal was completed at least once |
| **Conversion rate** | Conversions ÷ visits |
| **Goal completions** | Every time the goal was completed, including repeats in one visit |
| **Revenue** | The sum of `revenue`, converted to the site currency at the ECB reference rate of the event's date. Original currencies are kept for breakdowns |
| **Live visitors** | Distinct visits with a hit in the last 5 minutes |
| **Web Vitals** | The 75th percentile (p75) of each metric (LCP, INP, CLS, FCP, TTFB), plus the share of good / needs improvement / poor by Google's thresholds |
| **Uptime** | Successful check intervals ÷ all intervals. An interval is down when most probe locations fail |
"Engaged time" needs the `engage` [module](/docs/tracker/modules), which
is on by default. Without it, visit duration and time on page are zero and
bounce rate counts every single-page visit without an event.
## Freshness
New events appear in reports within seconds (the target is 10 seconds at
the 95th percentile). The Live page reads the stream directly and updates
in about 2 seconds.
## Totals in breakdowns
In breakdown panels, the **share** column is each row's share of the rows
shown. Visit-based totals of a breakdown can add up to more than the
headline number: one visit can have several pages, and a visitor-day can
count under several countries if they travel.
## Filtering
Filters don't change definitions, only which visits and events count. See
[Filters and segments](/docs/dashboard/filters-and-segments).
## More
- [How visitors are counted](/docs/metrics/how-visitors-are-counted)
- [Why numbers differ from GA4](/docs/metrics/ga4-differences)
- [Channels](/docs/metrics/channels): how traffic sources are classified.
---
Source: https://privatusanalytics.com/docs/metrics/how-visitors-are-counted
# How visitors are counted
> How Privatus Analytics counts visitors and visits without cookies: a daily salted key computed in memory, random visit ids, and what that means for accuracy.
Privatus Analytics counts real visits and daily unique visitors without cookies,
without storing anything on the visitor's device, and with nothing that
persists or links across days.
## The daily visit key
1. Every UTC day we generate a random 256-bit **salt**. It exists only in
memory (Redis without persistence) and is destroyed shortly after the
day ends.
2. For each hit, `key = HMAC(daily_salt, site, IP, User-Agent)`, computed
in memory during the request.
3. The key is looked up in an in-memory store. If it's new, we start a
visit with a **random id** that is *not* derived from the key. Entries
expire after 30 minutes of inactivity and never outlive the UTC day.
4. The stored event has the random visit id and flags such as "first visit
today". The key, the IP and the raw User-Agent are never stored, logged
or queued.
After midnight the salt is gone, so nobody (including us) can recompute a
key or link a stored visit to a person or to another day.
## Visits, visitors and bounces
- **A visit** ends after 30 minutes without a hit, or at midnight UTC,
whichever comes first.
- **A visitor** is counted once per site per UTC day, on their first visit
of the day. The same browser the next day is a new visitor, so a weekly
total counts "visitor-days".
- **A bounce** is a visit with one pageview, no custom event and less than
10 seconds of engaged time.
Funnels, journeys, entry and exit pages, and the pages viewed before a
conversion are all built from these visits. Server-side events join the
same visits (see [server-side sessions](/docs/server-side/sessions)).
## What this means for accuracy
- Visitors can't be deduplicated across days, by design. Someone who
visits on Monday and Tuesday counts twice in a weekly total.
- Two people behind the same IP address with the same browser version
(an office network, for example) can be counted as one visitor.
- A visitor whose IP address changes during the day (switching from Wi-Fi
to mobile data) can be counted twice.
- A visit that spans midnight UTC is split into two.
See [why numbers differ from GA4](/docs/metrics/ga4-differences) for how
this compares with cookie-based tools.
## Your privacy policy
The IP address and User-Agent are processed transiently to build the daily
pseudonymous key, which you should mention in your privacy policy (see
[templates](/docs/privacy/policy-templates)).
---
Source: https://privatusanalytics.com/docs/metrics/ga4-differences
# Why numbers differ from Google Analytics 4
> Why Privatus Analytics and Google Analytics 4 report different numbers: consent banners, ad blockers, visitor and bounce definitions, bots and timezones.
It's normal for Privatus Analytics and GA4 to disagree, often by 10 to 50%. The main
reasons, roughly in order of size:
## 1. Consent banners
GA4 usually runs only after a visitor accepts cookies. Depending on your
banner and audience, 30 to 70% of visitors in Europe decline or ignore it.
With Consent Mode, GA4 models some of the missing data, which adds
estimates on top. Privatus Analytics doesn't need consent in most setups, so it
counts visitors GA4 never sees.
## 2. Ad and tracking blockers
Blockers stop GA4 more often than Privatus Analytics, but some blockers stop
Privatus Analytics too, so both tools can undercount. See
[Ad blockers](/docs/troubleshooting/ad-blockers).
## 3. Different definitions
| | Privatus Analytics | GA4 |
|---|---|---|
| Users / visitors | Unique **per day**, summed over the range | Unique over the whole range, based on a cookie or signed-in user id |
| Sessions / visits | 30 min inactivity, ends at midnight UTC, no campaign-based restarts | 30 min inactivity, can span midnight |
| Bounce | 1 pageview **and** no event **and** < 10 s engaged | Not "engaged": < 10 s, no conversion, one page |
| Engagement time | Visible time only | Foreground time |
Because visitors are counted per day, **weekly and monthly visitor totals
are higher** in Privatus Analytics than GA4's users for the same people. Compare
daily numbers, or pageviews, for a fair check.
## 4. Bot filtering
Both filter bots, with different lists. Privatus Analytics also filters data-center
traffic and headless browsers by default, and shows how many hits it
removed in the Overview's footer.
## 5. Timezones and date boundaries
Check that both tools use the same timezone. See
[Timezones](/docs/troubleshooting/timezones).
## 6. Where the script runs
Make sure both scripts are on the same pages. Single-page apps, excluded
paths, staging hostnames and [Google Tag Manager](/docs/install/google-tag-manager)
triggers often differ.
## A fair comparison
Pick one day, compare **pageviews** for a handful of top pages, with the
same timezone and hostname. Pageviews are the most comparable metric. The
remaining gap is mostly consent and blockers.
To bring your GA4 history over, see [Imports](/docs/reports/imports).
---
Source: https://privatusanalytics.com/docs/metrics/channels
# Traffic channels and sources
> How Privatus Analytics classifies every visit into a traffic channel from UTM parameters and the referrer, including AI assistants and custom channel rules.
Every visit gets one **channel**, from the landing page's campaign
parameters and the referrer. Rules are checked in this order, and the first
match wins.
| Channel | Rule |
|---|---|
| `paid_search` | A paid click id (gclid, msclkid…) or paid `utm_medium` from a search engine |
| `paid_social` | A paid click id or paid `utm_medium` from a social network |
| `paid_other` | Any other paid traffic. Paid mediums: cpc, ppc, paid, paidsearch, paid_search, cpm, cpv, display, banner, affiliate, paid_social, paidsocial |
| `email` | `utm_medium` containing email, or `newsletter`. Webmail: mail.google.com, outlook.live.com, outlook.office.com, mail.yahoo.com, mail.proton.me, app.fastmail.com, mail.aol.com |
| `ai_assistants` | Any `.ai` referrer, chatgpt.com, chat.openai.com, perplexity.ai, claude.ai, gemini.google.com, bard.google.com, copilot.microsoft.com, you.com, phind.com, meta.ai, grok.com, chat.mistral.ai, chat.deepseek.com, poe.com. Also utm_source chatgpt, chatgpt.com, openai, perplexity, claude, gemini, copilot, grok, deepseek, mistral |
| `organic_search` | google, bing, duckduckgo, yahoo, yandex, baidu, ecosia, qwant, startpage, brave, naver, seznam, ask, aol, search.yahoo, kagi, mojeek, sogou, so.com. Also utm_medium organic, search |
| `organic_social` | facebook.com, instagram.com, t.co, twitter.com, x.com, linkedin.com, lnkd.in, reddit.com, youtube.com, tiktok.com, pinterest.com, snapchat.com, threads.net, bsky.app, mastodon.social, news.ycombinator.com, whatsapp.com, telegram.org, discord.com, quora.com, tumblr.com, vk.com, weibo.com, producthunt.com. Also utm_medium social, social_media, sm, social-network |
| `internal` | A referrer on one of the site’s own domains |
| `referral` | Any other referrer or `utm_source` |
| `direct` | No referrer and no campaign parameters |
Click ids (`gclid`, `gbraid`, `wbraid`, `msclkid`, `fbclid`, `ttclid`,
`li_fat_id`, `twclid`, `dclid`) mark a visit as a paid click. They're kept
only as a yes/no flag. The id itself is discarded.
## Referrers, sources and campaigns
- **Referrer** is the hostname the visitor came from, with `www.` and `m.`
removed. The referrer's query string is never stored. Referrers from the
site's own domains are *internal* and don't start a new source.
- **UTM parameters** (`utm_source`, `utm_medium`, `utm_campaign`,
`utm_content`, `utm_term`) come from the landing page URL.
- **`ref`** is taken from `ref`, `via` or `source` query parameters.
A visit keeps the source it started with (first touch): later pages of the
same visit don't change it.
## Custom channel rules
**Site settings → Channels** lets you add your own rules, checked before
the built-in ones. Each rule has a channel name and one or more conditions
(all must match) on:
- `referrer_host`, `utm_source`, `utm_medium`, `utm_campaign`, `ref`, `path`
- with `is`, `contains`, `starts_with` or `regex` (case-insensitive).
Example: channel **Partners** when `ref starts_with partner-`. Rules apply
to new visits. The preview shows how recent traffic would be classified.
---
Source: https://privatusanalytics.com/docs/features
# Goals, funnels and more reports
> An overview of the reports beyond the dashboard: goals, funnels, journeys, campaigns, A/B experiments, Web Vitals, uptime, Search Console and AI crawlers.
The reports beyond the Overview:
| Report | What it answers |
|---|---|
| [Goals](/docs/features/goals) | How many visits converted, and from where? |
| [Funnels](/docs/features/funnels) | Where do people drop out of a multi-step flow? |
| [Journeys](/docs/features/journeys) | What do people do before and after a page? |
| [Campaigns](/docs/features/campaigns) | Which campaigns pay off, including cost, CPA and ROAS? |
| [Experiments](/docs/features/experiments) | Which variant converts better, and is it significant? |
| [Performance](/docs/features/performance) | How fast do pages feel to real visitors (Web Vitals)? |
| [Uptime](/docs/features/uptime) and [status pages](/docs/features/status-pages) | Is the site up, and how do we tell customers? |
| [Search Console](/docs/features/search-console) | Which search queries bring visits that convert? |
| [AI crawlers](/docs/features/ai-crawlers) | Which AI bots read the site, and which pages? |
| [Click maps](/docs/features/click-maps) | Which elements get clicked? |
---
Source: https://privatusanalytics.com/docs/features/goals
# Conversion goals
> Set up conversion goals for page visits, custom events, engagement, outbound clicks and file downloads, with goal values, counting options and path matching.
A goal marks a visit as **converted**. Goals are definitions applied when
you query, so creating or editing one updates all your history
immediately.
## Goal types
| Type | Completes when | Settings |
|---|---|---|
| **Page visit** | A page matching the path is viewed | Path, match type, optional hostname |
| **Event** | A custom event with that name fires | Event name, optional property conditions |
| **Engagement** | A page view reaches a scroll depth or time on page | Paths, scroll ≥ X% or time ≥ N seconds |
| **Outbound click** | An `Outbound Link` event to a domain or URL pattern | Domain or URL |
| **File download** | A `File Download` event | Extension or path |
Outbound click and file download goals use the events of the
[`auto` module](/docs/tracker/modules#auto-automatic-events). Engagement
goals need the `engage` module.
### Path matching
| Match | Example | Matches |
|---|---|---|
| Exact | `/thank-you` | `/thank-you` only |
| Starts with | `/docs/` | Everything under `/docs/` |
| Glob | `/blog/*/subscribed` | `*` stands for any characters |
| Regex | `^/(signup\|register)/done$` | A regular expression |
### Property conditions
Event goals can require properties, all of which must match: `is`,
`is_not`, `contains`, `gt`, `lt`. For example `plan is pro` and
`revenue gt 100`.
## Value
- **None**.
- **Fixed**: a value per completion, e.g. $50 per demo request.
- **From revenue**: the event's `revenue`, converted to the site currency.
## Counting
- **Once per visit** (default): conversions and conversion rate count
visits.
- **Every time**: completions count each repeat.
Both numbers are always available: *conversions* are visits with the goal,
*completions* are all the times it happened.
## The goal list and detail
The list shows each goal's completions, conversions, conversion rate,
value, trend and status. Duplicate, archive (hides it without deleting) or
create an alert from its menu.
A goal's detail page charts completions and conversion rate over time,
with breakdowns by channel, campaign, entry page, country and device, the
pages viewed before converting, the median time to convert
within the visit, and a link to build a funnel ending in the goal.
## Limits
Free: 10 goals per site. Paid plans: unlimited.
## API
Goals are a REST resource under `/sites/<site id>/goals` and MCP tools
named `goals_*` (for example `goals_list`, `goals_create`). The
[API reference](/docs/api) lists every input.
---
Source: https://privatusanalytics.com/docs/features/funnels
# Conversion funnels
> Build conversion funnels from pages, events and goals, see how many visits complete each step and where the rest go, with breakdowns and time between steps.
## Build a funnel
**Funnels → New funnel** in the site menu (or Site settings → Funnels).
- **Steps:** 2 or more (up to 5 on Free, 10 on Pro, 20 on Business). Each
step is one of:
- a **page** (exact, starts with, glob or regex),
- an **event**, optionally with property conditions,
- an existing **goal**.
- **Names** for steps (optional).
- **Order:** *strict* (steps must happen in order) or *any* order.
- **Window:** within the same **visit**, or the same **day**.
Funnels are calculated at query time, so they work on your history too.
## The report
- A bar per step with the count, the conversion from the previous step,
the conversion from the first step, and the drop-off.
- The median time between steps.
- **Where they went instead**: click a drop-off to see the top next pages
of visits that didn't continue.
- Breakdown by channel, device, country, browser, OS, UTM source or UTM
campaign, and a comparison period.
## Limits
Free: 3 funnels per site, up to 5 steps. Pro: unlimited funnels, 10 steps.
Business: unlimited funnels, 20 steps.
---
Source: https://privatusanalytics.com/docs/features/journeys
# User journey paths
> Explore the most common paths visits take through your site as a flow diagram, forward from a page or back from a goal, without following any one person.
**Journeys** shows the most common paths through your site as a flow
diagram.
- **Forward:** pick a starting page (or *any entrance*) and see the three
steps that most often follow. Expand any node to go deeper.
- **Reverse:** pick an end page or a goal and see the three steps before
it.
- **Filters:** device and channel, plus the usual date range.
Journeys are built from visits: the order of pageviews inside a visit. A
visit never spans more than one day and isn't linked to other visits, so
you see how people move through the site without following any one person.
For large sites, paths are sampled over 100,000 visits, and the sample rate is
shown.
---
Source: https://privatusanalytics.com/docs/features/campaigns
# UTM campaign tracking
> Track UTM campaigns with visitors, conversions, revenue, cost, CPA and ROAS, build tagged links with the UTM builder, and clean up near-duplicate UTM values.
## Campaign report
**Campaigns** rolls UTM-tagged traffic up by campaign, then source and
medium, with visitors, visits, conversions, conversion rate, revenue and,
when you add costs, **cost**, **CPA** (cost per conversion) and **ROAS**
(revenue ÷ cost).
UTM values come from the landing page of each visit. Values are compared
as sent, so `Facebook` and `facebook` are reported as different values
(see [UTM hygiene](/docs/features/campaigns#utm-hygiene) below).
## Costs
In **Campaigns → Costs**, add spend per campaign per month by hand, or
upload a CSV with a header row and the columns `campaign`, `month`
(`YYYY-MM`), `amount` and, optionally, `currency` (the upload box shows
the exact template). A file can be up to 1 MB, and its first 5,000 rows
are imported.
Each campaign has one cost per month, so saving or importing the same
campaign and month again replaces the amount. The campaign name is
matched to `utm_campaign` without regard to case. Without a currency a
cost uses the site currency. Other currencies are converted to it for
the report. A month's cost is spread evenly over its days, so a report
for part of a month counts part of the cost.
## UTM builder
**Campaigns → UTM builder** builds a tagged link from a landing page URL
and the five UTM values, and shows the link as you type. The presets
(Newsletter, Social post, Paid search, Paid social, Print / QR and
Partner) fill in the usual source and medium.
**Check link** checks every value. Capital letters are lowercased and
spaces become underscores. A value that looks like **personal data** (an
email address, an id or a long number) is an error, and no link is built
until you remove it.
**Copy** the link, or use **Save to library** to keep it in the
[link library](/docs/features/campaigns#link-library).
## Link library
**Campaigns → Links** keeps the tagged links your team uses, so everyone
copies the same URL instead of typing UTM values again. Save one from the
UTM builder with **Save to library**, or start from **New link**.
| Field | Rules |
|---|---|
| **Name** | Required, up to 120 characters. A label for the library, not part of the URL |
| **Landing page URL** | Required. Starts with `https://` or `http://`, has no spaces and is up to 2,048 characters |
| **Source, Medium, Campaign, Content, Term** | Optional `utm_*` values. Saved in lowercase, with spaces turned into underscores, and cut at 255 characters |
| **Tags** | Optional, separated by commas. Saved in lowercase. A tag is cut at 40 characters and a link keeps its first 20 tags |
| **Notes** | Optional free text, for example where the link is used |
A link is not saved when its UTM values look like personal data (an
email address, an id or a long number).
### The tagged URL
Every saved link shows its **tagged URL**: the landing page URL with the
link's UTM parameters added. If the landing page URL already has one of
those parameters, the link's value replaces it. Other query parameters
are kept. **Copy** puts the tagged URL on your clipboard, from the list
or from the link's own page.
### Search and tags
The list shows the newest links first. Search matches the name, the
landing page URL and the campaign. Choose a tag from the menu, or click
a tag on a link, to see only the links with that tag.
### QR codes
**QR code** on a link shows a code for its tagged URL, for posters,
flyers and packaging. **Download SVG** saves it as a vector file, which
scales to any print size.
> **Tip:** Scan the code with a phone before you send it to print.
### Links and reports
A saved link is the landing page URL itself, not a redirect or a short
link, so the library does not count clicks. Visits that arrive through
the link appear in the
[campaign report](/docs/features/campaigns#campaign-report) under its
campaign, source and medium, like any other tagged visit. A link with a
campaign has a **See campaign performance** shortcut to that report.
Deleting a link only removes it from the library. Copies already in
emails, ads or print keep working, and their visits stay in your
reports.
Anyone who can view the site can open the library, copy links and
download QR codes. Saving, editing and deleting a link needs the
`content.write` permission (see
[roles](/docs/teams/roles#permission-matrix)).
## UTM hygiene
**Campaigns → UTM hygiene** checks the `utm_source`, `utm_medium` and
`utm_campaign` values in the selected period and lists:
- **Near-duplicate values** that differ only by case, spaces or
punctuation (`Facebook` vs `facebook`, `e-mail` vs `email`), with the
visits for each and a suggested spelling.
- **Values to tidy** that break the lowercase, underscore style (capital
letters, spaces, hyphens or other punctuation), with a suggested value.
- **Sources we don't recognize**: `utm_source` values that are not on the
list of well-known sources.
These are suggestions only, and nothing is changed for you. Fix the
links at the source (the UTM builder keeps new ones consistent). **Set
up alias** opens **Site settings → Channels**, where a
[custom channel rule](/docs/metrics/channels#custom-channel-rules) can
put the variants in the same channel.
## Tips
- Use `utm_source` for where (newsletter, linkedin), `utm_medium` for the
type (email, cpc, social) and `utm_campaign` for the campaign.
- `utm_medium` values like `cpc`, `paid` or `display` put visits in a paid
[channel](/docs/metrics/channels), and `email` puts them in Email.
- Never put personal data (emails, customer ids) in UTM parameters.
## API
The campaign report, costs, builder, hygiene check and link library are
REST resources under `/sites/<site id>/campaigns` and MCP tools:
| Area | REST path | MCP tools |
|---|---|---|
| Campaign report | `/sites/<site id>/campaigns` | `campaigns_list` |
| Costs | `/sites/<site id>/campaigns/costs` | `campaign_costs_list`, `campaign_costs_create`, `campaign_costs_update`, `campaign_costs_delete`, `campaign_costs_import` |
| UTM builder | `/sites/<site id>/campaigns/builder` | `campaigns_builder` |
| UTM hygiene | `/sites/<site id>/campaigns/hygiene` | `campaigns_hygiene` |
| Link library | `/sites/<site id>/campaigns/links` | `links_list`, `links_get`, `links_create`, `links_update`, `links_delete`, `links_qr` |
`links_qr` returns the QR code as SVG text. Its optional `size` is the
module size in pixels, from 2 to 20. The [API reference](/docs/api)
lists every input.
---
Source: https://privatusanalytics.com/docs/features/experiments
# A/B test experiment reports
> Report on A/B tests you run with your own tool: send the variant as a property, then compare conversion rates per variant with statistical significance.
Privatus Analytics doesn't run experiments. It reports on the ones you run with your
own code or tool (GrowthBook, Statsig, VWO, Optimizely…).
## Send the variant
Add the experiment and variant as properties on every hit:
```js
privatus.props({ experiment: 'checkout_2026_09', variant: 'b' })
```
Set them before the first pageview (use
[manual mode](/docs/tracker/manual-mode) if the variant is assigned after
load), or send them on the events that matter.
## The report
**Experiments** takes a property that holds the variant and a goal, and
shows per variant:
- visits and conversions,
- the conversion rate, with the difference from the control,
- the **statistical significance** of the difference.
Wait for significance before deciding, and decide the sample size up
front: stopping as soon as a result looks significant inflates false
positives.
Visits never outlive the UTC day, so an experiment that spans several
visits by the same person counts each visit separately.
---
Source: https://privatusanalytics.com/docs/features/performance
# Core Web Vitals monitoring
> Monitor real-user Core Web Vitals (LCP, INP, CLS, FCP and TTFB) at the 75th percentile by page, device, browser and country, with automatic regression notes.
Turn on the [`vitals` module](/docs/tracker/modules#vitals-web-vitals):
```html
<script defer src="https://privatusanalytics.com/js/pa.js" data-site="pa_YOURSITEID" data-modules="engage,vitals"></script>
```
## Scorecard
For each metric, the **75th percentile** (p75) over the range, the share
of page views rated good / needs improvement / poor, and the trend:
| Metric | Good | Poor |
|---|---|---|
| LCP (Largest Contentful Paint) | ≤ 2.5 s | > 4 s |
| INP (Interaction to Next Paint) | ≤ 200 ms | > 500 ms |
| CLS (Cumulative Layout Shift) | ≤ 0.1 | > 0.25 |
| FCP (First Contentful Paint) | ≤ 1.8 s | > 3 s |
| TTFB (Time to First Byte) | ≤ 0.8 s | > 1.8 s |
These are Google's thresholds. Between good and poor is "needs
improvement".
## Breakdowns
By page (worst first, weighted by traffic), device, browser and country.
The [page detail](/docs/dashboard/page-detail) view shows Vitals for one
page by device.
## Regressions
Every day, each metric's p75 for the last 7 complete days is compared with
the 7 days before. A rise of more than 20% (with at least 20 samples)
adds an automatic [note](/docs/dashboard/notes) to your charts. Create a
**Vitals regression** [alert](/docs/reports/alerts) to be notified.
## Sampling and usage
Vitals are sampled on the server at the site's sample rate (Site settings
→ Tracking). The Free plan allows up to 10% and paid plans up to 100%. The
current rate is shown on the report. Web Vitals never count toward your
event usage.
---
Source: https://privatusanalytics.com/docs/features/uptime
# Uptime monitoring
> Monitor uptime with HTTP, keyword, TCP and DNS checks from four probe locations, plus SSL certificate and domain expiry, incident history and downtime alerts.
## Checks
Create checks from a site's **Uptime** page or across the workspace.
| Type | Checks that |
|---|---|
| **HTTP(S)** | A URL answers with the expected status code (`GET` or `HEAD`) |
| **Keyword** | A URL's response contains a keyword |
| **TCP** | A port accepts connections |
| **DNS** | A hostname resolves |
For each check choose the **interval**, a **timeout** and the **probe
locations**: US East, US West, EU Central and EU West.
| Plan | Checks | Fastest interval |
|---|---|---|
| Free | 3 | 5 minutes |
| Pro | 20 | 1 minute |
| Business | 100 | 30 seconds |
## When is a check down?
A check is **down** only when **most of its locations fail**, and a
confirmation re-check 30 seconds later fails too. One flaky location
never pages you. An incident opens when a check goes down and closes when
it recovers.
## Check detail
- Response time per location.
- Incident timeline: start, end, duration, which locations failed and the
error.
- For HTTPS: the **SSL certificate** issuer and expiry date. For the
domain: its **registration expiry** (from RDAP).
- 24-hour, 7-day and 30-day uptime and average response time.
Uptime % is the share of check intervals that were up.
## Alerts
Create **Uptime down/recovered** and **SSL or domain expiring in N days**
[alerts](/docs/reports/alerts), delivered by email, Slack, Teams, Discord,
webhooks, or PagerDuty and Opsgenie on Business. When a check linked to a
site goes down, the incident also appears as a [note](/docs/dashboard/notes)
on that site's charts.
## Allowing our probes
Probes identify themselves with this User-Agent:
```text
PrivatusUptime/1.0 (+https://privatusanalytics.com/docs/uptime)
```
The probe locations and their IP ranges are published as JSON at
[`/uptime/probes.json`](/uptime/probes.json), for firewall allowlists.
Uptime checks don't count toward event usage.
## Status pages
Show checks on a public [status page](/docs/features/status-pages).
---
Source: https://privatusanalytics.com/docs/features/status-pages
# Public status pages
> Create a public, branded status page for your uptime checks with a custom domain, incident updates and email subscribers. No cookies or third-party scripts.
A status page shows the current state and history of the checks you
choose, on a public page.
## Create one
**Status pages → New status page** in the workspace menu. Choose:
- a **name** and a **slug**: the page lives at
`https://privatusanalytics.com/status/<slug>`,
- which **checks** to show (each shows under its check name),
- your logo and colors,
- optionally a **custom domain** such as `status.example.com`: point a
CNAME at `privatusanalytics.com` and add the domain to the status page.
## Incident posts
Post updates during an incident ("Investigating", "Identified",
"Resolved") with a message. Posts appear on the page in a timeline.
## Subscribers
Visitors can subscribe by email. They confirm with a link (double
opt-in) and can unsubscribe from any email. Subscribers get your incident
posts. You can see and remove subscribers in the status page settings.
Their addresses are used only for these notifications.
## Privacy
Status pages set no cookies and don't load third-party scripts.
---
Source: https://privatusanalytics.com/docs/features/search-console
# Google Search Console and Bing integration
> Connect Google Search Console and Bing Webmaster Tools to see queries, clicks, impressions and rankings next to the visits and conversions each page brings.
## Connect
Open the site's **Search** page (also linked from **Site settings →
Integrations**): sign in with Google, grant **read-only** access, and choose the
property that matches the site.
### Bing Webmaster Tools
Bing connects with your own Bing Webmaster API key:
1. Sign in to [Bing Webmaster Tools](https://www.bing.com/webmasters) with
the account where the site is verified. Only sites verified in that
account appear in the list.
2. Click **Settings** (the gear icon) > **API access** > **API Key**, and
copy your key.
3. On the **Search** page, switch to the **Bing Webmaster Tools** tab, paste
the key and click **Load sites**.
4. Pick the site and click **Connect**.
We store your key encrypted and only use it to read search performance for
the site you choose. It is never shown again or returned by the API. You can
revoke it in Bing Webmaster Tools at any time. If Bing stops accepting it,
the Search page asks you to paste a new one, and connecting again with a new
key replaces the old one. Each site has its own key.
Over the [API](/docs/api) or MCP, send `bing_api_key` with `provider: bing`
to `POST /sites/{site}/search/properties` (list the sites) and
`POST /sites/{site}/search/connections` (connect).
We sync the data daily. Search engines publish it with a delay of two to
three days, so the most recent days are always empty, and the report shows a
warning for them.
Disconnect at any time. The synced data, and for Bing your stored API key,
is deleted with the connection.
## The report
- **Queries, pages, countries and devices**, each with clicks,
impressions, click-through rate and average position.
- **Landing page join:** each page's search clicks next to its Privatus Analytics
visits, bounce rate and conversions. This is an aggregate join by page
URL. Nothing about individual people is involved. It answers "which
queries lead to pages that convert?".
- **Opportunities:** queries with many impressions but a low click-through
rate, and pages ranking in positions 8 to 20 that could reach page one.
### Bing reports queries and pages by week
Bing gives daily numbers only for the whole site. The totals and the
**Clicks by day** chart use those. Bing reports queries and pages once a
week, and only the top ones, so those tables add up to less than the
totals, and a short period can show fewer rows than you expect.
## Why search numbers don't match visits
Search clicks come from Google or Bing, visits from your site. They differ
because of blockers, visitors who leave before the page loads, bots, and
the search engines' own anonymised-query filtering.
---
Source: https://privatusanalytics.com/docs/features/ai-crawlers
# AI crawler tracking from server logs
> See which AI crawlers like GPTBot, ClaudeBot and PerplexityBot, and which search bots, read your pages, from server or CDN logs with no IP addresses stored.
Crawlers don't run JavaScript, so the tracker never sees them. The **AI
crawlers** report is built from your **Cloudflare analytics** or your
**server or CDN logs** instead.
## What you see
Daily hits per crawler and per path, grouped into:
| Category | Examples |
|---|---|
| **AI** (training, AI search and assistants) | GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, Claude-User, PerplexityBot, Google-Extended, Applebot-Extended, Bytespider, CCBot, Amazonbot, Meta-ExternalAgent |
| **Search** | Googlebot, Bingbot, DuckDuckBot, YandexBot, Baiduspider, Applebot |
| **SEO tools** | AhrefsBot and similar |
| **Other** | Any other bot |
Use it to decide what to allow in `robots.txt`, to see which pages AI
assistants fetch when answering users, and to spot crawlers ignoring your
rules.
AI assistants sending *people* to your site is different: those visits
appear in the **AI assistants** [channel](/docs/metrics/channels).
## Connect Cloudflare
If your site is behind Cloudflare, this is the quickest way. There is
nothing to deploy.
1. Open the site's **AI crawlers** page and choose **Connect Cloudflare**.
2. Approve read-only access on Cloudflare's own consent page. We ask for
two permissions: listing your zones and reading zone analytics.
3. Pick the zone that serves the site.
The first import brings in up to 30 days, as far back as your Cloudflare
plan keeps analytics. After that the report updates every three hours, and
**Sync now** imports straight away. Only requests to the site's own
hostname (with and without `www`) are counted, so other subdomains in the
same zone stay out.
Good to know:
- Cloudflare samples analytics on busy zones, so hit counts are close
estimates, not exact log counts.
- Each day keeps the 10,000 busiest crawler and path pairs.
- Use Cloudflare sync or log shipping for a site, not both, or the same
hits are counted twice.
- **Disconnect** removes the hits imported from Cloudflare and revokes our
access. Hits from your own logs stay.
Over the API and MCP, `crawlers_cloudflare_zones`,
`crawlers_cloudflare_connect`, `crawlers_cloudflare_sync` and
`crawlers_cloudflare_disconnect` do the same once the Cloudflare account
has been approved in the browser.
## Connect your logs
Not on Cloudflare, or want exact counts? Send logs yourself.
Logs are sent with the site's **server ingest key** (Site settings →
Tracking → Server ingest key) to the endpoint shown on the site's **AI
crawlers** page. Connectors:
- **Cloudflare:** a Worker (or Logpush job) that forwards request logs.
- **Vercel** and **Netlify:** a log drain.
- **Nginx or Caddy:** a small log shipper that posts lines in the
"combined" log format.
## Privacy
Log lines contain visitors' IP addresses, so we parse them immediately and
keep only the day, the path, the status code and the crawler's name.
Lines from normal browsers are skipped. The IP, the referrer and any user
field are discarded as soon as a line is split and are never stored.
The Cloudflare sync never receives IP addresses at all. Cloudflare sends
us request counts grouped by User-Agent and path. We use the User-Agent
to name the crawler and store only the name, the path and the daily count.
---
Source: https://privatusanalytics.com/docs/features/click-maps
# Click maps without session recording
> Count clicks per element with privacy-friendly click maps built from CSS selectors. No mouse movement, coordinates, form input or session replay is collected.
Turn on the [`clicks` module](/docs/tracker/modules#clicks-click-maps):
```html
<script defer src="https://privatusanalytics.com/js/pa.js" data-site="pa_YOURSITEID" data-modules="engage,clicks"></script>
```
For each click, the module sends a short CSS selector of the clicked link,
button or control, for example `header > nav.main > a#pricing`. The report
lists the most clicked elements per page for the selected date range, with
each element's share of clicks.
What it never collects: mouse movement, scrolling paths, coordinates,
element text, form input or screenshots. There's no session replay.
## Name your targets
Generated ids and classes (those with three or more digits in a row) are
left out of selectors. For stable names, add `data-privatus-click` to
important elements:
```html
<div role="button" data-privatus-click="plan-picker">…</div>
```
Click-map hits don't count toward usage.
---
Source: https://privatusanalytics.com/docs/reports
# Sharing, reports and exports
> Share dashboards, schedule email reports, set up alerts, export raw or aggregated data, and import your history from Google Analytics 4 and other tools.
| Page | For |
|---|---|
| [Sharing](/docs/reports/sharing) | Public and password links, embeds, badges and wallboards |
| [Email reports](/docs/reports/email-reports) | Scheduled daily, weekly or monthly summaries |
| [Alerts](/docs/reports/alerts) | Thresholds, anomalies, goals, uptime, SSL, Vitals and usage |
| [Exports](/docs/reports/exports) | Aggregated tables, raw events and warehouse sync |
| [Imports](/docs/reports/imports) | GA4, Universal Analytics and other tools' history |
| [White label](/docs/reports/white-label) | Your brand name, logo and color on shared dashboards and email reports (Business) |
---
Source: https://privatusanalytics.com/docs/reports/sharing
# Share analytics dashboards
> Share a read-only analytics dashboard with a public or password-protected link, embed it in an iframe, show it on a TV wallboard or add a visitor counter badge.
**Site settings → Sharing** creates links to a read-only dashboard for
people without an account.
## Link types
| Type | Who can open it | Plan |
|---|---|---|
| **Public** | Anyone with the link | All |
| **Password** | Anyone with the link and the password | All |
| **Embed** | Pages that embed it in an `<iframe>` | Pro and up |
| **SSO-restricted** | Members of your SSO identity provider | Business |
| **Wallboard** | A TV showing the [wallboard](/docs/dashboard/live#wallboard). Created from **Live → Wallboard → TV links** (linked from Site settings → Sharing) | All |
Each link has a name, an optional **expiry date** (Pro and up) and can be
revoked at any time. Links look like `https://privatusanalytics.com/share/<token>`,
and the token is long and random.
## What's shared
Choose the sections: Overview, Pages, Sources, Campaigns, Locations,
Technology, Conversions, Events and Live. You can **lock the date range
and filters** (viewers see exactly what you set) or let viewers change
them.
Branding follows your [white label](/docs/reports/white-label) settings
on Business.
## Password links
The password is entered on a form and never travels in the URL. After a
correct password we set a short-lived, signed cookie on our domain for
that link only, which is strictly necessary for the password protection to
work.
## Embeds
```html
<iframe src="https://privatusanalytics.com/share/<token>/embed?theme=light"
width="100%" height="900" style="border:0" loading="lazy"
title="Website statistics"></iframe>
```
Embed links are always read-only and can lock filters and the date range.
## Visitor counter badge
A small SVG badge with your visitor count, for a README or a footer:
```html
<img src="https://privatusanalytics.com/badge/pa_YOURSITEID.svg" alt="Visitors">
```
Turn it on under Site settings → Sharing. (The Free plan's
[badge bonus](/docs/billing/usage#badge-bonus) uses a different badge.)
## Search engines
Shared dashboards are `noindex` unless you choose to publish a public stats
page that can be indexed.
---
Source: https://privatusanalytics.com/docs/reports/email-reports
# Scheduled email reports
> Send scheduled daily, weekly or monthly analytics email reports for one site or many to any recipient, with custom content blocks and an optional PDF attached.
**Email reports → New report** in the workspace menu.
| Setting | Options |
|---|---|
| Sites | One site or several (one email, a section per site) |
| Frequency | Daily at a chosen hour, weekly on a chosen weekday, or monthly on the 1st |
| Recipients | Up to 50 email addresses. Recipients don't need an account. People outside your workspace get an invite first (see below) |
| Content blocks | KPIs, chart, top pages, top sources, goals, campaigns, Web Vitals, uptime |
| Intro | Your own text at the top |
| Format | HTML email, optionally with a PDF attached |
**Send test** sends it to you right away (up to 10 tests an hour per
member, together with notification channel tests). The **delivery log** shows every
send and its status.
## Recipients outside your workspace
Members of your workspace are added at once. Anyone else gets one invite
email with **Accept** and **Decline** links, and receives nothing more
unless they accept. The report form shows each recipient's status:
**Active**, **Invite sent** (with the date), **Declined** or
**Unsubscribed**.
- Invites expire after 14 days. **Resend invite** is allowed once every 7
days per address and report.
- **Send test** to an address that hasn't accepted goes to you instead.
- Removing an address from the list deletes it from the report.
Every report email has a one-click **unsubscribe** link. Declining or
unsubscribing puts the address on an opt-out list: no workspace can add it
to a report again, and the form shows "This address has opted out of
reports". Only the person can undo it, with the **Receive reports again**
link on the unsubscribe page, which emails them a confirmation link.
The API and MCP take the same `recipients` list of addresses. Reports
return each address with its status in `recipient_details`, and
`email_report_recipients_list`, `email_report_recipients_resend` and
`email_report_recipients_delete` manage them one by one.
The Free plan includes 3 email reports. Paid plans are unlimited.
Slack, Microsoft Teams and Discord digests use the same settings with a
[notification channel](/docs/reports/alerts#channels) as the destination.
---
Source: https://privatusanalytics.com/docs/reports/alerts
# Analytics alerts and notifications
> Set alerts for traffic thresholds, anomalies, goals, missing data, downtime, SSL expiry, Web Vitals and usage, delivered by email, Slack, Teams or webhooks.
## Rule types
| Rule | Fires when |
|---|---|
| **Threshold** | A metric (visitors, visits, pageviews, bounce rate or conversion rate) goes above or below a value over a period, e.g. visitors < 10 per hour |
| **Anomaly** | A metric moves unusually far from its automatic baseline, with sensitivity low, medium or high |
| **Goal** | A goal reaches N completions within the rule's window |
| **No data** | No hits for N hours: the script may be missing |
| **Uptime** | An [uptime check](/docs/features/uptime) goes down or recovers |
| **SSL / domain** | A certificate or domain expires within N days |
| **Vitals** | A Web Vitals metric (LCP, INP, CLS, FCP, TTFB) regresses |
| **Usage** | Workspace usage reaches 80% or 100% of the plan (workspace-level) |
Site rules live in **Site settings → Alerts**. All rules are listed in the
workspace's **Alerts** page.
## Channels
Alerts are delivered through **notification channels**, set up once per
workspace and reused by any rule:
| Channel | Plan |
|---|---|
| Email | All |
| Slack, Microsoft Teams, Discord | Pro and up |
| Webhook ([signed](/docs/api/webhooks)) | Pro and up |
| Browser push | Pro and up |
| PagerDuty, Opsgenie | Business |
Each channel has a **Send test** button.
## Noise control
- **Mute** a rule for a period (for example during a planned migration).
- **History**: every time a rule fired and recovered. **Acknowledge** a
triggered alert to show the team someone's on it.
---
Source: https://privatusanalytics.com/docs/reports/exports
# Data exports and warehouse sync
> Export aggregated tables, raw events or a dashboard bundle as CSV, JSON or XLSX, or sync analytics data daily to S3, BigQuery, Snowflake or Azure Blob Storage.
## Quick exports
Every panel and drill-down table has a CSV download, and the Overview's
**Export** menu downloads the current view.
## Export builder
**Exports → New export** (workspace menu) for bigger jobs.
| Setting | Options |
|---|---|
| Data | **Aggregated** (metrics by dimensions), **pageviews**, **events**, **imported** data, a **dashboard** bundle, or **raw** events |
| Range | Any date range, in the site's timezone |
| Grouping | Hour, day, week, month, quarter or year (aggregated) |
| Dimensions and metrics | Any combination (aggregated) |
| Filters | Any filters and segment |
| Format | CSV, JSON, NDJSON, XLSX. The dashboard bundle is a ZIP |
**Preview** shows the first rows and an estimated row count before you
start. Exports run in the background. You get a notification (and a
`export.ready` [webhook](/docs/api/webhooks) if configured) when the file
is ready. Download links last 7 days.
Raw event exports are available on Pro and above. Properties you haven't
marked as "No personal data" under **Events → Property settings** are left
out of row-level exports and warehouse syncs.
## Warehouse sync (Business)
Push data to **Amazon S3**, **Google BigQuery**, **Snowflake** or **Azure
Blob Storage** every day. Add a destination with its credentials under
**Exports → Warehouses** (from the Exports page), then run a sync manually or let the daily
schedule do it. Credentials are stored encrypted.
## API
Exports are a REST resource under `/workspaces/<workspace id>/exports`
(create, list, show, download). See the [API reference](/docs/api).
Exports and API calls don't count toward your usage.
---
Source: https://privatusanalytics.com/docs/reports/imports
# Import data from GA4 and other tools
> Import your history from Google Analytics 4, Universal Analytics, Plausible, Fathom or Matomo so your Privatus Analytics charts don't start from zero.
Imported data shows alongside what Privatus Analytics collects, so your charts
don't start from zero. Turn on **Show imported data** in the Overview's
toolbar (it appears once a site has a finished import). Imported data
doesn't count toward usage. Each finished import also adds a
[note](/docs/dashboard/notes) spanning the imported dates.
## Google Analytics 4
1. **Imports → New import → Google Analytics 4** (Imports is in the site
menu and in Site settings).
2. Sign in with Google and grant **read-only** access.
3. Choose the GA4 property.
4. Choose the date range. Import up to the day before your Privatus Analytics
tracking started, so days aren't counted twice.
5. Start the import. It runs in the background.
We import daily aggregates: visitors, visits, pageviews, bounce rate and
duration, in total and by page, source, country, device, browser and
operating system. GA4 events and campaigns aren't imported.
GA4's own definitions are kept, so imported numbers won't match
Privatus Analytics-collected numbers exactly (see
[why numbers differ](/docs/metrics/ga4-differences)).
## CSV imports
Choose a template and upload the CSV file. Columns are matched to the
template automatically. If the file doesn't match (for example a missing
date or metric column), the import fails with the reason and nothing is
kept, so you can fix the file and try again.
| Template | Export from |
|---|---|
| Universal Analytics | UA custom report exports |
| Fathom | Fathom's CSV export |
| Simple Analytics | Simple Analytics' export |
| Plausible | A CSV file from Plausible's export (unzip it first) |
| Matomo | Matomo's export |
| Umami | Umami's export |
| Clicky | Clicky's export |
## Managing imports
The import list shows status (queued, running, complete, failed), rows
and the date span. Deleting an import removes its data but doesn't touch
anything Privatus Analytics collected.
---
Source: https://privatusanalytics.com/docs/reports/white-label
# White label branding for shared reports
> Put your own brand name, logo and accent color on shared dashboards and email reports, and remove Privatus Analytics branding from embeds and status pages.
White label puts your own name, logo and accent color on the reports you
send to clients, and can remove the Privatus Analytics name from them. You set it
once per workspace and it applies to every site in that workspace.
## Who can use it
White label is part of the **Business** and **Enterprise** plans. A
workspace covered by an approved agency
[discount](/docs/billing/plans#discounts) also gets it on Pro.
The settings are in **Workspace settings → White label**. Changing them
needs the `workspace.manage` permission, which the Owner and Admin
[roles](/docs/teams/roles) have.
## Settings
| Setting | What it does | Rules |
|---|---|---|
| **Brand name** | Shown in place of Privatus Analytics | Up to 60 characters |
| **Logo URL** | An image shown next to the brand name | An `https://` link to a PNG, SVG or JPEG, with no spaces, up to 500 characters |
| **Accent color** | The color of the brand name | `#` and six hex digits, such as `#06755b` |
| **Hide Privatus Analytics branding** | Removes the Privatus Analytics name and logo | On or off |
Every setting is optional. Clear a field and save to remove it.
The brand is applied as soon as the workspace has a brand name, a logo or
**Hide Privatus Analytics branding** turned on. An accent color on its own changes
nothing, because it only colors the brand name.
> **Note:** The logo is not uploaded. Shared dashboards and emails load
> it from your URL each time, so keep the file online at that address. It
> is shown about 32 pixels tall on shared dashboards and 28 pixels tall
> in emails.
## Where your brand appears
| Place | Brand name, logo and color | Hide Privatus Analytics branding |
|---|---|---|
| [Shared dashboards](/docs/reports/sharing), including the password prompt | Your logo and brand name at the top of the page, and your brand name in the browser tab title | Removes the Privatus Analytics link at the bottom of the page |
| [Embeds](/docs/reports/sharing#embeds) | Your brand name in the title of the embedded frame. The embed shows no logo | Removes the Privatus Analytics link under the chart |
| [Email reports](/docs/reports/email-reports) | Your logo and brand name at the top of the email in place of the Privatus Analytics logo, and your brand name in the footer line | Removes the Privatus Analytics logo from the top of the email, even with no brand name or logo |
| [Status pages](/docs/features/status-pages) | Not used. Each status page has its own logo and color | Removes the "Powered by Privatus Analytics" link |
> **Tip:** The footer line of a report email says who sent the report. It
> names Privatus Analytics until you set a brand name, even when **Hide
> Privatus Analytics branding** is on.
## What it does not change
- **Addresses.** Shared dashboards and embeds stay on `privatusanalytics.com`, and
report emails come from the Privatus Analytics sending address. Custom dashboard
domains and custom email sender domains are not available. A status
page can have its own
[custom domain](/docs/features/status-pages#create-one).
- **Chart colors.** The accent color only colors your brand name. Charts
and buttons keep the standard colors.
- **PDF attachments.** The PDF attached to an email report keeps the
Privatus Analytics name at the top.
- **Other emails.** Report invitations, alert notifications and export
emails keep Privatus Analytics branding. Status page emails use the status page's
own name and color.
- **Wallboards and badges.** The TV wallboard and the visitor counter
badge are unchanged.
- **The app.** Members who sign in see the normal Privatus Analytics dashboard.
## Plans and downgrades
On a plan without white label, the page shows the form switched off with
a link to the plans. Saving through the API returns a validation error
that names the Business plan.
If a workspace moves to a plan without white label, the settings are kept
but stop applying: shared dashboards, embeds, email reports and status
pages show Privatus Analytics branding again. When the workspace is back on a plan
with white label, the saved brand applies again with nothing to re-enter.
## API
White label is a REST resource at
`/workspaces/<workspace id>/white_label` (`GET` to read, `PATCH` to
change) and the MCP tools `white_label_get` and `white_label_update`. An
update changes only the fields you send (`brand_name`, `brand_logo_url`,
`brand_color`, `hide_branding`), and a blank value removes a field. The
response adds `available` (the plan includes white label) and `active`
(the brand is being applied now). The [API reference](/docs/api) lists
every input.
---
Source: https://privatusanalytics.com/docs/teams
# Team access and security
> Manage workspaces, members, roles and site access for your analytics team, and secure sign-in with SSO, SCIM, two-factor authentication and an audit log.
## Workspaces and members
A **workspace** owns sites, members, billing, API tokens and webhooks.
Everyone in it is a **member** with one **role** and access to **all
sites** or **selected sites**.
- **Invite** from **Workspace settings → Members**: enter up to 50 email
addresses, then choose a role and site access. Invitations are emailed
and expire after 14 days. You can revoke pending ones.
- **Change role** or **site access** at any time. "All sites" includes
sites added later. You can't change your own access, or give someone a
role or sites beyond your own.
- **Remove** a member: their API tokens for this workspace stop working
immediately. Members can also leave on their own.
- **Transfer ownership** to another member (owners only). The previous
owner becomes an admin. The owner can't be removed or leave before
that.
Inviting, changing and removing members need the `members.manage`
permission (see [Roles & permissions](/docs/teams/roles)). Per-site
access can also be managed from a site's **Access** tab.
The Free plan allows 3 members, and pending invitations count toward
that limit. Paid plans are unlimited.
Members and invitations are REST resources under
`/workspaces/<workspace id>/members` and
`/workspaces/<workspace id>/invitations`, and MCP tools named `members_*`
and `invitations_*`. The [API reference](/docs/api) lists every input.
## In this section
- [Roles & permissions](/docs/teams/roles), including custom roles.
- [Single sign-on](/docs/teams/sso) with guides for
[Okta](/docs/teams/sso-okta), [Microsoft Entra ID](/docs/teams/sso-entra-id),
[Google Workspace](/docs/teams/sso-google-workspace) and
[JumpCloud](/docs/teams/sso-jumpcloud).
- [SCIM provisioning](/docs/teams/scim).
- [Two-factor authentication](/docs/teams/two-factor).
- [Audit log](/docs/teams/audit-log).
## Workspace security settings
**Workspace settings → Security** holds the sign-in rules for everyone
in the workspace. Changing them needs the `workspace.manage` permission,
which the Owner and Admin roles have.
| Setting | Options | Plan |
|---|---|---|
| **Require two-factor authentication** | On or off | Business |
| **Allowed login methods** | Email and password, Email login link, Passkey, Google, GitHub, SSO (SAML/OIDC) | All |
| **Sign members out after** | No limit, 8 hours, 24 hours, 7 days or 30 days | All |
| **IP allowlist** | IP addresses and CIDR ranges, IPv4 or IPv6 | Business |
| **Support access** | On or off, for 7 days at a time | All |
- **Require two-factor authentication.** Members without an
authenticator app or a passkey are sent to set one up before they can
open the workspace. See
[Two-factor authentication](/docs/teams/two-factor#enforce-it-for-everyone).
- **Allowed login methods** apply to every member, and at least one
method must stay selected. The owner can always log in with a password
or a passkey, so a login rule can't lock the owner out. Someone who
belongs to several workspaces can use only the methods that all of
them allow. When [SSO](/docs/teams/sso) is enforced, members sign in
through SSO only.
- **Sign members out after** ends a session that many hours after the
member signed in, however active they are. Someone who belongs to
several workspaces gets the shortest lifetime among them.
- **IP allowlist.** Only the listed addresses can open the workspace in
the app or use its API tokens. Put one entry per line, such as
`203.0.113.0/24` or `2001:db8::/32`. An empty list allows any address.
The list must include the address you are saving from (the page shows
it), so you can't lock yourself out.
- **Support access** lets Privatus Analytics support view the workspace for 7 days
from the time you save. Support staff cannot see your workspace unless
you allow it. Turn it off to end access at once. Access is read-only
and every view is written to the
[audit log](/docs/teams/audit-log#support-access).
> **Note:** On a plan below Business the two Business settings are shown
> switched off. If a workspace moves to a lower plan, its 2FA requirement
> and IP allowlist are kept but stop applying until it is back on
> Business.
Security settings are a REST resource at
`/workspaces/<workspace id>/security` (`GET` to read, `PATCH` to change)
and the MCP tools `workspace_security_get` and
`workspace_security_update`. Over the API, `session_ttl_hours` takes any
whole number of hours up to 2,160 (90 days), and `0` means no limit. The
[API reference](/docs/api) lists every input.
---
Source: https://privatusanalytics.com/docs/teams/roles
# Team roles and permissions
> See what each built-in role (Owner, Admin, Editor, Analyst, Viewer, Billing) can do, how custom roles work on Business, and how API tokens narrow access.
Access is built from **permissions**. A role is a set of permissions, and
every [API operation](/docs/api) and MCP tool declares the one permission
it needs.
## Permission matrix
This table is generated from the code that enforces it.
| Permission | Allows | Owner | Admin | Editor | Analyst | Viewer | Billing |
|---|---|---|---|---|---|---|---|
| `analytics.read` | View dashboards, stats, live data and reports | ✓ | ✓ | ✓ | ✓ | ✓ | - |
| `analytics.export` | Create exports and download data | ✓ | ✓ | ✓ | ✓ | - | - |
| `content.write` | Manage goals, funnels, segments, notes, alerts, email reports, links and dashboards | ✓ | ✓ | ✓ | ✓ | - | - |
| `sites.manage` | Create sites and change site settings, tracking, privacy, traffic rules, integrations and sharing | ✓ | ✓ | ✓ | - | - | - |
| `uptime.manage` | Manage uptime checks and status pages | ✓ | ✓ | ✓ | - | - | - |
| `members.manage` | Invite members and change roles and site access | ✓ | ✓ | - | - | - | - |
| `tokens.manage` | Create and revoke API tokens for anyone in the workspace (members can always manage their own) | ✓ | ✓ | - | - | - | - |
| `billing.manage` | Change plan, payment details and view invoices | ✓ | ✓ | - | - | - | ✓ |
| `workspace.manage` | Workspace settings, security, SSO, webhooks, white label, audit log and deletion | ✓ | ✓ | - | - | - | - |
A member with no access to a site can't see it anywhere, including in
lists, exports and the API.
## Built-in roles
- **Owner:** everything. Every workspace has at least one owner.
- **Admin:** everything an owner can do.
- **Editor:** analytics, exports, content (goals, funnels, segments, notes,
alerts, reports, links), site settings and uptime. No members, billing,
tokens for others or workspace settings.
- **Analyst:** analytics, exports and content. No site settings.
- **Viewer:** read-only analytics.
- **Billing:** plan, payment details and invoices only.
On the Free plan, the Owner, Admin and Viewer roles are available.
## Custom roles
On Business, create roles with any combination of permissions in
**Workspace settings → Roles** (a permission matrix editor), then assign
them like built-in roles.
## API tokens narrow, never widen
An [API token](/docs/api/authentication) belongs to a member. Its effective
access is:
- **permissions** = the member's role ∩ the permissions chosen for the
token,
- **sites** = the member's sites ∩ the sites chosen for the token.
If the member's role or site access shrinks, their tokens shrink with it.
Members can always manage their own tokens, and `tokens.manage` lets admins
manage everyone's.
---
Source: https://privatusanalytics.com/docs/teams/sso
# Single sign-on (SSO) with SAML or OIDC
> Set up single sign-on for your analytics workspace with SAML 2.0 or OpenID Connect: IdP values, email domains, just-in-time provisioning and enforcing SSO.
SSO is available on the **Business** plan. Members sign in through your
identity provider (IdP), so you control access centrally.
## Values for your identity provider
Replace `ws_…` with your workspace id (Workspace settings → Overview).
### SAML 2.0
| Setting | Value |
|---|---|
| ACS (reply / single sign-on) URL | `https://privatusanalytics.com/users/auth/saml/callback` |
| SP entity ID (audience) | `https://privatusanalytics.com/users/auth/saml/metadata?workspace=ws_…` |
| Name ID format | `emailAddress` |
| Name ID value | The user's email address |
| Attributes (optional) | `name` or `displayName` for the member's name |
From the IdP, you'll need its **SSO URL**, **entity ID (issuer)** and
**X.509 signing certificate**, or its metadata XML to import.
### OpenID Connect
| Setting | Value |
|---|---|
| Redirect (callback) URI | `https://privatusanalytics.com/users/auth/openid_connect/callback` |
| Scopes | `openid email profile` |
| Flow | Authorization code with PKCE |
From the IdP, you'll need the **issuer URL** (we use its discovery
document), a **client id** and a **client secret**.
## Set up
1. **Workspace settings → SSO.** Choose SAML or OIDC and enter
the IdP's values.
2. List your **email domains**. Only people with those domains can sign in
through SSO.
3. Choose **just-in-time provisioning** and the **default role** for new
members (any role except Owner).
4. **Test**: sign in through the IdP in a private window. A successful
test marks the configuration as tested. Nothing changes for other
members.
5. **Activate.** Members can now use **Log in with SSO** (enter your email
or domain).
6. Optional: **Enforce SSO**, so members of this workspace must sign in
through the IdP. Keep one owner with another sign-in method as a break-glass
account.
## Signing in
On the login page choose **Log in with SSO** and enter your work email. You
are sent to your IdP and back. Start sign-in from Privatus Analytics (SP-initiated).
Tiles in your IdP's app dashboard should link to the Privatus Analytics SSO login
page.
## Guides
[Okta](/docs/teams/sso-okta) · [Microsoft Entra ID](/docs/teams/sso-entra-id) ·
[Google Workspace](/docs/teams/sso-google-workspace) ·
[JumpCloud](/docs/teams/sso-jumpcloud). To create and remove members
automatically, add [SCIM](/docs/teams/scim).
---
Source: https://privatusanalytics.com/docs/teams/sso-okta
# Set up SSO with Okta
> Connect Okta to Privatus Analytics with SAML 2.0 or OpenID Connect single sign-on. Create the app integration, copy the values, assign people and test.
1. In the Okta Admin Console go to **Applications → Applications → Create
App Integration**, choose **SAML 2.0**, and name it "Privatus Analytics".
2. **SAML settings:**
| Okta field | Value |
|---|---|
| Single sign-on URL | `https://privatusanalytics.com/users/auth/saml/callback` (keep "Use this for Recipient URL and Destination URL" checked) |
| Audience URI (SP Entity ID) | `https://privatusanalytics.com/users/auth/saml/metadata?workspace=ws_…` |
| Name ID format | EmailAddress |
| Application username | Email |
Optionally add an attribute statement `name` → `user.displayName`.
3. Finish, then open **Sign On → SAML 2.0 → More details** and copy the
**Sign on URL**, **Issuer** and **Signing certificate**.
4. In Privatus Analytics, **Workspace settings → SSO → SAML**: paste the
three values, list your email domains, and save.
5. In Okta, **Assignments**: assign the people or groups who should have
access.
6. **Test** in Privatus Analytics, then **Activate**.
For automatic provisioning, enable SCIM in the same Okta app: see
[SCIM](/docs/teams/scim).
Prefer OpenID Connect? Create an **OIDC - Web Application** instead, with
the sign-in redirect URI `https://privatusanalytics.com/users/auth/openid_connect/callback`,
and paste the issuer (`https://<your-okta-domain>`), client id and secret
into the OIDC form.
---
Source: https://privatusanalytics.com/docs/teams/sso-entra-id
# Set up SSO with Microsoft Entra ID
> Connect Microsoft Entra ID (Azure AD) to Privatus Analytics with SAML 2.0 single sign-on, step by step: enterprise app, claims, certificate and testing.
1. In the Entra admin center go to **Identity → Applications → Enterprise
applications → New application → Create your own application**. Name
it "Privatus Analytics" and choose "Integrate any other application you
don't find in the gallery".
2. Open **Single sign-on → SAML** and edit **Basic SAML Configuration**:
| Entra field | Value |
|---|---|
| Identifier (Entity ID) | `https://privatusanalytics.com/users/auth/saml/metadata?workspace=ws_…` |
| Reply URL (ACS URL) | `https://privatusanalytics.com/users/auth/saml/callback` |
3. Under **Attributes & Claims**, set **Unique User Identifier (Name ID)**
to `user.mail` with the format **Email address**. (If some users have
no mailbox, use `user.userprincipalname` when it equals their email.)
4. Under **SAML Certificates**, download **Certificate (Base64)**. Under
**Set up Privatus Analytics**, copy the **Login URL** and **Microsoft
Entra Identifier**.
5. In Privatus Analytics, **Workspace settings → SSO → SAML**: paste the
login URL, identifier and certificate, list your email domains, and
save.
6. In Entra, **Users and groups**: assign who can sign in.
7. **Test** in Privatus Analytics, then **Activate**.
For provisioning, Entra's **Provisioning** tab supports SCIM: see
[SCIM](/docs/teams/scim).
---
Source: https://privatusanalytics.com/docs/teams/sso-google-workspace
# Set up SSO with Google Workspace
> Connect Google Workspace to Privatus Analytics with a custom SAML app for single sign-on, including the ACS URL, entity ID, Name ID and provisioning options.
1. In the Google Admin console go to **Apps → Web and mobile apps → Add
app → Add custom SAML app**. Name it "Privatus Analytics".
2. On **Google Identity Provider details**, copy the **SSO URL**, **Entity
ID** and **Certificate** (or download the metadata). Continue.
3. **Service provider details:**
| Google field | Value |
|---|---|
| ACS URL | `https://privatusanalytics.com/users/auth/saml/callback` |
| Entity ID | `https://privatusanalytics.com/users/auth/saml/metadata?workspace=ws_…` |
| Name ID format | EMAIL |
| Name ID | Basic Information › Primary email |
4. **Attribute mapping** (optional): map *First name* and *Last name*, or
add `name`.
5. Finish, then turn the app **ON for everyone** or for selected
organizational units or groups.
6. In Privatus Analytics, **Workspace settings → SSO → SAML**: paste the
SSO URL, entity ID and certificate, list your email domains, and save.
7. **Test** in Privatus Analytics, then **Activate**.
Google Workspace doesn't offer SCIM for custom SAML apps. Use
just-in-time provisioning and remove members in Privatus Analytics when they leave,
or connect provisioning through another directory.
Everyone can also use **Sign in with Google** without SAML, if Google
sign-in is allowed in your workspace's security settings.
---
Source: https://privatusanalytics.com/docs/teams/sso-jumpcloud
# Set up SSO with JumpCloud
> Connect JumpCloud to Privatus Analytics with SAML 2.0 single sign-on: create the custom app, enter the SP entity ID and ACS URL, bind user groups and test.
1. In the JumpCloud Admin Portal go to **SSO Applications → Add New
Application → Custom Application**, and choose **Manage Single Sign-On
(SSO)** with **SAML 2.0**. Name it "Privatus Analytics".
2. On the **SSO** tab:
| JumpCloud field | Value |
|---|---|
| IdP Entity ID | Any unique value, e.g. `jumpcloud-privatus` |
| SP Entity ID | `https://privatusanalytics.com/users/auth/saml/metadata?workspace=ws_…` |
| ACS URL | `https://privatusanalytics.com/users/auth/saml/callback` |
| SAMLSubject NameID | email |
| SAMLSubject NameID Format | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` |
| Signature Algorithm | RSA-SHA256, sign Assertion |
Optionally add an attribute `name` mapped to the user's full name.
3. Activate, then **Export Metadata** or copy the **IDP URL** and download
the certificate.
4. In Privatus Analytics, **Workspace settings → SSO → SAML**: enter the
IdP URL, the IdP entity ID and the certificate, list your email
domains, and save.
5. In JumpCloud, bind **user groups** to the application.
6. **Test** in Privatus Analytics, then **Activate**.
JumpCloud supports SCIM for custom apps on some plans: see
[SCIM](/docs/teams/scim).
---
Source: https://privatusanalytics.com/docs/teams/scim
# SCIM user provisioning
> Set up SCIM 2.0 to create, update and remove workspace members automatically from your identity provider, with the base URL, token and supported endpoints.
SCIM 2.0 keeps workspace members in sync with your directory (Business
plan, with [SSO](/docs/teams/sso) set up).
## Connect
1. **Workspace settings → SSO → SCIM token → Generate.** The
token (`scim_…`) is shown once. Generating a new one replaces the old.
2. In your IdP's provisioning settings:
| Setting | Value |
|---|---|
| SCIM base URL | `https://privatusanalytics.com/scim/v2` |
| Authentication | HTTP header, Bearer token: the `scim_…` token |
| Unique identifier | `userName` = email address |
3. Enable **create**, **update** and **deactivate** users, and assign the
people or groups to provision.
## What's supported
| Operation | Endpoint | Effect |
|---|---|---|
| List / filter users | `GET /scim/v2/Users` | Users provisioned into this workspace (`filter=userName eq "…"` supported) |
| Get a user | `GET /scim/v2/Users/{id}` | |
| Create | `POST /scim/v2/Users` | Creates the user if needed and adds them as a member with the SSO default role |
| Update | `PUT` or `PATCH /scim/v2/Users/{id}` | Display name and `active`. `active: false` removes the membership |
| Delete | `DELETE /scim/v2/Users/{id}` | Removes the member from the workspace |
Groups aren't provisioned: set roles and site access in Privatus Analytics. Removing
a member revokes their API tokens for this workspace. The person's account itself is kept (they may belong to
other workspaces).
Every SCIM change is recorded in the [audit log](/docs/teams/audit-log).
---
Source: https://privatusanalytics.com/docs/teams/two-factor
# Two-factor authentication (2FA)
> Turn on two-factor authentication with an authenticator app or passkeys, save recovery codes, and enforce 2FA for every member of your analytics workspace.
## Turn it on
**Account settings → Security → Two-factor authentication → Set up.**
1. Scan the QR code with an authenticator app (1Password, Google
Authenticator, Authy, Microsoft Authenticator…).
2. Enter the six-digit code to confirm.
3. **Save your recovery codes.** Each works once, if you lose your device.
You can regenerate them (which invalidates the old ones).
From then on, after your password, email link or social sign-in, you're
asked for a code, a passkey or a recovery code.
## Passkeys
Add passkeys (Touch ID, Face ID, Windows Hello, a security key or a
password manager) under **Account settings → Security → Passkeys**. A
passkey can sign you in on its own, and counts as the second factor.
## Enforce it for everyone
On the **Business** plan, owners and admins can require 2FA for all members
in **Workspace settings → Security**. Members without it are asked to set it
up at their next sign-in. If the workspace moves to a lower plan, the
setting is kept but stops applying until it's back on Business. The Members
list shows each member's 2FA status on every plan.
## Lost access?
Use a recovery code. If you have none left, ask a workspace owner to
contact support from their account. We verify ownership before removing
2FA.
---
Source: https://privatusanalytics.com/docs/teams/audit-log
# Workspace audit log
> Use the audit log to see who changed sites, members, API tokens, SSO and billing, and when. Filter by actor, action or date, and export entries to CSV.
**Workspace settings → Audit log** lists changes made in the workspace:
sites, settings, goals, funnels, members and roles, API tokens, SSO,
webhooks, billing and more. Each entry shows:
- the **actor** (member, API token, SCIM, or Privatus Analytics support with your
consent),
- the **action**: create, update or destroy,
- the **record** and what changed,
- the **time**, and the IP address of the *member* who made the change.
Visitors' IPs are never involved.
Filter by actor, record type, action and date range, and **export** to
CSV. The same filters work in the [API](/docs/api) (`audit_logs` tools).
## Retention
| Plan | Kept for |
|---|---|
| Free | Not available |
| Pro | 30 days |
| Business | 1 year |
| Enterprise | Custom |
## Support access
Our support team can only view your workspace after an owner grants
temporary access (with an expiry). Everything done during that time is
recorded here.
---
Source: https://privatusanalytics.com/docs/privacy
# Privacy and GDPR for cookieless analytics
> How Privatus Analytics measures without cookies or persistent identifiers, what happens to IP addresses, and what it means for GDPR and cookie banners.
> **Note:** This section explains how the product works and gives
> templates. It isn't legal advice. Your obligations depend on your
> jurisdiction and your other processing. Check with your own counsel.
## The data journey
1. **Browser:** the tracker sends one request per pageview or event with
the page URL, referrer, screen width, language and the properties you
choose. It reads and writes nothing on the device (except an
[opt-out flag](/docs/tracker/opt-out) the visitor sets themselves) and
uses no fingerprinting APIs.
2. **Ingest (US):** the request arrives at our US region with the
visitor's IP address and User-Agent, as every HTTP request does. This
is the same for every visitor, including visitors from the EU/EEA, the
UK and Switzerland. In memory only, while the request is handled, the
IP and User-Agent are used to:
- check for bots,
- compute the daily visit key
`HMAC(daily salt, site, IP, User-Agent)`.
The visitor's country comes from the `CF-IPCountry` header that our
network provider, Cloudflare, adds to the request. Location is country
only: no region, city or coordinates are collected.
3. **Minimization:** the URL is stripped of query parameters (except
campaign parameters and your allowlist), the
[PII scrubber](/docs/privacy/pii-scrubbing) redacts emails, ids and
tokens, your [path masks](/docs/tracker/exclusions-and-masking) and
[traffic rules](/docs/privacy/traffic-rules) apply, and the User-Agent
is reduced to browser, OS and device type.
4. **Storage (US):** only the minimized event is stored. **The IP address,
the raw User-Agent and the visit key are never written to disk, logs,
queues or backups.**
## Key facts
| Question | Answer |
|---|---|
| Cookies or device storage? | None (only the visitor's own opt-out flag) |
| Persistent identifiers? | None. Visit ids are random and last at most one UTC day |
| Cross-site or cross-device tracking? | Impossible by design |
| IP addresses stored? | Never, not even for bots or security |
| Data sold or shared? | Never. Not used for advertising or model training |
| Where is data stored? | United States. See [Where data lives](/docs/privacy/where-data-lives) |
| Affiliate referrals? | Attributed without cookies or click logs. See [Affiliate program](/docs/billing/affiliates#how-referrals-are-attributed-privacy) |
| Can we re-identify a visitor? | Not from stored data: the daily salt that could link a visit to an IP is destroyed after the day |
We describe this data as **pseudonymous, heavily minimized** data, not as
"anonymous": for one day, a visit key could in theory be linked to an IP
by someone holding the salt. See
[How visitors are counted](/docs/metrics/how-visitors-are-counted).
## Do I need a cookie banner?
For Privatus Analytics alone, in most setups, no:
- **ePrivacy / PECR** consent rules cover storing or reading information
on a device. The tracker does neither.
- **GDPR** still applies to the transient processing of IP addresses. Most
customers rely on **legitimate interests** (Art. 6(1)(f)). Use our
[LIA template](/docs/privacy/dpia-lia) to document it, and describe the
processing in your privacy policy ([templates](/docs/privacy/policy-templates)).
- **US state laws** (CCPA/CPRA and others): we act as your service
provider/processor, so there's no "sale" or "sharing" of personal
information. We honour **Global Privacy Control** by default anyway.
Some regulators and some organizations take stricter views. The
[opt-out](/docs/tracker/opt-out) and [GPC/DNT handling](/docs/privacy/dnt-gpc)
exist for them.
## Our role
You're the **controller** of your visitors' data, and we're your
**processor**. Our Data Processing Agreement (with the EU Standard
Contractual Clauses and the UK addendum) is part of the Terms and is
published at [/legal/dpa](/legal/dpa), with the
[subprocessor list](/legal/subprocessors). The DPA includes our technical
and organizational measures.
## In this section
- [Data inventory](/docs/privacy/data-inventory): every stored field.
- [Where data lives](/docs/privacy/where-data-lives).
- [PII scrubbing](/docs/privacy/pii-scrubbing) and
[traffic rules](/docs/privacy/traffic-rules).
- [DNT and GPC](/docs/privacy/dnt-gpc) and the [opt-out snippet](/docs/privacy/opt-out).
- [Privacy policy templates](/docs/privacy/policy-templates) in six
languages.
- [DPIA and LIA templates](/docs/privacy/dpia-lia).
---
Source: https://privatusanalytics.com/docs/privacy/data-inventory
# Analytics data inventory
> Every field Privatus Analytics stores about visits and events, why it is needed, how it is minimized and how long it is kept, plus what stays in memory only.
## Stored per event and visit
| Field | Purpose | Minimization |
|---|---|---|
| Hostname and path | Pages report | Query string removed except campaign parameters and your allowlist, PII scrubbed, path masks applied |
| Referrer host and path | Sources | `www.`/`m.` stripped, query string dropped, your own domains blanked |
| UTM source, medium, campaign, content, term, `ref` | Campaigns | Stored as sent (don't put personal data in them), click ids reduced to a yes/no "paid click" flag |
| Channel | Channels | Derived from the above |
| Country | Locations | From the `CF-IPCountry` header Cloudflare adds to each request. No region, city or coordinates |
| Language | Locations | `navigator.language`, max 16 characters |
| Device type, browser + major version, OS + major version | Technology | Parsed from the User-Agent, raw User-Agent dropped |
| Screen size bucket | Technology | `xs` < 414, `sm` < 768, `md` < 1024, `lg` < 1440, `xl` px, exact width dropped |
| Visit id | Visits | Random UUIDv7, not derived from the visitor, at most one UTC day |
| Time | All reports | To the second |
| Event name, properties | Events | ≤ 30 properties, typed, length-limited, PII scrubbed |
| Revenue, currency | Revenue | As sent |
| Engaged time, scroll depth | Engagement | Time capped at 4 h, scroll in 10% bands |
| Interaction (yes, no or unknown) | Telling people from bots that load a page and leave | One flag per visit: whether any mouse, touch, key or wheel input was seen. Nothing about the input itself |
| Web Vital name and value | Performance | Sampled |
| Click selector | Click maps | Short CSS selector, generated ids removed |
## Held briefly in memory only
| Data | Purpose | Lifetime |
|---|---|---|
| IP address | Bot checks, visit key | The request (milliseconds) |
| Raw User-Agent | Parsing, bot checks, visit key | The request |
| Daily salt | Visit key | Until the end of the UTC day plus 30 minutes, never persisted |
| Visit key (HMAC) | Continue a visit | 30 minutes of inactivity, never past midnight UTC, memory only |
## Aggregates
| Data | Purpose | Retention |
|---|---|---|
| Filtered hit counts (bots, traffic rules, redactions) by reason and country | Show what was filtered | 13 months |
No IP address is stored for bots or blocked hits.
## Retention
Event data is kept for your plan's retention (6 months on Free, for as
long as you subscribe on paid plans, custom per site on Business), then
deleted automatically. You can delete data for a date range, a site or
your whole workspace at any time. See
[Cancellation](/docs/billing/cancellation) for what happens when you
leave.
---
Source: https://privatusanalytics.com/docs/privacy/where-data-lives
# Where analytics data is stored
> Where Privatus Analytics stores and processes data (the United States), what counts as a transfer for EU, UK and Swiss visitors, and which safeguards apply.
## Storage: United States
All stored data (events, visits, your account and settings, backups and
exports) is kept in our **US region**.
## Processing: United States, in memory
Every visitor request is processed in our US region, including requests
from visitors in the **EU/EEA, the UK and Switzerland**. The IP address
and User-Agent arrive with the request and are used **in memory only**
(bot checks and the daily visit key) while the request is handled. Then they are **dropped**. They are never
written to disk, logs, queues, caches or backups.
## What is transferred
For visitors outside the US, each request is a transfer of personal data
to the US: the IP address and User-Agent exist there in memory for the
duration of the request. What is stored afterwards is the minimized event,
which has no IP address, no raw User-Agent and no persistent identifier.
See the [data inventory](/docs/privacy/data-inventory).
## Transfer safeguards
- the **Standard Contractual Clauses** (2021/914, module 2) in our DPA,
with the **UK addendum** and the amendments for the **Swiss FADP**,
- minimization: the IP address and User-Agent are processed in memory only
and never stored.
We are not certified under the EU-US Data Privacy Framework.
## EU hosting
We don't offer EU storage or processing yet. If you need it, join the
waitlist from the website: demand decides when we add an EU region. Our
code is built so that each workspace belongs to a region, which makes
that possible.
## Subprocessors
The current list, with each provider's location and purpose, is on the
[subprocessors page](/legal/subprocessors).
---
Source: https://privatusanalytics.com/docs/privacy/pii-scrubbing
# PII scrubbing for analytics data
> How the PII scrubber redacts emails, tokens and other PII from URLs, referrers and event properties before storage, plus custom rules and a redaction log.
Personal data often leaks into analytics by accident: an email in a
confirmation URL, a password-reset token, a phone number in a search. The
PII scrubber replaces it **before anything is stored**. It's on by default
(Site settings → Privacy).
## What it checks
Paths, referrer paths and every string property, with these rules:
| Rule | Finds | Replacement |
|---|---|---|
| `email` | Email addresses | `[redacted-email]` |
| `jwt` | JWT-like tokens (three base64 segments starting with `eyJ`) | `[redacted-token]` |
| `secret` | Values of `token=`, `key=`, `secret=`, `password=`, `pass=`, `auth=` and `session=` parameters | `[redacted]` |
| `uuid` | UUIDs | `[redacted-id]` |
| `long_id` | Hexadecimal ids of 32 characters or more | `[redacted-id]` |
| `digits` | Runs of 10 or more digits (spaces and dashes allowed), such as phone and card numbers | `[redacted-number]` |
For example `/reset?token=abc123` becomes `/reset?token=[redacted]` (if
`token` were an allowed parameter at all), and
`/users/jane@example.com` becomes `/users/[redacted-email]`.
## Custom rules
Add your own regular expressions in **Site settings → Privacy → PII
scrubber**, for example customer numbers like `CUST-\d{6}`. Matches become
`[redacted]`.
## Redaction log
The same tab shows how often each rule fired over the last 30 days, so you
can find and fix the leak at its source. We count redactions but never
keep the redacted values.
## It's a safety net
Fix leaks where they start: don't put personal data in URLs, and don't
send it as event properties. Use [path masks](/docs/tracker/exclusions-and-masking)
for ids in paths.
---
Source: https://privatusanalytics.com/docs/privacy/traffic-rules
# Traffic rules: block or allow hits
> Use traffic rules to block or allow analytics hits by hostname, path, referrer, country, IP range, browser or event, for example to skip your office or staging.
**Site settings → Traffic rules** has seven lists. Each list is either a
**block list** (matching hits are dropped) or an **allow list**
(everything else is dropped). An empty list does nothing.
| List | Matches | Example |
|---|---|---|
| Hostnames | The page's hostname | `staging.example.com`, `*.vercel.app` |
| Paths | The page path | `/admin/*`, `/internal/*` |
| Referrers | The referrer's hostname | `spam-site.example` |
| Countries | ISO country code | `XX` |
| IP ranges | The visitor's IP, IPv4 or IPv6 CIDR | `203.0.113.0/24` |
| User agents | Browser family and major version | `Chrome 79` |
| Events | Custom event names | `Test event` |
Patterns use `*` wildcards and are case-insensitive. IP ranges use CIDR
notation.
## The test box
Enter a URL, referrer, country or IP to see whether a hit would be
counted and which rule would drop it.
## Privacy
IP ranges are checked in memory during ingest, like everything else about
the IP. Blocked hits aren't stored. We only count them per list, shown in
the Overview's footer. Blocked hits don't count toward usage.
## Common uses
- Exclude your office or VPN: block its IP range.
- Ignore preview deployments: block `*.vercel.app` or `*.netlify.app`, or
allow only your production hostnames.
- Only count one country for a local site: allow list with that country.
---
Source: https://privatusanalytics.com/docs/privacy/dnt-gpc
# Do Not Track and Global Privacy Control
> How Privatus Analytics handles Global Privacy Control (honored by default) and Do Not Track signals, including server-side events and the effect on numbers.
The tracker reports two browser signals with every hit:
- **Global Privacy Control** (`navigator.globalPrivacyControl`): a signal
recognized by several US state laws (California, Colorado, Connecticut
and others) as an opt-out of sale and sharing.
- **Do Not Track** (`navigator.doNotTrack`): an older signal with no
legal force in most places.
What happens is a **site setting** (Site settings → Privacy):
| Signal | Default | When honoured |
|---|---|---|
| GPC | **Honoured** | Hits with GPC are dropped before processing and not counted |
| DNT | Not honoured | Turn it on to drop hits with DNT as well |
Privatus Analytics analytics isn't a "sale" or "sharing" of personal information, so
honoring GPC isn't strictly required. We do it by default as good faith.
Turn it off if you have a documented reason to count those visitors.
Dropped hits don't count toward usage and don't appear anywhere, so
dashboards undercount slightly (usually a few percent) when these
settings are on.
Server-side events can carry the signals as `dnt` and `gpc` fields. They're
honored the same way.
---
Source: https://privatusanalytics.com/docs/privacy/opt-out
# Analytics opt-out button snippet
> Copy a ready-made opt-out button for your privacy policy page that lets visitors stop being counted by Privatus Analytics in their browser, and how it works.
Visitors can opt out of being counted in their browser. Put this on your
privacy policy page. It works wherever the tracker is installed.
```html
<p id="privatus-optout-status">Checking…</p>
<button type="button" id="privatus-optout-button" hidden>Change</button>
<script>
(function () {
var status = document.getElementById('privatus-optout-status');
var button = document.getElementById('privatus-optout-button');
function render() {
if (!window.privatus || !privatus.isOptedOut) {
status.textContent = 'Analytics isn’t running in this browser, so your visits aren’t counted.';
return;
}
var out = privatus.isOptedOut();
status.textContent = out
? 'Your visits to this site are not counted.'
: 'Your visits are counted anonymously, without cookies.';
button.textContent = out ? 'Count my visits again' : 'Don’t count my visits';
button.hidden = false;
}
button.addEventListener('click', function () {
privatus.isOptedOut() ? privatus.optIn() : privatus.optOut();
render();
});
window.addEventListener('load', render);
})();
</script>
```
- The choice is stored as `privatus_optout=1` in `localStorage` on your
domain, only after the visitor clicks. That's the only thing Privatus Analytics
ever stores in a browser.
- It applies to this browser and this domain. Subdomains (`shop.`,
`blog.`) have their own storage, so add the button there too, or on each
domain you use.
- Clearing site data removes the choice.
- If the tracker is blocked (for example by an extension), the snippet
says so and hides the button: nothing is counted in that browser anyway.
WordPress: use the `[privatus_optout]` shortcode instead. The tracker API
behind this is described in [Opt-out](/docs/tracker/opt-out).
---
Source: https://privatusanalytics.com/docs/privacy/policy-templates
# Privacy policy templates for analytics
> Copy ready-made privacy policy paragraphs that describe Privatus Analytics, in English, German, French, Spanish, Dutch and Italian.
Copy the paragraph for your language into your privacy policy and adjust
the parts in square brackets. Have your counsel review the result.
## English
**Website analytics (Privatus Analytics)**
We use Privatus Analytics, a privacy-friendly analytics service provided by
[Privatus Analytics, legal entity and address], to understand how our
website is used. Privatus Analytics does not use cookies or similar technologies,
does not store any information on your device, and does not track you
across websites or devices.
When you visit our website, your IP address and browser information are
processed briefly, in memory only, to determine your country, to filter out bots, and to recognize page views that belong to
the same visit on the same day. For this, a pseudonymous key is created
from your IP address and browser information using a random value that
changes every day and is then deleted. Your IP address and this key are
never stored. This processing takes place in the United States, also for
visitors from the EU, the UK and Switzerland. The resulting data (for example the pages
visited, the referring website, the country, the browser and device type)
is stored in the United States and cannot be used to identify you.
The legal basis is our legitimate interest in analyzing and improving our
website (Art. 6(1)(f) GDPR). Data is transferred to the United States on
the basis of the EU Standard Contractual Clauses. You can opt out of analytics in your browser
[below / at link]. We honour the Global Privacy Control signal.
## Deutsch
**Webanalyse (Privatus Analytics)**
Wir nutzen Privatus Analytics, einen datenschutzfreundlichen Analysedienst
von [Privatus Analytics, Firma und Anschrift], um zu verstehen, wie unsere
Website genutzt wird. Privatus Analytics verwendet keine Cookies oder ähnliche
Technologien, speichert keine Informationen auf Ihrem Endgerät und
verfolgt Sie nicht über Websites oder Geräte hinweg.
Bei Ihrem Besuch werden Ihre IP-Adresse und Browserinformationen kurz und
ausschließlich im Arbeitsspeicher verarbeitet, um Ihr Land zu bestimmen, Bots herauszufiltern und Seitenaufrufe desselben
Besuchs am selben Tag zu erkennen. Dazu wird aus IP-Adresse und
Browserinformationen mit einem täglich wechselnden Zufallswert, der
anschließend gelöscht wird, ein pseudonymer Schlüssel gebildet. Ihre
IP-Adresse und dieser Schlüssel werden nie gespeichert. Diese Verarbeitung
erfolgt in den USA, auch für Besucher aus der EU, dem Vereinigten
Königreich und der Schweiz. Die daraus entstehenden Daten (zum Beispiel
besuchte Seiten, verweisende Website, Land, Browser und Gerätetyp) werden
in den USA gespeichert und lassen keinen Rückschluss auf Ihre Person zu.
Rechtsgrundlage ist unser berechtigtes Interesse an der Analyse und
Verbesserung unserer Website (Art. 6 Abs. 1 lit. f DSGVO). Die Übermittlung
in die USA erfolgt auf Grundlage der EU-Standardvertragsklauseln. Sie können der Analyse in Ihrem Browser
[unten / unter Link] widersprechen. Wir berücksichtigen das Signal Global
Privacy Control.
## Français
**Mesure d'audience (Privatus Analytics)**
Nous utilisons Privatus Analytics, un service de mesure d'audience
respectueux de la vie privée fourni par [Privatus Analytics, raison
sociale et adresse], pour comprendre l'utilisation de notre site.
Privatus Analytics n'utilise ni cookies ni technologies similaires, ne stocke
aucune information sur votre appareil et ne vous suit pas d'un site ou
d'un appareil à l'autre.
Lors de votre visite, votre adresse IP et les informations de votre
navigateur sont traitées brièvement, uniquement en mémoire, pour
déterminer votre pays, filtrer les
robots et reconnaître les pages vues appartenant à la même visite le même
jour. Pour cela, une clé pseudonyme est calculée à partir de votre adresse
IP et des informations du navigateur à l'aide d'une valeur aléatoire qui
change chaque jour puis est supprimée. Votre adresse IP et cette clé ne
sont jamais enregistrées. Ce traitement a lieu aux États-Unis, y compris
pour les visiteurs de l'UE, du Royaume-Uni et de la Suisse. Les données qui
en résultent
(par exemple les pages consultées, le site référent, le pays, le
navigateur et le type d'appareil) sont stockées aux États-Unis et ne
permettent pas de vous identifier.
La base légale est notre intérêt légitime à analyser et améliorer notre
site (art. 6, par. 1, point f) du RGPD). Le transfert vers les États-Unis
repose sur les clauses contractuelles types de l'UE. Vous pouvez vous
opposer à la mesure d'audience dans votre navigateur [ci-dessous / via ce
lien]. Nous respectons le signal Global Privacy Control.
## Español
**Analítica web (Privatus Analytics)**
Utilizamos Privatus Analytics, un servicio de analítica respetuoso con la
privacidad prestado por [Privatus Analytics, razón social y dirección],
para entender cómo se usa nuestro sitio web. Privatus Analytics no utiliza cookies
ni tecnologías similares, no almacena información en su dispositivo y no
le sigue entre sitios web ni dispositivos.
Cuando visita nuestro sitio, su dirección IP y la información de su
navegador se tratan brevemente, solo en memoria, para determinar su país, filtrar bots y reconocer las páginas vistas que
pertenecen a la misma visita en el mismo día. Para ello se genera una
clave seudónima a partir de su dirección IP y la información del navegador
con un valor aleatorio que cambia cada día y después se elimina. Su
dirección IP y esta clave nunca se almacenan. Este tratamiento se realiza
en Estados Unidos, también para los visitantes de la UE, el Reino Unido y
Suiza. Los datos
resultantes (por ejemplo, las páginas visitadas, el sitio de procedencia,
el país, el navegador y el tipo de dispositivo) se almacenan en Estados
Unidos y no permiten identificarle.
La base jurídica es nuestro interés legítimo en analizar y mejorar nuestro
sitio web (art. 6.1.f del RGPD). La transferencia a Estados Unidos se basa
en las cláusulas contractuales tipo de la UE. Puede oponerse a la analítica en su navegador
[más abajo / en este enlace]. Respetamos la señal Global Privacy Control.
## Nederlands
**Webstatistieken (Privatus Analytics)**
Wij gebruiken Privatus Analytics, een privacyvriendelijke dienst voor
webstatistieken van [Privatus Analytics, bedrijfsnaam en adres], om te
begrijpen hoe onze website wordt gebruikt. Privatus Analytics gebruikt geen cookies
of vergelijkbare technieken, slaat geen informatie op uw apparaat op en
volgt u niet over websites of apparaten heen.
Bij uw bezoek worden uw IP-adres en browsergegevens kort en uitsluitend in
het werkgeheugen verwerkt om uw land te bepalen, bots
te herkennen en paginaweergaven van hetzelfde bezoek op dezelfde dag te
herkennen. Daarvoor wordt uit uw IP-adres en browsergegevens een
gepseudonimiseerde sleutel berekend met een willekeurige waarde die
dagelijks wisselt en daarna wordt verwijderd. Uw IP-adres en deze sleutel
worden nooit opgeslagen. Deze verwerking vindt plaats in de Verenigde
Staten, ook voor bezoekers uit de EU, het Verenigd Koninkrijk en
Zwitserland. De resulterende
gegevens (bijvoorbeeld bezochte pagina's, de verwijzende website, het land,
de browser en het apparaattype) worden in de Verenigde Staten opgeslagen en
zijn niet tot u te herleiden.
De rechtsgrond is ons gerechtvaardigd belang bij het analyseren en
verbeteren van onze website (art. 6 lid 1 sub f AVG). De doorgifte naar de
Verenigde Staten is gebaseerd op de standaardcontractbepalingen van de EU. U kunt bezwaar maken tegen de
statistieken in uw browser [hieronder / via deze link]. Wij respecteren het
Global Privacy Control-signaal.
## Italiano
**Statistiche del sito (Privatus Analytics)**
Utilizziamo Privatus Analytics, un servizio di statistiche rispettoso della
privacy fornito da [Privatus Analytics, ragione sociale e indirizzo], per
capire come viene utilizzato il nostro sito. Privatus Analytics non utilizza cookie
né tecnologie simili, non memorizza informazioni sul suo dispositivo e non
la segue tra siti web o dispositivi.
Quando visita il nostro sito, il suo indirizzo IP e le informazioni del
browser sono trattati brevemente, solo in memoria, per determinare il suo
paese, filtrare i bot e riconoscere le pagine
visualizzate nella stessa visita nello stesso giorno. A tal fine viene
calcolata una chiave pseudonima dal suo indirizzo IP e dalle informazioni
del browser con un valore casuale che cambia ogni giorno e viene poi
cancellato. Il suo indirizzo IP e questa chiave non vengono mai
memorizzati. Questo trattamento avviene negli Stati Uniti, anche per i
visitatori dell'UE, del Regno Unito e della Svizzera. I dati risultanti (ad esempio le
pagine visitate, il sito di provenienza, il paese, il browser e il tipo di
dispositivo) sono conservati negli Stati Uniti e non consentono di
identificarla.
La base giuridica è il nostro legittimo interesse ad analizzare e
migliorare il sito (art. 6, par. 1, lett. f) GDPR). Il trasferimento
negli Stati Uniti si basa sulle clausole contrattuali tipo dell'UE. Può opporsi alle statistiche nel suo
browser [qui sotto / a questo link]. Rispettiamo il segnale Global Privacy
Control.
## Custom events and properties
If you send custom events or properties, describe them too, for example:
"We also count certain actions, such as newsletter sign-ups and purchases
(with the amount but no customer details)." Never send personal data as
properties.
---
Source: https://privatusanalytics.com/docs/privacy/dpia-lia
# DPIA and LIA templates for analytics
> Templates for a legitimate interests assessment (LIA) and a data protection impact assessment (DPIA) outline covering Privatus Analytics, ready to fill in.
These templates cover Privatus Analytics only. Fill in the bracketed parts,
add your other processing, and have your data protection officer or
counsel review them.
## Legitimate interests assessment (LIA)
### 1. Purpose test
- **Interest:** understanding how visitors use [website] to improve its
content, performance and conversion, and measuring marketing
effectiveness.
- **Why it matters:** [e.g. prioritizing content, fixing broken pages,
deciding campaign budgets].
- **Is the interest legitimate?** Yes: audience measurement is a normal,
expected activity for a website operator.
### 2. Necessity test
- **Is processing necessary?** Counting visits, sources and pages requires
processing requests to the website. Privatus Analytics minimizes this: no cookies,
no device storage, no persistent identifiers, IP addresses used in memory
only and never stored.
- **Less intrusive alternatives?** [Explain why you need visit and daily
visitor counts, e.g. to measure conversion rates and campaign
effectiveness, rather than raw pageview totals only.]
### 3. Balancing test
| Factor | Assessment |
|---|---|
| Nature of data | Pseudonymous for at most one day, then effectively anonymous aggregates. No special categories. PII scrubber redacts accidental personal data |
| Reasonable expectations | Visitors expect websites to count visits, and the privacy policy explains it |
| Impact on individuals | Minimal: no profiling, no cross-site tracking, no advertising use, no decisions about individuals |
| Safeguards | No cookies, daily salt destroyed, IP and User-Agent processed in memory only and never stored, opt-out, GPC honored, DPA and SCCs with Privatus Analytics |
| Vulnerable groups | [Consider if your site targets children] |
**Conclusion:** the legitimate interest is not overridden by the
interests or rights of visitors. [Date, name, role.]
## Data protection impact assessment (DPIA) outline
A DPIA is usually **not required** for Privatus Analytics alone, because it isn't
large-scale profiling, systematic monitoring of individuals or processing
of special categories. If your organization does one anyway (or your
regulator's list requires it), cover:
1. **Description:** purposes (audience measurement), data (see the
[data inventory](/docs/privacy/data-inventory)), recipients (Privatus Analytics as
processor and its subprocessors), retention ([your plan's retention]),
locations (US processing and storage, IP and User-Agent in memory only).
2. **Necessity and proportionality:** lawful basis (legitimate
interests, LIA above), minimization measures, transparency (privacy
policy) and data subject rights (opt-out, and no identifiable data is stored,
so access requests usually return nothing).
3. **Risks:** re-identification of visitors (mitigated: salt destroyed
daily, no IPs stored), accidental collection of personal data in URLs or
properties (mitigated: PII scrubber, query stripping, path masks,
redaction log), international transfer (mitigated: IP and User-Agent
processed in memory only and never stored, SCCs) and unauthorized access to the dashboard (mitigated: roles,
2FA, SSO, audit log).
4. **Measures and residual risk:** [low].
5. **Sign-off:** [DPO opinion, decision, date].
The [DPA](/legal/dpa) and the [subprocessor list](/legal/subprocessors)
are on our legal pages. The DPA includes our technical and organizational
measures.
---
Source: https://privatusanalytics.com/docs/api
# Analytics REST API
> The Privatus Analytics REST API: add .json to any app URL and send a token. Conventions and a reference of every operation, generated from the code.
Every page and action in Privatus Analytics is also an API endpoint. There's no
separate `/api/v1`: **add `.json` to a URL** and send an API token.
```sh
curl https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json?period=7d \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
```
```json
{
"data": {
"period": { "from": "2026-09-23T00:00:00Z", "to": "2026-09-30T00:00:00Z" },
"metrics": {
"visitors": 1840, "visits": 2310, "pageviews": 5122,
"views_per_visit": 2.22, "bounce_rate": 41.3,
"visit_duration": 48000, "revenue": 129900
}
}
}
```
The [reference below](#operations) lists every operation with its method,
path, permission, input schema and response schema. It's generated from
the running code, as is the **[OpenAPI 3.1 document](/openapi.json)**, so
neither can drift from what the server does. The same operations are
[MCP tools](/docs/mcp).
## Conventions
| | |
|---|---|
| Base URL | `https://privatusanalytics.com` |
| Format | JSON. Add `.json` to the path (or send `Accept: application/json`) |
| Auth | `Authorization: Bearer pat_…` ([Authentication](/docs/api/authentication)) |
| Ids | Public ids with a prefix: `ws_…` workspaces, `pa_…` sites, `seg_…` segments, `wh_…` webhooks |
| Reads | `GET` with query parameters |
| Writes | `POST`, `PATCH`, `DELETE` with a JSON body of flat fields |
| Success | `{ "data": … }`, plus `"meta"` for lists |
| Errors | `{ "error": { "code", "message", "details" } }` ([Errors](/docs/api/errors)) |
| Lists | `page` and `per_page` (max 100) ([Pagination](/docs/api/pagination)) |
| Times | ISO 8601 in UTC. Date parameters (`from`, `to`) are days in the site's timezone |
| Money | Minor units (cents) in the site currency, e.g. `revenue: 129900` = 1,299.00 |
| Durations | Milliseconds |
## Common tasks
| Task | Operation |
|---|---|
| List workspaces | `GET /workspaces.json` |
| List sites | `GET /workspaces/{workspace_id}/sites.json` |
| Headline metrics | `GET /sites/{site_id}/stats/aggregate.json` |
| Chart data | `GET /sites/{site_id}/stats/timeseries.json` |
| Top pages, sources, countries… | `GET /sites/{site_id}/breakdown/{dimension}.json` |
| Everything on the Overview | `GET /sites/{site_id}/overview.json` |
| Live visitors | `GET /sites/{site_id}/live.json` |
| Add a note (e.g. a deploy) | `POST /sites/{site_id}/notes.json` |
See [Stats endpoints](/docs/api/stats) and [Examples](/docs/api/examples).
## In this section
[Authentication](/docs/api/authentication) · [Errors](/docs/api/errors) ·
[Pagination](/docs/api/pagination) · [Rate limits](/docs/api/rate-limits) ·
[Filters](/docs/api/filters) · [Stats endpoints](/docs/api/stats) ·
[Examples](/docs/api/examples) · [Webhooks](/docs/api/webhooks) ·
[Changelog and deprecation](/docs/api/changelog)
Sending data in is a different API: see [Server-side ingest](/docs/server-side).
---
Source: https://privatusanalytics.com/docs/api/authentication
# API authentication and tokens
> Create API tokens for the Privatus Analytics REST API, choose permissions, sites, expiry and IP allowlists, and send them as Bearer tokens in requests.
## API tokens
Create a token in **Workspace settings → API tokens**. Choose:
- a **name**,
- **permissions**: any subset of your own (for example only
`analytics.read` for a dashboard integration),
- **sites**: all your sites, or only some,
- an optional **expiry date**,
- an optional **IP allowlist** (IPv4/IPv6 addresses or CIDR ranges).
The token (`pat_…`) is shown **once**. We store only a SHA-256 digest and
a short prefix so you can recognize it in the list.
```http
Authorization: Bearer pat_…
```
Requests with a token don't use cookies or CSRF tokens.
## What a token can do
A token acts as the member who created it, narrowed by its settings:
- **permissions** = the member's role ∩ the token's permissions,
- **sites** = the member's site access ∩ the token's sites.
If the member loses access, so does the token. See the
[permission matrix](/docs/teams/roles). Each operation in the
[reference](/docs/api) names the permission it needs.
A token belongs to one workspace. Using it on another workspace's
resources returns `403`.
## Errors
| Status | Code | Meaning |
|---|---|---|
| 401 | `unauthorized` | Missing, invalid, revoked or expired token |
| 403 | `forbidden` | The token's IP allowlist doesn't include your IP, or the token lacks the permission or site |
## Revoking
Revoke a token in the token list. Removing a member from a workspace
revokes their tokens for it. The list shows when each token was last used.
## Public endpoints
A few operations need no token: the docs (including `/docs/*.json`),
`/openapi.json`, and the collection endpoints (`/api/event`, `/api/pixel`,
while `/api/events` uses an [ingest key](/docs/server-side/ingest-keys)).
## OAuth
MCP clients can connect with OAuth 2.1 instead of a pasted token: see
[MCP authentication](/docs/mcp#authentication). OAuth-issued tokens are
ordinary API tokens you can see and revoke in your token list.
---
Source: https://privatusanalytics.com/docs/api/errors
# API errors and status codes
> The error format of the Privatus Analytics API, every HTTP status and error code (401, 402, 403, 422, 429 and more), and when to retry a failed request.
Errors always have the same shape:
```json
{
"error": {
"code": "validation_failed",
"message": "Name can't be blank",
"details": { "name": ["can't be blank"] }
}
}
```
`details` is present for validation errors: field names mapped to
messages.
| Status | `code` | When |
|---|---|---|
| 400 | `bad_request` | Malformed input, e.g. `filters` that isn't a JSON array |
| 401 | `unauthorized` | No token, or an invalid, revoked or expired one |
| 402 | `plan_limit` | A plan limit was reached (sites, goals, funnels, members…). The message says which and how to upgrade |
| 403 | `forbidden` | Missing permission or site access, or the token's IP allowlist |
| 404 | `not_found` | The record doesn't exist or you can't see it |
| 422 | `validation_failed` | Invalid input (see `details`) |
| 423 | `locked` | The workspace's dashboards are locked by Privatus Analytics support. Reaching the monthly limit never locks the API (see [Monthly limit](/docs/billing/overage)) |
| 429 | `rate_limited` | Too many requests ([Rate limits](/docs/api/rate-limits)) |
| 5xx | Any | Our fault. Retry with backoff and check the status page |
Handle errors by `code`, not by `message`: messages are for people and may
change.
## Retrying
- `GET` requests are always safe to retry.
- Retry `429` and `5xx` with exponential backoff.
- Don't retry `4xx` other than `429` without changing the request.
---
Source: https://privatusanalytics.com/docs/api/pagination
# API pagination
> Page through lists in the Privatus Analytics API with page and per_page (up to 100), read the meta object, and page through ranked stats breakdowns with limit.
List operations take `page` (from 1) and `per_page` (default 25, maximum
100) and return a `meta` object:
```sh
curl "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/goals.json?page=2&per_page=50" \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
```
```json
{
"data": [ … ],
"meta": { "page": 2, "per_page": 50, "total": 132, "total_pages": 3 }
}
```
Loop until `page` equals `total_pages`.
## Breakdowns
Stats breakdowns page differently, because they're ranked results rather
than records: use `limit` (rows per page, up to 1,000) and `page`:
```text
GET /sites/pa_7Q2K9XH3AB/breakdown/page.json?limit=1000&page=3
```
Keep requesting pages until a page returns fewer rows than `limit`.
---
Source: https://privatusanalytics.com/docs/api/rate-limits
# API rate limits
> API requests per hour for each Privatus Analytics plan, what a 429 rate_limited response means, and practical ways to stay under the limits with caching.
API limits are per API token, per hour, and depend on the workspace's plan:
| Plan | Requests / hour |
|---|---|
| Free | 1,000 |
| Pro | 5,000 |
| Business | 20,000 |
| Enterprise | Custom |
- API calls **never count** toward your event usage.
- When you exceed a limit you get `429` with the error code
`rate_limited`. Wait and retry with exponential backoff.
## Staying under the limits
- Stats responses are cached on our side and keyed by the site's latest
data, so asking for the same thing twice is cheap for us but still
counts as a request. Cache on your side too.
- Use one `overview` request instead of many small ones when you need
everything on the Overview.
- Ask for up to 1,000 breakdown rows per request instead of many small
pages.
- For bulk data, use [exports](/docs/reports/exports) or the warehouse
sync instead of paging through the API.
The [ingest API](/docs/server-side) has its own per-key limits and isn't
counted here.
## Email sending limits
Operations that send email have their own limits, whether you call them
from the app, the API or MCP. Over a limit you get `429` with the code
`rate_limited` and a `Retry-After` header (seconds), and nothing is sent.
| What | Limit |
|---|---|
| Team invitations | 20 per member an hour, 50 per workspace a day |
| Report recipient invites | 30 new invites per member an hour, 100 per workspace a day, 3 a week to one address from all workspaces |
| Report and channel tests | 10 per member an hour, 30 per workspace an hour |
| Site transfers | 20 per workspace a day |
| Any of these to one address | 10 a day per workspace |
Alert and uptime emails are grouped instead of refused: repeated alerts
for one rule become one email every 30 minutes, and a flapping uptime
check sends at most 6 emails an hour.
---
Source: https://privatusanalytics.com/docs/api/filters
# API filters and date periods
> One filter syntax for the dashboard, the API, MCP and exports. Learn the period, comparison and segment inputs and how to combine conditions with AND and OR.
Every stats operation accepts the same inputs:
| Parameter | Description |
|---|---|
| `period` | `today`, `yesterday`, `24h`, `7d`, `14d`, `28d`, `30d` (default), `90d`, `mtd`, `last_month`, `qtd`, `last_quarter`, `ytd`, `12mo`, `last_year`, `all`, `custom` |
| `from`, `to` | Dates (`YYYY-MM-DD`, inclusive) in the site's timezone, with `period=custom` |
| `compare` | `none` (default), `previous_period`, `previous_year`, `custom` |
| `compare_from`, `compare_to` | With `compare=custom` |
| `match_weekday` | `true` to align the comparison by day of the week |
| `filters` | See below |
| `segment_id` | Apply a saved segment (`seg_…`), combined with `filters` |
## Syntax
`filters` is a JSON array. Each item is a condition
`[dimension, operator, value]`. Items are combined with **AND**. Wrap
conditions in `{"any": [...]}` to combine them with **OR**.
```json
[
["page", "starts_with", "/blog"],
["country", "any_of", ["DE", "FR", "NL"]],
{ "any": [["channel", "is", "email"], ["utm_medium", "is", "newsletter"]] }
]
```
In URLs, send it URL-encoded:
```sh
curl -G "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json" \
--data-urlencode 'filters=[["page","starts_with","/blog"],["country","any_of",["DE","FR"]]]' \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
```
In JSON bodies and MCP tool calls, pass the array itself. Conditions can
also be objects: `{"dimension": "page", "operator": "is", "value": "/"}`.
Limits: 20 conditions in total, regular expressions up to 200 characters.
## Operators
| Operator | Value | Meaning |
|---|---|---|
| `is`, `is_not` | a string | Equals / doesn't equal |
| `any_of`, `none_of` | a list | Equals one of / none of |
| `contains`, `not_contains` | a string | Case-insensitive substring |
| `starts_with` | a string | Prefix |
| `regex`, `not_regex` | a string | Regular expression |
| `gt`, `lt` | a number | Greater / less than (numeric properties) |
| `between` | `[min, max]` | Inclusive range (numeric properties) |
## Dimensions
The same keys are used for filters and for
`/sites/{site_id}/breakdown/{dimension}`.
| Dimension | Label | Scope |
|---|---|---|
| `channel` | Channel | Visit (first touch) |
| `referrer` | Referrer | Visit (first touch) |
| `referrer_url` | Referrer URL | Visit (first touch) |
| `utm_source` | UTM source | Visit (first touch) |
| `utm_medium` | UTM medium | Visit (first touch) |
| `utm_campaign` | UTM campaign | Visit (first touch) |
| `utm_content` | UTM content | Visit (first touch) |
| `utm_term` | UTM term | Visit (first touch) |
| `ref` | Ref | Visit (first touch) |
| `hostname` | Hostname | Visit (first touch) |
| `country` | Country | Visit (first touch) |
| `language` | Language | Visit (first touch) |
| `device` | Device | Visit (first touch) |
| `browser` | Browser | Visit (first touch) |
| `browser_version` | Browser version | Visit (first touch) |
| `os` | Operating system | Visit (first touch) |
| `os_version` | OS version | Visit (first touch) |
| `screen` | Screen size | Visit (first touch) |
| `entry_page` | Entry page | Visit only |
| `exit_page` | Exit page | Visit only |
| `interaction` | Interaction | Visit only |
| `page` | Page | Event / page |
| `event` | Event | Event / page |
| `goal` | Goal | Goal |
| `prop:<key>` | Custom property value, e.g. `prop:plan` | Event |
- **Visit (first touch)** dimensions describe how a visit started. Events
carry their visit's values, so "country is DE" works for events too.
- **Visit only**: entry and exit pages.
- **Event / page**: `page` filters visits that viewed a page, and `event`
filters visits in which an event happened.
- **Goal**: `["goal", "is", "<goal id>"]` filters visits that converted.
- **Properties:** `prop:<key>`, e.g. `["prop:plan", "is", "pro"]`, or
`["prop:seats", "gt", 5]`.
Channel values are the keys listed in [Channels](/docs/metrics/channels)
(`organic_search`, `ai_assistants`…). Countries are ISO 3166-1 alpha-2
codes. There are no region or city dimensions.
## Errors
An unknown dimension or operator, a list operator without a list, or an
invalid regex returns `422 validation_failed` with the reason in
`message`. Filters that aren't valid JSON return `400 bad_request`.
---
Source: https://privatusanalytics.com/docs/api/stats
# Stats API endpoints
> Query the aggregate, timeseries, breakdown and overview stats API endpoints (also MCP tools) with periods, comparisons and filters, and read example responses.
All four accept the [period, comparison and filter inputs](/docs/api/filters)
and need the `analytics.read` permission.
## Aggregate
`GET /sites/{site_id}/stats/aggregate.json` · MCP `stats_aggregate`
```sh
curl "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json?period=30d&compare=previous_period" \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
```
```json
{
"data": {
"period": { "from": "2026-08-31T00:00:00+02:00", "to": "2026-09-30T00:00:00+02:00" },
"metrics": { "visitors": 8120, "visits": 10433, "pageviews": 24871, "views_per_visit": 2.38,
"bounce_rate": 38.9, "visit_duration": 52000, "revenue": 1254300 },
"comparison_period": { "from": "2026-08-01T00:00:00+02:00", "to": "2026-08-31T00:00:00+02:00" },
"comparison": { "visitors": 7410, "…": "…" },
"change": { "visitors": 9.6, "visits": 7.1, "…": "…" }
}
}
```
- `visit_duration` is the median engaged time in milliseconds.
- `bounce_rate` is a percentage.
- `revenue` is in minor units of the site currency.
- `change` is the percentage change, or `null` when the previous value is
zero.
## Timeseries
`GET /sites/{site_id}/stats/timeseries.json` · MCP `stats_timeseries`
Extra input: `interval` = `auto` (default), `minute`, `hour`, `day`,
`week`, `month`, `quarter`, `year`.
```json
{
"data": {
"period": { "from": "…", "to": "…" },
"interval": "day",
"series": [
{ "date": "2026-09-28T00:00:00Z", "visitors": 301, "visits": 377, "pageviews": 902,
"views_per_visit": 2.39, "bounce_rate": 37.1, "visit_duration": 51000, "revenue": 0 }
],
"comparison_series": [ … ]
}
}
```
`date` is the start of each bucket as wall-clock time in the site's
timezone (written with a `Z` suffix), so `2026-09-28T00:00:00Z` means
"September 28" in the site's timezone. Empty buckets are included with
zeros.
## Breakdown
`GET /sites/{site_id}/breakdown/{dimension}.json` · MCP `stats_breakdown`
Extra inputs: `limit` (default 10, max 1,000), `page`, `sort`
(`visitors`, `visits`, `pageviews`, `revenue`). `dimension` is any key from
[Filters › Dimensions](/docs/api/filters#dimensions), including
`prop:<key>`.
```sh
curl "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/channel.json?period=7d" \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
```
```json
{
"data": {
"period": { "…": "…" }, "dimension": "channel", "label": "Channel",
"page": 1, "limit": 10,
"rows": [
{ "value": "organic_search", "visitors": 912, "visits": 1104, "pageviews": 2710, "share": 41.2, "…": "…" },
{ "value": "direct", "visitors": 603, "…": "…", "share": 27.3 }
]
}
}
```
The columns depend on the dimension: visit dimensions return visit
metrics, `page` returns pageviews, visits, time on page and scroll depth,
and `event` and `goal` return completions, conversions, conversion rate and
revenue. The [reference](/docs/api) has the exact schema. Swap `.json`
for `.csv` to download rows as CSV.
## Overview
`GET /sites/{site_id}/overview.json` · MCP `stats_overview`
Everything the Overview page shows (metrics, the chart series and the top
rows of each panel) in one request.
---
Source: https://privatusanalytics.com/docs/api/examples
# API code examples
> Fetch top pages from the analytics API with curl, JavaScript, Python, PHP, Go and Ruby. Copy working code examples with filters, periods and a Bearer token.
Each example fetches last week's top pages. Keep your token in
`PRIVATUS_TOKEN`.
## curl
```sh
curl -G "https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/page.json" \
--data-urlencode "period=7d" \
--data-urlencode "limit=20" \
--data-urlencode 'filters=[["channel","is","organic_search"]]' \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
```
## JavaScript (Node.js 18+ or the browser's fetch on your server)
```js
const params = new URLSearchParams({
period: '7d',
limit: '20',
filters: JSON.stringify([['channel', 'is', 'organic_search']]),
})
const response = await fetch(
`https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/page.json?${params}`,
{ headers: { Authorization: `Bearer ${process.env.PRIVATUS_TOKEN}` } },
)
if (!response.ok) throw new Error((await response.json()).error.message)
const { data } = await response.json()
for (const row of data.rows) console.log(row.value, row.pageviews)
```
Never use an API token in browser code: it would be visible to everyone.
## Python
```python
import json, os, requests
response = requests.get(
"https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/page.json",
params={"period": "7d", "limit": 20,
"filters": json.dumps([["channel", "is", "organic_search"]])},
headers={"Authorization": f"Bearer {os.environ['PRIVATUS_TOKEN']}"},
timeout=30,
)
response.raise_for_status()
for row in response.json()["data"]["rows"]:
print(row["value"], row["pageviews"])
```
## PHP
```php
<?php
$query = http_build_query([
'period' => '7d',
'limit' => 20,
'filters' => json_encode([['channel', 'is', 'organic_search']]),
]);
$context = stream_context_create(['http' => [
'header' => 'Authorization: Bearer ' . getenv('PRIVATUS_TOKEN'),
]]);
$json = file_get_contents("https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/page.json?$query", false, $context);
foreach (json_decode($json, true)['data']['rows'] as $row) {
echo $row['value'], ' ', $row['pageviews'], PHP_EOL;
}
```
## Go
```go
q := url.Values{}
q.Set("period", "7d")
q.Set("limit", "20")
q.Set("filters", `[["channel","is","organic_search"]]`)
req, _ := http.NewRequest("GET",
"https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/page.json?"+q.Encode(), nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("PRIVATUS_TOKEN"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
var body struct {
Data struct {
Rows []struct {
Value string `json:"value"`
Pageviews int `json:"pageviews"`
} `json:"rows"`
} `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&body)
```
## Ruby
```ruby
require "net/http"
require "json"
uri = URI("https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/breakdown/page.json")
uri.query = URI.encode_www_form(period: "7d", limit: 20,
filters: [["channel", "is", "organic_search"]].to_json)
request = Net::HTTP::Get.new(uri, "Authorization" => "Bearer #{ENV.fetch('PRIVATUS_TOKEN')}")
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
JSON.parse(response.body)["data"]["rows"].each { |row| puts "#{row['value']} #{row['pageviews']}" }
```
## Writing: add a deploy note
```sh
curl -X POST https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Deployed v2.4.0", "date": "2026-09-29", "source": "deploy"}'
```
Check the [reference](/docs/api) for each operation's exact fields. The
official [SDKs](/docs/server-side/sdks) for Node.js, Python, PHP, Go and
Ruby wrap these calls too.
---
Source: https://privatusanalytics.com/docs/api/webhooks
# Webhooks for analytics events
> Receive signed webhooks when alerts fire, uptime changes, exports finish or sites change, and verify the HMAC-SHA256 signature in Node.js, Python or Ruby.
**Workspace settings → Webhooks → Add endpoint.** Enter an `https` URL and
choose the events. A **signing secret** (`whsec_…`) is created for the
endpoint.
## Events
| Event | Sent when |
|---|---|
| `alert.triggered` | An alert fired |
| `alert.resolved` | An alert recovered |
| `goal.completed_threshold` | A goal reached its completion threshold |
| `uptime.down` | An uptime check started failing |
| `uptime.up` | An uptime check recovered |
| `export.ready` | An export is ready to download |
| `import.completed` | An import finished |
| `site.created` | A site was added |
| `site.deleted` | A site was deleted |
| `member.added` | A member joined the workspace |
| `usage.threshold` | Usage crossed a share of the plan allowance |
**Send test** delivers a `webhook.test` event.
## Request
```http
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Privatus-Webhooks/1.0
Privatus-Event: uptime.down
Privatus-Delivery: whd_…
Privatus-Signature: t=1790000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```
```json
{
"id": "whd_…",
"event": "uptime.down",
"created_at": "2026-09-29T10:15:00Z",
"workspace_id": "ws_7Q2K9XH3AB",
"data": { "…": "event-specific fields" }
}
```
Respond with any `2xx` within 10 seconds. Anything else, or a timeout,
counts as a failure and is retried up to 8 times with exponential backoff
(from about a minute to a few hours). Test deliveries aren't retried. The delivery log shows
every attempt with its status and response, and you can **redeliver** any
delivery. After 20 consecutive failures the endpoint is disabled. Fix it
and re-enable it.
## Verify the signature
`Privatus-Signature` is `t=<unix time>,v1=<hex HMAC-SHA256>` where the HMAC
is computed with your signing secret over `"<t>.<raw request body>"`.
Reject requests whose signature doesn't match or whose `t` is more than
five minutes old.
```js
import crypto from 'node:crypto'
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}
```
```python
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return abs(time.time() - int(parts["t"])) < 300 and hmac.compare_digest(expected, parts["v1"])
```
```ruby
def verify(raw_body, header, secret)
parts = header.split(",").to_h { |p| p.split("=", 2) }
expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{parts['t']}.#{raw_body}")
(Time.now.to_i - parts["t"].to_i).abs < 300 &&
ActiveSupport::SecurityUtils.secure_compare(expected, parts["v1"])
end
```
Use the **raw** body as received. Re-serializing the JSON changes it.
## Security
We only deliver to public addresses (never to private or internal
networks), from the User-Agent `Privatus-Webhooks/1.0`. Webhooks are
available on Pro and above.
---
Source: https://privatusanalytics.com/docs/api/changelog
# API changelog and deprecation policy
> How the Privatus Analytics API evolves: additive changes within a version, at least 6 months of notice for breaking changes, and where to follow the changelog.
## Compatibility
The API is generated from the same operations as the app, so new features
appear in the API and MCP the day they ship. Within the current version we
only make **additive** changes:
- new operations, new optional inputs, new response fields, new enum
values, new webhook events,
- new error `details`.
Write clients that ignore unknown fields and handle unknown enum values.
## Breaking changes
Removing or renaming an operation, input or field, or changing its type,
is a breaking change. We:
1. announce it in the changelog and by email to owners of workspaces whose
tokens used the affected operation in the last 90 days,
2. keep the old behavior working for at least **6 months**,
3. mark deprecated operations and fields in the
[reference](/docs/api) and [OpenAPI document](/openapi.json).
## Changelog
Product and API changes are published on the changelog page of the
website, with an RSS feed. Tracker releases also appear as automatic
[notes](/docs/dashboard/notes) on your charts.
---
Source: https://privatusanalytics.com/docs/mcp
# MCP analytics server
> Connect Claude, ChatGPT, Gemini, Cursor and other AI agents to your analytics with the Privatus Analytics MCP server: endpoint, OAuth, tokens and tool names.
Privatus Analytics runs a hosted **Model Context Protocol** server. Every [API
operation](/docs/api) you're allowed to use is an MCP tool, so an agent can
read your stats, create goals, add notes or check uptime with the same
permissions as your API token.
| | |
|---|---|
| Endpoint | `https://privatusanalytics.com/mcp` |
| Transport | Streamable HTTP (JSON responses) |
| Auth | `Authorization: Bearer pat_…` or OAuth 2.1 |
Set it up in your client: [Claude, ChatGPT, Gemini CLI, Cursor and VS Code](/docs/mcp/clients).
## Authentication
**API token.** Create a token in Workspace settings → API tokens and send
it as a Bearer token. Give the token only the permissions the agent needs.
For read-only analysis, `analytics.read` is enough. See
[Authentication](/docs/api/authentication).
**OAuth.** Clients that support MCP authorization can connect with just
the URL. The server publishes its metadata at
`/.well-known/oauth-protected-resource` and
`/.well-known/oauth-authorization-server`, supports dynamic client
registration (`/oauth/register`) and the authorization code flow with PKCE
(S256). You sign in, choose the workspace, and approve. The client
receives an API token that appears in your token list, where you can
revoke it.
## Tool names
Tools are named `<resource>_<verb>`:
| Verb | HTTP | Example |
|---|---|---|
| `list` | `GET` a collection | `sites_list`, `goals_list` |
| `get` | `GET` one record | `sites_get` |
| `create` | `POST` | `goals_create`, `notes_create` |
| `update` | `PATCH` | `sites_update` |
| `delete` | `DELETE` | `goals_delete` |
| other actions | as named | `goals_duplicate`, `stats_breakdown`, `docs_search` |
Each tool's input schema is the operation's inputs plus its path
parameters (`site_id`, `workspace_id`…). Read tools are marked
read-only and `DELETE` tools destructive, so clients can ask before
running them.
The server only lists tools your token's permissions allow. Tool calls go
through the same routes, permission checks and validation as the API.
## Start here
Agents usually begin with:
1. `workspaces_list` → your workspace id (`ws_…`).
2. `sites_list` with `workspace_id` → site ids (`pa_…`).
3. `stats_aggregate`, `stats_timeseries`, `stats_breakdown` or
`stats_overview` with `site_id`, `period` and `filters`
([filter syntax](/docs/api/filters)).
4. `docs_search` and `docs_get` to read these docs.
See [Examples](/docs/mcp/examples).
## All tools
Generated from the running code. The [API reference](/docs/api) has each
tool's full input and output schema.
### API tokens
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `api_tokens_create` | `POST /workspaces/:workspace_id/api_tokens` | Create an API token (the token is returned once) | public |
| `api_tokens_delete` | `DELETE /workspaces/:workspace_id/api_tokens/:id` | Revoke an API token | public |
| `api_tokens_list` | `GET /workspaces/:workspace_id/api_tokens` | List API tokens | public |
### Account
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `account_get` | `GET /account` | Get your profile and preferences | public |
| `account_update` | `PATCH /account` | Update your profile and preferences | public |
### Affiliate program
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `affiliate_commissions_list` | `GET /account/affiliate/commissions` | List your affiliate commissions | public |
| `affiliate_signup_box_get` | `GET /account/affiliate/signup-box` | Get your affiliate signup box code and results | public |
| `affiliate_get` | `GET /account/affiliate` | Get your affiliate status, referral link and stats | public |
### Alerts
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `alerts_acknowledge` | `POST /alerts/:id/acknowledge` | Acknowledge the latest incident | `analytics.read` |
| `alerts_create` | `POST /workspaces/:workspace_id/alerts` | Create an alert | `content.write` |
| `alerts_delete` | `DELETE /alerts/:id` | Delete an alert | `content.write` |
| `alerts_history` | `GET /alerts/:id/history` | Incident history of an alert | `analytics.read` |
| `alerts_list` | `GET /workspaces/:workspace_id/alerts` | List alerts | `analytics.read` |
| `alerts_mute` | `POST /alerts/:id/mute` | Mute (or unmute) an alert’s notifications | `content.write` |
| `alerts_get` | `GET /alerts/:id` | Get an alert | `analytics.read` |
| `alerts_update` | `PATCH /alerts/:id` | Update an alert | `content.write` |
| `site_alerts_list` | `GET /sites/:site_id/alerts` | List alerts for a site | `analytics.read` |
### Analytics
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `stats_overview` | `GET /sites/:site_id/overview` | Site overview: metrics, chart series, top panels, live visitors and notes | `analytics.read` |
| `experiments_report` | `GET /sites/:site_id/experiments` | Experiment report: conversion rate per variant, uplift vs control and significance (two-proportion z-test) | `analytics.read` |
| `insights_get` | `GET /sites/:site_id/insights` | Notable changes vs the previous period, in plain English (biggest movers, goal conversion changes) | `analytics.read` |
| `journeys_explore` | `GET /sites/:site_id/journeys` | Journeys: top 3-step paths after a page (or any entrance), or before a page or goal | `analytics.read` |
| `pages_detail` | `GET /sites/:site_id/pages/detail` | Page detail: metrics, previous and next pages, sources, Web Vitals, events and click map for one path | `analytics.read` |
| `stats_aggregate` | `GET /sites/:site_id/stats/aggregate` | Headline metrics for a period (with comparison) | `analytics.read` |
| `stats_breakdown` | `GET /sites/:site_id/breakdown/:dimension` | Top values of a dimension (pages, sources, countries…) | `analytics.read` |
| `stats_timeseries` | `GET /sites/:site_id/stats/timeseries` | Metrics per time bucket for charts | `analytics.read` |
### Assistant
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `assistant_ask` | `POST /sites/:site_id/ask` | Ask a question in a new conversation (counts toward the monthly AI questions limit) | `analytics.read` |
| `assistant_conversations_delete` | `DELETE /sites/:site_id/ask/:id` | Delete an Ask conversation and its messages | `analytics.read` |
| `assistant_conversations_list` | `GET /sites/:site_id/ask` | List your Ask conversations for a site | `analytics.read` |
| `assistant_conversations_get` | `GET /sites/:site_id/ask/:id` | An Ask conversation: questions, answers, the queries behind them and charts | `analytics.read` |
| `assistant_ask_followup` | `POST /sites/:site_id/ask/:ask_conversation_id/messages` | Ask a follow-up question in a conversation (counts toward the monthly AI questions limit). Returns the answer. | `analytics.read` |
### Audit log
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `audit_logs_get` | `GET /workspaces/:workspace_id/audit_log` | List audit log entries (add .csv to export) | `workspace.manage` |
### Billing
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `billing_badge` | `POST /workspaces/:workspace_id/billing/badge` | Opt in or out of the badge bonus (free plan) | `billing.manage` |
| `billing_cancel` | `POST /workspaces/:workspace_id/billing/cancel` | Cancel at the end of the billing period | `billing.manage` |
| `billing_change_plan` | `POST /workspaces/:workspace_id/billing/change_plan` | Change plan, tier or interval (prorated) | `billing.manage` |
| `billing_checkout` | `POST /workspaces/:workspace_id/billing/checkout` | Start a Paddle checkout for a paid plan | `billing.manage` |
| `billing_discount` | `POST /workspaces/:workspace_id/billing/discount` | Apply for a discount program (nonprofit, education, open source or agency) | `billing.manage` |
| `billing_payment_method` | `POST /workspaces/:workspace_id/billing/payment_method` | Get a link to update the payment method | `billing.manage` |
| `billing_portal` | `POST /workspaces/:workspace_id/billing/portal` | Get a Paddle customer portal link | `billing.manage` |
| `billing_preview` | `GET /workspaces/:workspace_id/billing/preview` | Preview a plan change with proration | `billing.manage` |
| `billing_resume` | `POST /workspaces/:workspace_id/billing/resume` | Undo a scheduled cancellation or resume a pause | `billing.manage` |
| `billing_get` | `GET /workspaces/:workspace_id/billing` | Get the plan, subscription and usage | `billing.manage` |
| `billing_update` | `PATCH /workspaces/:workspace_id/billing` | Update billing emails, tax id and auto-upgrade | `billing.manage` |
| `billing_usage` | `GET /workspaces/:workspace_id/billing/usage` | Get this month's usage, forecast and per-site split | `billing.manage` |
| `billing_invoices_list` | `GET /workspaces/:workspace_id/billing/invoices` | List invoices | `billing.manage` |
| `billing_invoices_get` | `GET /workspaces/:workspace_id/billing/invoices/:id` | Get the PDF link for an invoice | `billing.manage` |
### Campaigns
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `campaign_costs_create` | `POST /sites/:site_id/campaigns/costs` | Set the spend for a campaign in a month | `content.write` |
| `campaign_costs_delete` | `DELETE /sites/:site_id/campaigns/costs/:id` | Delete a campaign cost entry | `content.write` |
| `campaign_costs_import` | `POST /sites/:site_id/campaigns/costs/import` | Import campaign costs from CSV (campaign,month,amount[,currency]) | `content.write` |
| `campaign_costs_list` | `GET /sites/:site_id/campaigns/costs` | List campaign cost entries | `analytics.read` |
| `campaign_costs_update` | `PATCH /sites/:site_id/campaigns/costs/:id` | Change a campaign cost entry | `content.write` |
| `campaigns_builder` | `GET /sites/:site_id/campaigns/builder` | Build and validate a UTM-tagged URL | `analytics.read` |
| `campaigns_hygiene` | `GET /sites/:site_id/campaigns/hygiene` | UTM hygiene: near-duplicate values, style issues and unknown sources | `analytics.read` |
| `campaigns_list` | `GET /sites/:site_id/campaigns` | Campaign rollup with conversions, revenue, cost, CPA and ROAS | `analytics.read` |
| `links_create` | `POST /sites/:site_id/campaigns/links` | Save a UTM-tagged link to the library | `content.write` |
| `links_delete` | `DELETE /sites/:site_id/campaigns/links/:id` | Delete a saved link | `content.write` |
| `links_list` | `GET /sites/:site_id/campaigns/links` | List saved campaign links | `analytics.read` |
| `links_qr` | `GET /sites/:site_id/campaigns/links/:id/qr` | QR code (SVG) for a saved link | `analytics.read` |
| `links_get` | `GET /sites/:site_id/campaigns/links/:id` | Get a saved campaign link | `analytics.read` |
| `links_update` | `PATCH /sites/:site_id/campaigns/links/:id` | Change a saved link | `content.write` |
### Channel rules
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `channel_rules_create` | `POST /sites/:site_id/channel_rules` | Add a channel rule | `sites.manage` |
| `channel_rules_delete` | `DELETE /sites/:site_id/channel_rules/:id` | Delete a channel rule | `sites.manage` |
| `channel_rules_list` | `GET /sites/:site_id/channel_rules` | List channel rules in order | `analytics.read` |
| `channel_rules_move` | `PATCH /sites/:site_id/channel_rules/:id/move` | Move a channel rule up or down | `sites.manage` |
| `channel_rules_preview` | `POST /sites/:site_id/channel_rules/preview` | Preview the channel for a sample referrer and UTM tags | `analytics.read` |
| `channel_rules_update` | `PATCH /sites/:site_id/channel_rules/:id` | Change a channel rule | `sites.manage` |
### Crawlers
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `crawlers_cloudflare_connect` | `POST /sites/:site_id/crawlers/connection` | Sync AI crawler hits from a Cloudflare zone (needs a Cloudflare grant from the browser) | `sites.manage` |
| `crawlers_cloudflare_disconnect` | `DELETE /sites/:site_id/crawlers/connection` | Disconnect Cloudflare and delete the crawler hits it imported | `sites.manage` |
| `crawlers_cloudflare_sync` | `POST /sites/:site_id/crawlers/sync` | Import crawler hits from Cloudflare now | `sites.manage` |
| `crawlers_cloudflare_zones` | `GET /sites/:site_id/crawlers/zones` | List the Cloudflare zones you can connect (needs a Cloudflare grant from the browser) | `sites.manage` |
| `crawlers_report` | `GET /sites/:site_id/crawlers` | AI crawlers report: hits by crawler over time, top paths per crawler, by category | `analytics.read` |
### Dashboards
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `dashboards_card` | `GET /workspaces/:workspace_id/dashboards/:id/cards/:index` | Data for one card of a custom dashboard | `analytics.read` |
| `dashboards_create` | `POST /workspaces/:workspace_id/dashboards` | Create a custom dashboard | `content.write` |
| `dashboards_delete` | `DELETE /workspaces/:workspace_id/dashboards/:id` | Delete a custom dashboard | `content.write` |
| `dashboards_list` | `GET /workspaces/:workspace_id/dashboards` | List custom dashboards | `analytics.read` |
| `dashboards_get` | `GET /workspaces/:workspace_id/dashboards/:id` | Get a custom dashboard and its cards | `analytics.read` |
| `dashboards_update` | `PATCH /workspaces/:workspace_id/dashboards/:id` | Rename a custom dashboard or replace its cards | `content.write` |
### Documentation
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `docs_api` | `GET /docs/api` | List every API operation and MCP tool | public |
| `docs_list` | `GET /docs` | List documentation pages | public |
| `docs_openapi` | `GET /openapi` | OpenAPI 3.1 document for the whole API | public |
| `docs_search` | `GET /docs/search` | Search the documentation | public |
| `docs_get` | `GET /docs/:section/:page` | Read a documentation page (Markdown and HTML) | public |
### Email reports
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `email_report_recipients_delete` | `DELETE /recipients/:id` | Remove a recipient from an email report | `content.write` |
| `email_report_recipients_list` | `GET /reports/:report_id/recipients` | List the recipients of an email report with their status | `analytics.read` |
| `email_report_recipients_resend` | `POST /recipients/:id/resend` | Resend a pending report invite | `content.write` |
| `email_reports_create` | `POST /workspaces/:workspace_id/reports` | Create an email report | `content.write` |
| `email_reports_deliveries` | `GET /reports/:id/deliveries` | Delivery log of an email report | `analytics.read` |
| `email_reports_delete` | `DELETE /reports/:id` | Delete an email report | `content.write` |
| `email_reports_list` | `GET /workspaces/:workspace_id/reports` | List email reports | `analytics.read` |
| `email_reports_send_test` | `POST /reports/:id/send_test` | Send an email report now as a test | `content.write` |
| `email_reports_get` | `GET /reports/:id` | Get an email report | `analytics.read` |
| `email_reports_update` | `PATCH /reports/:id` | Update an email report | `content.write` |
### Events
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `event_properties_list` | `GET /sites/:site_id/events/properties` | List event property keys seen in the last 30 days | `analytics.read` |
| `event_properties_update` | `PATCH /sites/:site_id/events/properties` | Rename or hide an event property key | `sites.manage` |
| `events_delete` | `DELETE /sites/:site_id/events` | Delete an event and its history (runs in the background, confirm by typing the name) | `sites.manage` |
| `events_list` | `GET /sites/:site_id/events` | List events with completions, visits, conversion rate and first/last seen | `analytics.read` |
| `events_merge` | `POST /sites/:site_id/events/merge` | Merge several events into one display name | `sites.manage` |
| `events_get` | `GET /sites/:site_id/events/detail` | One event: chart, property pivot, number property aggregates, pages and sources | `analytics.read` |
| `events_update` | `PATCH /sites/:site_id/events/settings` | Rename, hide or unhide an event, or set its currency | `sites.manage` |
### Exports
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `exports_create` | `POST /workspaces/:workspace_id/exports` | Queue an export (built in the background) | `analytics.export` |
| `exports_delete` | `DELETE /exports/:id` | Delete an export and its file | `analytics.export` |
| `exports_download` | `GET /exports/:id/download` | Get a signed link to the file (valid 10 minutes) | `analytics.export` |
| `exports_list` | `GET /workspaces/:workspace_id/exports` | List exports (the job queue) | `analytics.export` |
| `exports_preview` | `POST /workspaces/:workspace_id/exports/preview` | Preview an export: first 20 rows and the estimated row count | `analytics.export` |
| `exports_get` | `GET /exports/:id` | Get an export and its status | `analytics.export` |
### Funnels
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `funnels_create` | `POST /sites/:site_id/funnels` | Create a funnel | `content.write` |
| `funnels_delete` | `DELETE /sites/:site_id/funnels/:id` | Delete a funnel | `content.write` |
| `funnels_list` | `GET /sites/:site_id/funnels` | List funnels with entries, completions and rate | `analytics.read` |
| `funnels_get` | `GET /sites/:site_id/funnels/:id` | Funnel report: step counts, conversion, drop-off, time between steps and where visits went instead | `analytics.read` |
| `funnels_update` | `PATCH /sites/:site_id/funnels/:id` | Update a funnel | `content.write` |
### Goals
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `goals_archive` | `POST /sites/:site_id/goals/:id/archive` | Archive a goal (hidden from reports) | `content.write` |
| `goals_create` | `POST /sites/:site_id/goals` | Create a goal | `content.write` |
| `goals_delete` | `DELETE /sites/:site_id/goals/:id` | Delete a goal (data is kept) | `content.write` |
| `goals_duplicate` | `POST /sites/:site_id/goals/:id/duplicate` | Copy a goal | `content.write` |
| `goals_list` | `GET /sites/:site_id/goals` | List goals with completions, conversions, rate and value for a period | `analytics.read` |
| `goals_get` | `GET /sites/:site_id/goals/:id` | Goal report: metrics, chart, breakdowns and the journey to converting | `analytics.read` |
| `goals_unarchive` | `POST /sites/:site_id/goals/:id/unarchive` | Restore an archived goal | `content.write` |
| `goals_update` | `PATCH /sites/:site_id/goals/:id` | Update a goal | `content.write` |
### Help and feedback
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `support_message_send` | `POST /help` | Send a question or feedback to the Privatus Analytics team | public |
### Imports
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `imports_google_properties` | `GET /sites/:site_id/imports/google/properties` | List Google Analytics 4 properties to import | `sites.manage` |
| `imports_create` | `POST /sites/:site_id/imports` | Start an import (GA4 property or CSV upload) | `sites.manage` |
| `imports_delete` | `DELETE /sites/:site_id/imports/:id` | Delete an import and all its imported data | `sites.manage` |
| `imports_list` | `GET /sites/:site_id/imports` | List imports for a site | `analytics.read` |
| `imports_get` | `GET /sites/:site_id/imports/:id` | Get an import and its status | `analytics.read` |
### Live
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `live_get` | `GET /sites/:site_id/live` | Live visitors, activity stream and what is popular right now (last 30 minutes) | `analytics.read` |
| `live_wallboard` | `GET /sites/:site_id/live/wallboard` | Wallboard cards (live and today) for one or more sites | `analytics.read` |
| `wallboard_links_create` | `POST /sites/:site_id/live/wallboard/links` | Create a wallboard link (read-only, revocable) | `sites.manage` |
| `wallboard_links_delete` | `DELETE /sites/:site_id/live/wallboard/links/:id` | Revoke a wallboard link | `sites.manage` |
| `wallboard_links_list` | `GET /sites/:site_id/live/wallboard/links` | List wallboard links for a site | `sites.manage` |
### Members
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `invitations_create` | `POST /workspaces/:workspace_id/invitations` | Invite people by email | `members.manage` |
| `invitations_delete` | `DELETE /workspaces/:workspace_id/invitations/:id` | Revoke a pending invitation | `members.manage` |
| `invitations_list` | `GET /workspaces/:workspace_id/invitations` | List pending invitations | `members.manage` |
| `members_delete` | `DELETE /workspaces/:workspace_id/members/:id` | Remove a member (or leave the workspace) | public |
| `members_list` | `GET /workspaces/:workspace_id/members` | List workspace members | public |
| `members_update` | `PATCH /workspaces/:workspace_id/members/:id` | Change a member's role or site access | `members.manage` |
| `ownership_transfers_create` | `POST /workspaces/:workspace_id/ownership_transfer` | Transfer workspace ownership to another member (owner only, you become an admin) | public |
### Notes
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `notes_create` | `POST /sites/:site_id/notes` | Add a note to a site (use source "deploy" for release webhooks) | `content.write` |
| `notes_delete` | `DELETE /sites/:site_id/notes/:id` | Delete a note | `content.write` |
| `notes_list` | `GET /sites/:site_id/notes` | List notes for a site (including workspace-wide notes) | `analytics.read` |
| `notes_get` | `GET /sites/:site_id/notes/:id` | Get a note | `analytics.read` |
| `notes_update` | `PATCH /sites/:site_id/notes/:id` | Edit a note | `content.write` |
| `workspace_notes_create` | `POST /workspaces/:workspace_id/notes` | Add a workspace-wide note (shown on every site) | `content.write` |
| `workspace_notes_delete` | `DELETE /workspaces/:workspace_id/notes/:id` | Delete a workspace note | `content.write` |
| `workspace_notes_list` | `GET /workspaces/:workspace_id/notes` | List notes across a workspace | `analytics.read` |
| `workspace_notes_update` | `PATCH /workspaces/:workspace_id/notes/:id` | Edit a workspace note | `content.write` |
### Notification channels
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `notification_channels_create` | `POST /workspaces/:workspace_id/channels` | Add a notification channel | `content.write` |
| `notification_channels_delete` | `DELETE /channels/:id` | Delete a notification channel | `content.write` |
| `notification_channels_list` | `GET /workspaces/:workspace_id/channels` | List notification channels | `analytics.read` |
| `notification_channels_send_test` | `POST /channels/:id/send_test` | Send a test message through a channel | `content.write` |
| `notification_channels_get` | `GET /channels/:id` | Get a notification channel | `analytics.read` |
| `notification_channels_update` | `PATCH /channels/:id` | Update a notification channel | `content.write` |
| `push_subscriptions_create` | `POST /push_subscription` | Register a browser for push notifications | public |
| `push_subscriptions_delete` | `DELETE /push_subscription` | Remove a browser push registration | public |
### Performance
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `performance_report` | `GET /sites/:site_id/performance` | Web Vitals: p75 scorecard, daily trend and breakdowns by page, device, browser and country | `analytics.read` |
### Plans
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `plans_list` | `GET /plans` | List plans, prices and limits | public |
### Roles
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `roles_create` | `POST /workspaces/:workspace_id/roles` | Create a custom role | `members.manage` |
| `roles_delete` | `DELETE /workspaces/:workspace_id/roles/:id` | Delete a custom role (must be unused) | `members.manage` |
| `roles_list` | `GET /workspaces/:workspace_id/roles` | List custom roles | public |
| `roles_update` | `PATCH /workspaces/:workspace_id/roles/:id` | Update a custom role | `members.manage` |
### SSO
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `sso_activate` | `POST /workspaces/:workspace_id/sso/activate` | Activate a tested SSO configuration | `workspace.manage` |
| `sso_deactivate` | `POST /workspaces/:workspace_id/sso/deactivate` | Turn SSO off (back to draft) | `workspace.manage` |
| `sso_get` | `GET /workspaces/:workspace_id/sso` | Get SSO settings | `workspace.manage` |
| `sso_update` | `PATCH /workspaces/:workspace_id/sso` | Create or update SSO settings | `workspace.manage` |
### Search
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `search_report` | `GET /sites/:site_id/search` | Search report: clicks, impressions, CTR, position, top queries/pages, landing pages and opportunities | `analytics.read` |
| `search_connect` | `POST /sites/:site_id/search/connections` | Connect a Search Console property or Bing site | `sites.manage` |
| `search_disconnect` | `DELETE /sites/:site_id/search/connections/:provider` | Disconnect Search Console or Bing and delete its data | `sites.manage` |
| `search_properties` | `POST /sites/:site_id/search/properties` | List properties you can connect (Search Console needs a Google grant from the browser) | `sites.manage` |
| `search_sync` | `POST /sites/:site_id/search/sync` | Import search data now | `sites.manage` |
### Segments
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `segments_create` | `POST /sites/:site_id/segments` | Save filters as a segment | `content.write` |
| `segments_delete` | `DELETE /sites/:site_id/segments/:id` | Delete a segment | `content.write` |
| `segments_list` | `GET /sites/:site_id/segments` | List segments you can use on a site | `analytics.read` |
| `segments_preview` | `POST /sites/:site_id/segments/preview` | Describe filters in plain English and count the visitors they matched in the last 30 days | `analytics.read` |
| `segments_get` | `GET /sites/:site_id/segments/:id` | Get a segment | `analytics.read` |
| `segments_update` | `PATCH /sites/:site_id/segments/:id` | Rename a segment or change its filters or sharing | `content.write` |
### Sharing
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `shared_links_create` | `POST /sites/:site_id/shared_links` | Create a share link | `sites.manage` |
| `shared_links_delete` | `DELETE /sites/:site_id/shared_links/:id` | Revoke a share link | `sites.manage` |
| `shared_links_list` | `GET /sites/:site_id/shared_links` | List share links | `sites.manage` |
| `shared_links_update` | `PATCH /sites/:site_id/shared_links/:id` | Change a share link | `sites.manage` |
| `shares_breakdown` | `GET /share/:token/breakdown/:dimension` | Top values of a shared dimension | public |
| `shares_overview` | `GET /share/:token` | Shared dashboard overview for a share token | public |
### Sites
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `sites_reset_data` | `POST /sites/:site_id/data_reset` | Delete all events and visits in a date range (runs in the background, cannot be undone) | `sites.manage` |
| `sites_filter_stats` | `GET /sites/:site_id/filter_stats` | Filtered traffic summary: bots, traffic rules or PII redactions by reason and country (counts only) | `analytics.read` |
| `sites_access_list` | `GET /sites/:site_id/access` | List members and whether they can see this site | `members.manage` |
| `sites_access_update` | `PATCH /sites/:site_id/access` | Grant or remove one member's access to this site | `members.manage` |
| `sites_favorite` | `POST /sites/:site_id/favorite` | Star a site (pinned first on All sites) | `analytics.read` |
| `sites_unfavorite` | `DELETE /sites/:site_id/favorite` | Unstar a site | `analytics.read` |
| `sites_setup_get` | `GET /sites/:site_id/setup` | Installation status and snippet for a site | `analytics.read` |
| `site_transfers_accept` | `POST /transfers/:token/accept` | Accept a site transfer into one of your workspaces | public |
| `sites_transfer_start` | `POST /sites/:site_id/transfer` | Start transferring a site to another workspace (emails the recipient) | `sites.manage` |
| `sites_transfer_cancel` | `DELETE /sites/:site_id/transfer` | Cancel a pending site transfer | `sites.manage` |
| `site_transfers_get` | `GET /transfers/:token` | Get a pending transfer from its emailed token | public |
| `sites_create` | `POST /workspaces/:workspace_id/sites` | Add a site | `sites.manage` |
| `sites_delete` | `DELETE /sites/:id` | Delete a site (purged after 7 days) | `sites.manage` |
| `sites_list` | `GET /workspaces/:workspace_id/sites` | List sites in a workspace | `analytics.read` |
| `sites_get` | `GET /sites/:id` | Get a site and all its settings | `analytics.read` |
| `sites_update` | `PATCH /sites/:id` | Update site settings | `sites.manage` |
### Status pages
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `status_page_posts_create` | `POST /status_pages/:status_page_id/posts` | Post an incident update (emails subscribers) | `uptime.manage` |
| `status_page_posts_delete` | `DELETE /status_pages/:status_page_id/posts/:id` | Delete a status page post | `uptime.manage` |
| `status_page_posts_list` | `GET /status_pages/:status_page_id/posts` | List posts on a status page | `analytics.read` |
| `status_page_posts_update` | `PATCH /status_pages/:status_page_id/posts/:id` | Edit a status page post | `uptime.manage` |
| `status_page_subscribers_delete` | `DELETE /status_pages/:status_page_id/subscribers/:id` | Remove a subscriber | `uptime.manage` |
| `status_page_subscribers_list` | `GET /status_pages/:status_page_id/subscribers` | List subscribers of a status page | `uptime.manage` |
| `status_pages_create` | `POST /workspaces/:workspace_id/status_pages` | Create a status page | `uptime.manage` |
| `status_pages_delete` | `DELETE /status_pages/:id` | Delete a status page | `uptime.manage` |
| `status_pages_list` | `GET /workspaces/:workspace_id/status_pages` | List status pages | `analytics.read` |
| `status_pages_get` | `GET /status_pages/:id` | Get a status page | `analytics.read` |
| `status_pages_update` | `PATCH /status_pages/:id` | Change a status page | `uptime.manage` |
### Tracking
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `tracking_ingest_key_rotate` | `POST /sites/:site_id/tracking/ingest_key` | Create or rotate the server ingest key (shown once) | `sites.manage` |
| `tracking_ingest_key_revoke` | `DELETE /sites/:site_id/tracking/ingest_key` | Revoke the server ingest key | `sites.manage` |
| `tracking_verify` | `POST /sites/:site_id/tracking/verify` | Check the tracker is installed on the site (script tag, site id, CSP and referrer policy) | `sites.manage` |
| `tracking_snippet` | `GET /sites/:site_id/tracking/snippet` | Build the tracking snippet for chosen options | `analytics.read` |
### Traffic rules
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `traffic_rules_create` | `POST /sites/:site_id/traffic_rules` | Add a traffic rule | `sites.manage` |
| `traffic_rules_delete` | `DELETE /sites/:site_id/traffic_rules/:id` | Delete a traffic rule | `sites.manage` |
| `traffic_rules_list` | `GET /sites/:site_id/traffic_rules` | List traffic rules | `analytics.read` |
| `traffic_rules_test` | `POST /sites/:site_id/traffic_rules/test` | Test whether a hit would be counted with the site's current rules | `analytics.read` |
| `traffic_rules_update` | `PATCH /sites/:site_id/traffic_rules/:id` | Change a traffic rule | `sites.manage` |
### Uptime
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `uptime_checks_create` | `POST /sites/:site_id/uptime` | Add an uptime check for a site | `uptime.manage` |
| `uptime_checks_delete` | `DELETE /uptime/checks/:id` | Delete an uptime check and its history | `uptime.manage` |
| `uptime_checks_list` | `GET /sites/:site_id/uptime` | List a site's uptime checks | `analytics.read` |
| `uptime_checks_pause` | `POST /uptime/checks/:id/pause` | Pause an uptime check | `uptime.manage` |
| `uptime_checks_resume` | `POST /uptime/checks/:id/resume` | Resume a paused uptime check | `uptime.manage` |
| `uptime_checks_get` | `GET /uptime/checks/:id` | Get an uptime check: uptime 24h/7d/30d, response times and incidents | `analytics.read` |
| `uptime_checks_update` | `PATCH /uptime/checks/:id` | Change an uptime check | `uptime.manage` |
| `workspace_uptime_checks_create` | `POST /workspaces/:workspace_id/uptime` | Add a workspace uptime check (not tied to a site) | `uptime.manage` |
| `workspace_uptime_checks_list` | `GET /workspaces/:workspace_id/uptime` | List all uptime checks in a workspace | `analytics.read` |
### Warehouse sync
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `warehouse_destinations_create` | `POST /workspaces/:workspace_id/warehouses` | Add a warehouse destination | `workspace.manage` |
| `warehouse_destinations_delete` | `DELETE /warehouses/:id` | Delete a warehouse destination | `workspace.manage` |
| `warehouse_destinations_list` | `GET /workspaces/:workspace_id/warehouses` | List warehouse destinations | `workspace.manage` |
| `warehouse_destinations_get` | `GET /warehouses/:id` | Get a warehouse destination (no secrets) | `workspace.manage` |
| `warehouse_destinations_sync` | `POST /warehouses/:id/sync` | Queue a sync of one day now | `workspace.manage` |
| `warehouse_destinations_update` | `PATCH /warehouses/:id` | Update a warehouse destination (blank secrets are kept) | `workspace.manage` |
### Webhooks
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `webhook_deliveries_list` | `GET /workspaces/:workspace_id/webhooks/:webhook_id/deliveries` | List deliveries for a webhook | `workspace.manage` |
| `webhook_deliveries_redeliver` | `POST /workspaces/:workspace_id/webhooks/:webhook_id/deliveries/:id/redeliver` | Send a delivery again | `workspace.manage` |
| `webhooks_create` | `POST /workspaces/:workspace_id/webhooks` | Add a webhook endpoint | `workspace.manage` |
| `webhooks_delete` | `DELETE /workspaces/:workspace_id/webhooks/:id` | Delete a webhook | `workspace.manage` |
| `webhooks_list` | `GET /workspaces/:workspace_id/webhooks` | List webhooks | `workspace.manage` |
| `webhooks_get` | `GET /workspaces/:workspace_id/webhooks/:id` | Get a webhook | `workspace.manage` |
| `webhooks_test` | `POST /workspaces/:workspace_id/webhooks/:id/test` | Send a test delivery | `workspace.manage` |
| `webhooks_update` | `PATCH /workspaces/:workspace_id/webhooks/:id` | Update a webhook (events, URL, enabled, rotate secret) | `workspace.manage` |
### Website
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `changelog_list` | `GET /changelog` | List changelog entries | public |
| `changelog_get` | `GET /changelog/:id` | Get a changelog entry | public |
| `pricing_get` | `GET /pricing` | Get plans, prices and plan limits | public |
| `status_get` | `GET /status` | Get the current system status | public |
| `tools_consent_gap` | `GET /tools/consent-gap` | Estimate traffic missed by consent-based analytics | public |
| `tools_header_check` | `GET /tools/header-checker` | Check a page’s Referrer-Policy and CSP for analytics | public |
| `tools_privacy_policy` | `GET /tools/privacy-policy-generator` | Draft a privacy-policy paragraph for Privatus Analytics | public |
| `tools_qr_code` | `GET /tools/qr-code` | Generate a QR code as SVG | public |
| `tools_tracker_scan` | `GET /tools/tracker-scanner` | List cookies and known trackers on a page | public |
| `tools_utm_builder` | `GET /tools/utm-builder` | Build a campaign URL with UTM parameters | public |
### Workspaces
| Tool | Endpoint | Summary | Permission |
|---|---|---|---|
| `white_label_get` | `GET /workspaces/:workspace_id/white_label` | Get the white label brand | `workspace.manage` |
| `white_label_update` | `PATCH /workspaces/:workspace_id/white_label` | Set the white label brand for shared dashboards and email reports (Business) | `workspace.manage` |
| `workspace_security_get` | `GET /workspaces/:workspace_id/security` | Get workspace security settings | `workspace.manage` |
| `workspace_security_update` | `PATCH /workspaces/:workspace_id/security` | Update workspace security settings (2FA, login methods, session lifetime, IP allowlist, support access) | `workspace.manage` |
| `workspaces_delete` | `DELETE /workspaces/:id` | Delete a workspace and all its sites (owner only, cancels any subscription) | `workspace.manage` |
| `workspaces_list` | `GET /workspaces` | List your workspaces | public |
| `workspaces_get` | `GET /workspaces/:id` | Get a workspace | public |
| `workspaces_update` | `PATCH /workspaces/:id` | Update workspace settings | `workspace.manage` |
---
Source: https://privatusanalytics.com/docs/mcp/clients
# Connect AI clients to the MCP server
> Connect Claude Desktop, Claude Code, ChatGPT, Gemini CLI, Cursor and VS Code to the Privatus Analytics MCP server with OAuth or an API token, step by step.
Replace `pat_…` with an [API token](/docs/api/authentication). Prefer a
token with only the permissions the agent needs.
## Claude Desktop
**With OAuth:** Settings → Connectors → **Add custom connector**. Name it
"Privatus Analytics" and enter `https://privatusanalytics.com/mcp`. Claude opens a
browser window to sign in and approve access.
**With a token**, in `claude_desktop_config.json` (Settings → Developer →
Edit config), using the `mcp-remote` bridge:
```json
{
"mcpServers": {
"privatus": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://privatusanalytics.com/mcp", "--header", "Authorization:${PRIVATUS_AUTH}"],
"env": { "PRIVATUS_AUTH": "Bearer pat_…" }
}
}
}
```
Restart Claude Desktop.
## Claude Code
```sh
claude mcp add --transport http privatus https://privatusanalytics.com/mcp \
--header "Authorization: Bearer pat_…"
```
Add `--scope user` to use it in every project, or `--scope project` to
share it through `.mcp.json` (then reference an environment variable
instead of committing the token). Check it with `/mcp` inside Claude Code.
To sign in with OAuth instead of a token, leave out `--header` and
authenticate from `/mcp` inside Claude Code.
## ChatGPT
ChatGPT connects to remote MCP servers as custom connectors. Turn on
developer mode in ChatGPT's settings, create a connector, enter
`https://privatusanalytics.com/mcp` and choose OAuth as the authentication. ChatGPT
opens a window to sign in to Privatus Analytics and approve access.
## Gemini CLI
```sh
gemini mcp add --transport http privatus https://privatusanalytics.com/mcp
```
Then run `/mcp auth privatus` inside Gemini CLI to sign in with OAuth.
## Cursor
`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
```json
{
"mcpServers": {
"privatus": {
"url": "https://privatusanalytics.com/mcp",
"headers": { "Authorization": "Bearer pat_…" }
}
}
}
```
Then enable it under Cursor Settings → MCP.
## VS Code
`.vscode/mcp.json`, prompting for the token so it isn't stored in the
file:
```json
{
"inputs": [
{ "type": "promptString", "id": "privatus-token", "description": "Privatus Analytics API token", "password": true }
],
"servers": {
"privatus": {
"type": "http",
"url": "https://privatusanalytics.com/mcp",
"headers": { "Authorization": "Bearer ${input:privatus-token}" }
}
}
}
```
Start the server from the file's CodeLens or the **MCP: List Servers**
command, and use it in Copilot Chat's agent mode.
## Other clients
Any client that supports Streamable HTTP can connect to
`https://privatusanalytics.com/mcp` with an `Authorization` header. Clients that only
support stdio can use `mcp-remote` as shown for Claude Desktop.
---
Source: https://privatusanalytics.com/docs/mcp/examples
# MCP prompts and JSON-RPC examples
> Example prompts that work well with the Privatus Analytics MCP server, the tools an agent picks for them, and raw JSON-RPC calls for testing a token.
## Prompts
- "Which pages on example.com got the most visitors from AI assistants
last month, and how did that change from the month before?"
- "Compare signup conversion rate by channel for the last 90 days."
- "Create a goal for visits to /thank-you on example.com." (needs
`content.write`)
- "Add a note on today's date: 'Launched new pricing page'."
- "Are any of my uptime checks down right now?"
- "How do I track outbound links with Privatus Analytics?" (uses `docs_search`)
The agent picks the tools, for example `stats_breakdown` with
`dimension=page`, `period=last_month`, `compare=previous_period` and
`filters=[["channel","is","ai_assistants"]]`.
## Raw JSON-RPC
Useful for checking a token or building your own client.
List tools:
```sh
curl https://privatusanalytics.com/mcp \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
Call a tool:
```sh
curl https://privatusanalytics.com/mcp \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {
"name": "stats_aggregate",
"arguments": { "site_id": "pa_7Q2K9XH3AB", "period": "7d", "compare": "previous_period" }
}
}'
```
The result's `content[0].text` is the same JSON the API returns
(`{"data": …}`), also provided as `structuredContent`. Errors come back
with `isError: true` and the API's error body.
## Good practice
- Use a dedicated token per agent, with the smallest set of permissions
and sites, and an expiry date.
- Write tools (create, update, delete) show up only when the token has the
permission. Keep agents on `analytics.read` unless they need more.
- Everything an agent changes is in the [audit log](/docs/teams/audit-log)
under the token's member.
---
Source: https://privatusanalytics.com/docs/billing
# Billing and account
> How Privatus Analytics billing works: pricing by events a month, one allowance per workspace, a Free plan with no card, and no surprise charges, ever.
- **Pricing is by events a month.** An event is a pageview or a custom
event. Everything else is free: API calls, MCP, Web Vitals, engagement
pings, click maps, uptime checks, imports and bots.
- **One allowance per workspace**, shared by all its sites and members.
- **The Free plan needs no card**: 10,000 events a month (20,000 with the
optional badge), 10 sites, 3 members, 6 months of history. Above that,
Pro starts at $9 a month for up to 250,000 events.
- **No surprise charges, ever.** When you reach your monthly limit we
pause collection and email you. We never charge you more unless you
choose to upgrade, or you turned on automatic upgrades yourself. See
[Monthly limit](/docs/billing/overage).
## In this section
- [Plans](/docs/billing/plans): prices and limits.
- [What counts as an event](/docs/billing/usage), the usage meter and the
badge bonus.
- [Monthly limit](/docs/billing/overage): the 80% and 100% emails and
what pauses at the limit.
- [Invoices, tax and payment](/docs/billing/invoices).
- [Cancelling and your data](/docs/billing/cancellation).
Billing is managed by owners and members with the `billing.manage`
permission (the **Billing** role exists for finance teams) under
**Workspace settings → Billing**.
---
Source: https://privatusanalytics.com/docs/billing/plans
# Plans and pricing
> Compare Privatus Analytics Free, Pro, Business and Enterprise plans: pricing by monthly events, every plan limit, yearly billing, plan changes and discounts.
## Prices
Pro and Business are priced by your monthly event allowance. Yearly
billing costs 10× the monthly price (two months free). Prices are in US
dollars and include VAT or sales tax. The price you see is the price you
pay. See [Invoices, tax and payment](/docs/billing/invoices).
| Events / month | Pro (monthly) | Business (monthly) |
|---|---|---|
| 250,000 | $9 | $49 |
| 500,000 | $14 | $49 |
| 1,000,000 | $19 | $49 |
| 2,000,000 | $29 | $58 |
| 5,000,000 | $59 | $118 |
| 10,000,000 | $99 | $198 |
| 20,000,000 | $169 | $338 |
| 50,000,000 | $349 | $698 |
| 100,000,000 | Business only | $1,190 |
Business is twice the Pro price, with a $49 minimum. Above 100 million
events, or for custom terms, talk to us about **Enterprise**.
## Limits
These tables are generated from the limits the app enforces.
| Limit | Free | Pro | Business | Enterprise |
|---|---|---|---|---|
| Sites | 10 | Unlimited | Unlimited | Unlimited |
| Members | sites, member_seats, retention_months, goals_per_site, funnels_per_site, funnel_steps, property_keys, email_reports, uptime_checks, uptime_interval_seconds, ai_questions, api_requests_per_hour, raw_export, warehouse_export, sso, custom_roles, audit_days, white_label, alert_channels, vitals_sample_max, sso_links, expiring_links, require_2fa | sites, member_seats, retention_months, goals_per_site, funnels_per_site, funnel_steps, property_keys, email_reports, uptime_checks, uptime_interval_seconds, ai_questions, api_requests_per_hour, raw_export, warehouse_export, sso, custom_roles, audit_days, white_label, alert_channels, vitals_sample_max, sso_links, expiring_links, require_2fa | sites, member_seats, retention_months, goals_per_site, funnels_per_site, funnel_steps, property_keys, email_reports, uptime_checks, uptime_interval_seconds, ai_questions, api_requests_per_hour, raw_export, warehouse_export, sso, custom_roles, audit_days, white_label, alert_channels, vitals_sample_max, sso_links, expiring_links, require_2fa | sites, member_seats, retention_months, goals_per_site, funnels_per_site, funnel_steps, property_keys, email_reports, uptime_checks, uptime_interval_seconds, ai_questions, api_requests_per_hour, raw_export, warehouse_export, sso, custom_roles, audit_days, white_label, alert_channels, vitals_sample_max, sso_links, expiring_links, require_2fa |
| Data retention (months) | 6 | Unlimited while subscribed | Unlimited while subscribed | Unlimited while subscribed |
| Goals per site | 10 | Unlimited | Unlimited | Unlimited |
| Funnels per site | 3 | Unlimited | Unlimited | Unlimited |
| Steps per funnel | 5 | 10 | 20 | 20 |
| Event property keys per site | 10 | Unlimited | Unlimited | Unlimited |
| Email reports | 3 | Unlimited | Unlimited | Unlimited |
| Uptime checks | 3 | 20 | 100 | Unlimited |
| Fastest uptime interval (seconds) | 300 | 60 | 30 | 30 |
| AI assistant questions / month | - | 20 | 100 | Unlimited |
| API requests / hour | 1,000 | 5,000 | 20,000 | 100,000 |
| Web Vitals max sample (%) | 10 | 100 | 100 | 100 |
| Raw event export | - | ✓ | ✓ | ✓ |
| Warehouse export | - | - | ✓ | ✓ |
| SSO and SCIM | - | - | ✓ | ✓ |
| Custom roles | - | - | ✓ | ✓ |
| Audit log (days) | - | 30 | 365 | Unlimited |
| White label | - | - | ✓ | ✓ |
| Expiring share links | - | ✓ | ✓ | ✓ |
| SSO-restricted share links | - | - | ✓ | ✓ |
| Alert channels | email | email, slack, teams, discord, webhook, push | email, slack, teams, discord, webhook, push, pagerduty, opsgenie | email, slack, teams, discord, webhook, push, pagerduty, opsgenie |
Every plan includes the core dashboard, filters, segments, notes,
revenue, journeys, engagement, real time, imports, Search Console, the
server-side API and the [JSON API](/docs/api) and [MCP server](/docs/mcp).
## Changing plans
**Workspace settings → Billing → Change plan** shows the new price and the
prorated amount before you confirm. Upgrades apply immediately.
Downgrades warn you first if you're over the new plan's limits (for
example more goals per site than the Free plan allows). Nothing is deleted,
but you can't add more until you're under the limit.
## Discounts
- Nonprofits, education and open-source projects: 50% off Pro and
Business.
- Open-source project sites and docs: free Pro up to 1M events a month.
- Agencies: wholesale billing for client workspaces.
Ask from **Workspace settings → Billing → Request a discount**.
---
Source: https://privatusanalytics.com/docs/billing/usage
# What counts as a billable event
> Which hits count toward your Privatus Analytics event allowance, what is free (API, Web Vitals, bots, uptime), the usage meter, and the Free plan badge bonus.
## Counted
| Hit | Counts |
|---|---|
| Pageview (including SPA route changes) | 1 event |
| Custom event (`track()`, HTML attributes, `auto` module, server-side) | 1 event |
## Not counted
- Engagement pings (time on page, scroll depth)
- Web Vitals
- Click-map hits
- Bots and anything else filtered out (traffic rules, DNT/GPC, opted-out
visitors, foreign hostnames)
- API and MCP requests
- Uptime checks
- Imported data
## Estimating
Your GA4 "Views" plus "Event count" for custom events (not automatic
events like `scroll` or `user_engagement`) over a month is a good
estimate. Privatus Analytics often counts **more** pageviews than GA4, because it
doesn't depend on consent (see [why numbers differ](/docs/metrics/ga4-differences)).
## The usage meter
**Workspace settings → Billing** shows this month's events, a forecast for
the month, and a breakdown per site. Usage resets on the 1st of each month
(UTC). You're emailed at 80% and 100% of your allowance. At 100%,
collection pauses until the reset or an upgrade, and nothing is charged
(see [Monthly limit](/docs/billing/overage)).
## Badge bonus
On the Free plan, show our badge on one of your sites and get **10,000
extra events a month** (20,000 in total):
```html
<a href="https://privatusanalytics.com/?ref=badge"><img src="https://privatusanalytics.com/badge.svg" alt="Privacy-first analytics by Privatus Analytics" width="150" height="32"></a>
```
Turn it on in **Workspace settings → Billing**. We check your homepage for
the badge and re-check it regularly. If it disappears, we warn you, and
remove the bonus if it's still missing 14 days later.
---
Source: https://privatusanalytics.com/docs/billing/overage
# Monthly limit and no surprise charges
> What happens at your monthly event limit: emails at 80% and 100%, collection pauses until the reset or an upgrade, and nothing is charged automatically.
**No surprise charges, ever.** When you reach your monthly limit we pause
collection and email you. We never charge you more unless you choose to
upgrade, or you turned on automatic upgrades yourself.
## How the limit works
The limit is your plan's monthly allowance (plus the badge bonus on the
Free plan). It is the same on every plan: Free, Pro, Business and
Enterprise.
1. At **80%** of the allowance, the owners and billing contacts get an
email with the reset date and an **Upgrade your plan** button.
2. At **100%**, collection **pauses at once** for every site in the
workspace. New pageviews and custom events are not recorded, and you get
a second email saying so. The dashboard shows a banner and the billing
page shows **Collection paused: limit reached**.
3. Collection **resumes on its own** when the count resets on the 1st of
the next month (UTC), or **right away** when the allowance goes up: an
upgrade, a verified badge bonus or a comp.
Each email goes out once a month. If you upgrade and later reach the new
allowance in the same month, you are told again.
While collection is paused:
- Your sites keep working normally. The tracker gets its usual response,
so visitors never see an error.
- Your existing data, dashboards, reports and the API are untouched.
- What never counts keeps working: Web Vitals, engagement pings for visits
already recorded, uptime checks, imports and API calls. Bots are still
counted in the bot totals.
- Server-side events get the status `dropped` with the reason
`limit_reached` (see [Server-side events](/docs/server-side)).
## Automatic upgrades (opt in)
In **Workspace settings → Billing** you can turn on **Upgrade
automatically at the limit**. It is **off by default**. With it on, and an
active subscription, reaching the limit moves you to the next tier and
charges the prorated difference instead of pausing collection. We email you
when it happens. You can turn it off at any time. If no bigger tier fits
(Enterprise volume), collection pauses as usual. Enterprise plans are never
changed automatically.
- With it on, the 80% email tells you which tier you would move to and
that the prorated difference would be charged, so you can turn it off
first if you prefer to pause.
- If you turn it on **while collection is already paused at the limit**,
the upgrade happens as soon as you save, and collection resumes. The
billing page tells you the tier before you save.
- If the upgrade can't go through (for example the payment is declined),
nothing is charged, collection pauses and the email tells you why.
## Why a hard limit
A limit you can see is easier to plan for than a bill you can't. You
always know the most a month can cost: the price of the plan you picked.
---
Source: https://privatusanalytics.com/docs/billing/invoices
# Invoices, tax and payment methods
> Payment methods, currencies, invoices, VAT numbers and failed payments for Privatus Analytics, with Paddle as merchant of record handling sales tax worldwide.
Payments are processed by **Paddle**, our merchant of record. Paddle
handles sales tax and VAT worldwide and issues the invoices.
**Prices include VAT or sales tax. The price you see is the price you pay.**
Paddle works out the tax for your country from that price, so a $9 plan
costs $9 at checkout wherever you are.
- **Payment methods:** cards and the other methods Paddle offers in your
country (such as PayPal). Enterprise contracts can be paid by invoice.
- **Currencies:** USD, EUR and GBP.
- **Tax id / VAT number:** enter it in the Paddle checkout when you
subscribe, and add it under Workspace settings → Billing. Business
customers get a proper tax invoice from Paddle with their company
details and tax id. Where a reverse charge applies, Paddle handles it
and the invoice says so.
- **Invoices:** every payment has a PDF invoice in Workspace settings →
Billing. The invoice shows the tax breakdown: the net amount, the tax
rate and the tax included in the price. Billing emails can go to one or more addresses (for example your
accounts team) instead of the owner.
- **Failed payments:** Paddle retries and emails you. Update the payment
method from the billing page. Your data keeps being collected meanwhile.
- **Refunds:** you can get a full refund of any payment, renewals included,
if you ask within 30 days of that payment. Email
hello@privatusanalytics.com or ask Paddle at [paddle.net](https://paddle.net).
The money goes back to the payment method you used, and the refunded
period ends, so the workspace moves to the Free plan. See the
[refund policy](/legal/terms#refunds).
- **Billing questions:** contact support from the help menu.
---
Source: https://privatusanalytics.com/docs/billing/cancellation
# Canceling a plan and your data
> How canceling a paid Privatus Analytics plan works, what happens to your data on the Free plan, how to delete your workspace, and what to export before you go.
## Cancelling a paid plan
**Workspace settings → Billing → Cancel.** Cancelling takes effect at the
**end of the paid period**: you keep your plan until then. A short
optional survey asks why. You can also **pause** instead, or undo the
cancellation any time before the period ends.
Cancelling doesn't refund the current period. If you want your money
back, ask within 30 days of the payment: see the
[refund policy](/legal/terms#refunds).
When the period ends, the workspace moves to the **Free plan**:
- collection continues within Free limits,
- data older than the Free plan's 6 months of retention is deleted by the
regular retention job,
- features beyond Free (more goals and funnels, raw exports, SSO…) stop
working. Nothing you created is deleted, but you can't add more until
you're within the Free limits. Upgrading again restores everything.
## Deleting your data
To leave completely, **delete the workspace** (Workspace settings →
General → Delete workspace). It's soft-deleted for 7 days, then permanently
deleted. To undo a deletion, contact support within those 7 days and we'll
restore it. Backups expire within 30 days after that.
You can also delete individual sites, or reset a site's data for a date
range, at any time.
## Before you go
[Export](/docs/reports/exports) anything you want to keep: aggregated
tables, raw events (paid plans) or a dashboard bundle.
## Inactive free accounts
Free workspaces with no sign-ins and no data for 12 months are deleted,
with warnings by email 30 and 7 days before.
---
Source: https://privatusanalytics.com/docs/billing/affiliates
# Affiliate program
> How the Privatus Analytics affiliate program works, from your referral link to the 30-day hold, Wise payouts and account credit, with cookieless attribution.
Earn **25% of every payment** from the customers you refer, for **24
months** from each customer's first payment.
## Apply
**Account settings → Affiliate program.** Tell us your website or
channel and how you'll promote Privatus Analytics, pick a referral code
(or let us suggest one) and choose how you want to be paid. We review
applications within two business days and email you the result. If we
can't approve it, the email says why and you can apply again.
## Share your link
Once approved, your page shows a link like
`https://privatusanalytics.com/r/your-code`. It opens the sign-up page.
People can also enter your code in "How did you hear about us?" when they
create their first workspace.
## Signup box
A signup form for your own site. Visitors get a Privatus Analytics
tracking code for their site without leaving your page, and each new
account is credited to you like a link referral.
**Account settings → Affiliate program → Signup box** has a live preview
and your code. Pick a theme (match the visitor's device, light or dark),
then paste one of these where the box should appear.
The script fits the box to its content, supports prefill and tells your
page when someone signs up:
```html
<div data-privatus-signup="your-code" data-theme="auto"></div>
<script async src="https://privatusanalytics.com/js/signup-box.js"></script>
```
A plain iframe works on sites that don't allow scripts. It has a fixed
height and no prefill:
```html
<iframe src="https://privatusanalytics.com/embed/signup/your-code?theme=auto"
title="Privatus Analytics signup" allow="clipboard-write"
style="width:100%;max-width:480px;height:640px;border:0"></iframe>
```
### What the visitor does
1. They enter their first name, email and the domain of their site, accept
the Terms and the Privacy Policy, and choose whether they want product
emails.
2. The box shows their tracking code with a copy button and a **Check
installation** button. Pageviews are counted from this moment.
3. We email them a one-time link to their dashboard. Opening it creates
their account (or signs them in if they already have one) and puts the
site in it.
A signup that nobody opens the link for is removed after 7 days, with
everything it collected. Until then it never stops someone else from
adding the same domain to their own account.
### Prefill for signed-in visitors
If your visitors are signed in on your site, add what you already know to
the element. They can still change every field, and they always tick the
terms themselves.
| Attribute | Fills in |
|---|---|
| `data-first-name` | First name |
| `data-email` | Email address |
| `data-domain` | The domain of their site, like `example.com` |
The script hands these values to the box inside the visitor's browser.
They are never put in a URL, and we store nothing until the visitor
submits the form.
### React on your page
The script fires these events on the element, and they bubble:
| Event | Fires when |
|---|---|
| `privatus:signup:submitted` | The form was submitted and the tracking code is shown |
| `privatus:signup:installed` | The tracking code was found on the visitor's site |
| `privatus:signup:receiving` | The first pageview arrived |
```js
document.addEventListener("privatus:signup:submitted", () => {
// show your next step
})
```
The events carry no name, email, domain or site id.
## What counts
- 25% of each **net payment**: after discounts, excluding tax.
- Pro and Business payments from a workspace created by someone who signed
up through your link or your signup box, or entered your code, for 24
months from that workspace's first payment.
- A signup box credits you for **new accounts**. Someone who already had a
Privatus Analytics account and uses your box gets their site, but is not
a referral.
- Refunds and chargebacks are taken back from the commission. A reversed
chargeback restores it.
- Self-referrals don't count. Sign-ups from your own email domain are
reviewed before they earn (shared webmail domains like gmail.com are
fine).
## Getting paid
Each commission is **on hold for 30 days**, then becomes **payable**.
- **Wise:** once you have **$50 or more** payable we send it to the Wise
account email you gave us (payouts go out monthly) and email you the
transfer reference.
- **Account credit:** payable commissions come off the **next renewal of
your own subscription** automatically, with no minimum. We add as much as
the renewal can absorb and the rest waits for the following one. A
subscription can hold only one discount, so a workspace in a
[discount program](/docs/billing/plans#discounts) can't take credit: choose Wise
or another workspace. Credit also waits while the subscription bills in
a different currency than your commissions. Your affiliate page tells
you when credit is waiting and why. Switch to Wise at any time.
Your page and the API show signups, paying customers, what's on hold,
payable and paid, and every commission and payout. The Signup box page
shows the box's own numbers: signups waiting to confirm, confirmed signups
and paying customers.
## API and MCP
- `GET /account/affiliate.json` (MCP tool `affiliate_get`): status,
referral link, stats and balances.
- `GET /account/affiliate/commissions.json` (MCP tool
`affiliate_commissions_list`): commissions, paginated, with an optional
`status` filter.
- `GET /account/affiliate/signup-box.json` (MCP tool
`affiliate_signup_box_get`): your signup box code for a `theme` (`auto`,
`light` or `dark`) and the box's numbers.
Applying and changing payout details need a signed-in browser.
## How referrals are attributed (privacy)
The program follows the same rules as the product: no tracking cookies,
no fingerprinting, no click logs.
- `/r/your-code` sets **no cookie** and **records nothing**. It only
redirects to the sign-up page with the code in the address.
- The sign-up page keeps the code in its own session cookie (the one it
already needs for the form), which ends when the browser closes. The
code is dropped when the account is created.
- We then store which affiliate referred the new account and, later, its
workspace. That's all. We never store the visitor's IP address, device
or the pages they viewed.
- You see counts (signups and paying customers) and commissions, never
who your referrals are.
The signup box follows the same rules:
- It sets **no cookie** on your site or ours, and uses no storage.
- Until the visitor opens their emailed link we keep **no account, no
email address and no name**: only the site they asked for, and a keyed
hash of the address so the right person can claim it. The first name and
the email choice travel inside the signed link.
- The visitor's IP address is used in memory for the bot check and rate
limits, and never stored.
- Your page learns that a signup happened, never who signed up.
---
Source: https://privatusanalytics.com/docs/troubleshooting
# Troubleshooting analytics tracking
> Fix common analytics problems: missing data, blocked scripts, CSP errors, double-counted pageviews, traffic showing as Direct, cross-domain and timezone issues.
| Symptom | Start here |
|---|---|
| No data at all, or it stopped | [No data](/docs/troubleshooting/no-data) |
| Fewer visitors than expected | [Ad blockers](/docs/troubleshooting/ad-blockers), [GA4 differences](/docs/metrics/ga4-differences) |
| Console errors mentioning Content Security Policy | [CSP errors](/docs/troubleshooting/csp) |
| Pageviews doubled on a single-page app | [SPA double counting](/docs/troubleshooting/spa-double-counting) |
| Almost everything is "Direct" | [Referrer policy](/docs/troubleshooting/referrer-policy) |
| Tracking broke after enabling a cache or optimization plugin | [Caching plugins](/docs/troubleshooting/caching) |
| Visits split between domains, or your own domain shows as a referrer | [Cross-domain](/docs/troubleshooting/cross-domain) |
| "Today" doesn't match, or days look shifted | [Timezones](/docs/troubleshooting/timezones) |
Still stuck? Add `data-debug="true"` to the script tag and read the
console ([Debug mode](/docs/tracker/debug)), then contact support from the
help menu with your site id and what you see.
---
Source: https://privatusanalytics.com/docs/troubleshooting/no-data
# Fix missing analytics data
> Analytics showing no data? Work through this checklist: check the script is on the page and loads, that hits are sent and accepted, and the date range is right.
Work through these in order.
## 1. Is the script on the page?
View the page source (not the developer tools' Elements tab, which shows
the DOM after scripts ran) and search for `pa.js`. Or run **Verify
installation** in Site settings → Tracking. Common causes:
- the snippet is in a template that isn't used on every page,
- a cache still serves the old HTML ([caching](/docs/troubleshooting/caching)),
- a tag manager trigger isn't published.
## 2. Does the script load?
Developer tools → **Network** → filter `pa.js`. It should return **200**.
- *Blocked* or `ERR_BLOCKED_BY_CLIENT`: an ad blocker. See
[Ad blockers](/docs/troubleshooting/ad-blockers).
- Console says *Refused to load the script*: your
[CSP](/docs/troubleshooting/csp).
## 3. Is a hit sent?
Filter the Network tab for `event`. Each page load should `POST` to
`/api/event` and get **202**. If nothing is sent, add `data-debug="true"`
and look at the console. It prints the reason:
| Console message | Fix |
|---|---|
| `not sent: missing data-site` | Add `data-site="pa_…"` |
| `not sent: localhost` | Expected on local servers. Use `data-allow-local="true"` if you really want to send |
| `not sent: domain not in data-domains` | Add the hostname to `data-domains`, or remove the attribute |
| `not sent: opted out` | This browser opted out. Run `privatus.optIn()` |
| `not sent: automated browser` | You're testing with Selenium, Playwright, Puppeteer or Cypress |
Also check `data-exclude` doesn't match the page.
## 4. Is the hit accepted?
A 202 means received, not counted. The server can still drop a hit:
- **The hostname isn't one of the site's domains.** Check Site settings →
General and add `www.` variants or other domains you use. (Subdomains of a
listed domain are accepted.)
- **Wrong site id**: the `data-site` belongs to another site.
- **Bot filtering**: headless browsers, monitoring tools and data-center
networks are filtered ([Bot rules](/docs/server-side/bots)). A VPN on a
cloud provider's network counts as a data center.
- **Traffic rules** block your IP, path or country.
- **GPC or DNT**: your browser sends Global Privacy Control and the site
honours it (the default). Brave, DuckDuckGo and some extensions turn
GPC on. Test in another browser.
- **Collection is paused**: the workspace reached its monthly event
limit ([Monthly limit](/docs/billing/overage)), or the email address
isn't verified yet. The dashboard shows a banner when the limit is
reached.
The Overview's footer counts bot-filtered and rule-blocked hits, which
tells you if hits arrive and are dropped.
## 5. Is the dashboard looking at the right range?
Check the date range, the filters and segment, and the site's timezone
([Timezones](/docs/troubleshooting/timezones)). The [Live](/docs/dashboard/live)
page shows hits within seconds, without any date range.
---
Source: https://privatusanalytics.com/docs/troubleshooting/ad-blockers
# Ad blockers and analytics
> How ad blockers and privacy browsers affect analytics, how to check whether the tracker is blocked, and what you can do about it.
Some content blockers and privacy browsers block analytics scripts by
domain or file name, including privacy-friendly ones. Typical impact is a
few percent of visitors on general sites, more on developer-heavy
audiences.
Blocked visitors aren't counted, so your numbers may be somewhat lower
than the real traffic. Treat the dashboard as a slight undercount and
compare trends over time rather than exact totals across tools.
## What you can do
- **Expect some undercounting.** The tracker loads only from
`privatusanalytics.com`, and we don't offer ways around blockers. Visitors who
block analytics are simply not counted.
- **Server-side events** for important conversions (signups, purchases)
are never blocked: see [Server-side](/docs/server-side).
- **Don't** try to hide the script (random paths, renamed files or
forwarding it through your own server). We don't support that:
respecting people who deliberately block
analytics is part of the deal. They can also
[opt out](/docs/tracker/opt-out) directly.
## Checking whether you're blocked
With a blocker, the Network tab shows `pa.js` or `/api/event` as blocked
(`ERR_BLOCKED_BY_CLIENT` in Chrome). Test in a private window without
extensions to confirm tracking works.
---
Source: https://privatusanalytics.com/docs/troubleshooting/csp
# Fix CSP errors blocking analytics
> Fix Content Security Policy errors that block the analytics tracker: add the host to script-src and connect-src, handle nonces, and find where your CSP is set.
Console errors like these mean your Content Security Policy blocks the
tracker:
- *Refused to load the script 'https://privatusanalytics.com/js/pa.js' because it
violates the following Content Security Policy directive: "script-src …"*
- *Refused to connect to 'https://privatusanalytics.com/api/event' because it
violates … "connect-src …"*
Add the host to both directives:
```http
Content-Security-Policy: script-src 'self' https://privatusanalytics.com; connect-src 'self' https://privatusanalytics.com
```
If you use the [queue stub](/docs/tracker/javascript-api#queue-stub) or
other inline scripts, give them your nonce.
Where's your CSP set? Check the response headers of your HTML page
(Network tab → the document → Response headers), and `<meta
http-equiv="Content-Security-Policy">` tags in the page. Frameworks and
hosts often set it in config: `next.config.js` headers, Helmet in Express,
`_headers` on Netlify, `vercel.json`, or a security plugin.
**Verify installation** (Site settings → Tracking) reads your CSP header
and tells you which directive is missing. Full reference:
[Content Security Policy](/docs/tracker/csp).
---
Source: https://privatusanalytics.com/docs/troubleshooting/spa-double-counting
# Fix SPA double-counted pageviews
> Fix pageviews counted twice on single-page apps: duplicate router calls, the script included twice, tag manager history triggers, and checking with debug mode.
If pageviews are roughly double the visits you'd expect, or each page shows
up twice in the Live stream, two things are sending pageviews for each
navigation.
## Common causes
1. **Both automatic SPA tracking and a manual call.** You call
`privatus.pageview()` in a router hook (`router.afterEach`,
`useEffect` on the location, `onRouteChange`) while the tracker also
follows `history.pushState`. Remove your call, or switch the tracker to
`data-spa="off"` and keep yours.
2. **The script is included twice**: in the layout and in a page, or by a
plugin and by hand. Search the rendered HTML for `pa.js`. There should
be exactly one. A framework integration plus a manual snippet is a
common pair.
3. **A tag manager re-fires the tag** on "History change" triggers. Fire
it only on page load: the tracker handles history changes itself.
4. **Zaraz SPA support** or similar tools re-injecting scripts on
navigation.
## What the tracker already prevents
It won't send two pageviews in a row for the same path (pathname, plus the
fragment in hash mode), so a router that pushes the same URL twice isn't
double counted. `privatus.pageview()` always sends, by design.
Check with `data-debug="true"`: each navigation should log exactly one
`[privatus] pageview`.
---
Source: https://privatusanalytics.com/docs/troubleshooting/referrer-policy
# Referrer policy and Direct traffic
> Why most of your traffic might show as Direct, how referrer policies on your site and on other sites affect sources, and how UTM parameters fix attribution.
Sources come from `document.referrer`, which the **previous** site's
browser policy controls.
## Your own policy
If your site sends `Referrer-Policy: no-referrer` (or `same-origin`), your
**internal** navigation has no referrer, and single-page flows can look
like new direct visits. More importantly, links *from* your other
properties (blog → app) arrive without a referrer.
The browser default, `strict-origin-when-cross-origin`, is fine: other
sites send their origin (`https://news.example/`), which is all Privatus Analytics
stores anyway (we drop referrer query strings).
**Verify installation** warns when your pages send `no-referrer` or
`same-origin`.
## Other sites' policies
Many sites and apps send no referrer at all: mobile apps, email clients,
messaging apps, some social networks, and links opened from documents.
That traffic lands in **Direct**. Use UTM parameters on links you control
(newsletters, social posts, ads) so it's attributed correctly: see
[Campaigns](/docs/features/campaigns).
## HTTPS → HTTP
Browsers never send a referrer from an `https` page to an `http` page.
Serve your site over HTTPS.
---
Source: https://privatusanalytics.com/docs/troubleshooting/caching
# Fix caching plugins breaking analytics
> Stop WP Rocket, LiteSpeed Cache, Autoptimize, Cloudflare Rocket Loader and other caching or optimization tools from breaking the analytics tracker script.
Page caches and "optimize JavaScript" features can:
- serve old HTML without the snippet: **purge the cache** after adding it,
- **combine or minify** `pa.js` into a bundle. The tracker reads its own
`<script>` tag (`document.currentScript`) for `data-site` and the other
attributes. Inside a bundle there's no such tag and it does nothing,
- **delay JavaScript until user interaction**: visitors who don't
interact are never counted, and time on page is wrong,
- rewrite or strip `data-` attributes.
## Fix
Exclude `pa.js` (and `privatusanalytics.com`) from combine, minify, defer/delay and
lazy-load features. Common settings:
| Tool | Where |
|---|---|
| WP Rocket | File Optimization → *Excluded JavaScript Files* and *Delay JavaScript execution → Excluded*: add `pa.js` |
| LiteSpeed Cache | Page Optimization → JS Settings → *JS Excludes* and *JS Delayed Excludes* |
| Autoptimize | JS Options → *Exclude scripts from Autoptimize*: add `pa.js` |
| W3 Total Cache | Minify → JS → *Never minify the following JS files* |
| Cloudflare Rocket Loader | Add `data-cfasync="false"` to the script tag |
| Perfmatters, NitroPack, SiteGround Optimizer | Their "exclude from delay/combine" lists |
With Cloudflare Rocket Loader:
```html
<script data-cfasync="false" defer src="https://privatusanalytics.com/js/pa.js" data-site="pa_YOURSITEID"></script>
```
Then purge all caches and check the page source again.
---
Source: https://privatusanalytics.com/docs/troubleshooting/cross-domain
# Cross-domain and subdomain tracking
> Track several domains or subdomains as one site or as separate sites, keep visits together without cookies, and stop your own domain showing as a referrer.
## One site, several hostnames
Add every hostname under **Site settings → General → Extra domains**.
Subdomains of a listed domain (`www.`, `shop.`, `docs.`) are accepted
automatically. Then choose:
- **Combined** (default): the visit key doesn't include the hostname, so a
visitor moving from `example.com` to `shop.example.com` (or to
`example-checkout.com`) the same day continues the **same visit**, and
links between them are internal, not referrals.
- **Separate**: the hostname is part of the visit key, so each domain has
its own visits, as if they were separate sites that share a dashboard.
Use the **Hostname** tab of the Pages panel to compare them.
No cookies or link decoration are needed to join visits across domains:
visits come from the daily visit key, which is the same on every domain of
the site.
## Your own domain shows up as a referrer
If `shop.example.com` appears as a referrer on `example.com`, it isn't one
of the site's domains. Add it, and it becomes internal.
## Separate sites instead
Create separate sites when the properties have different owners, goals or
privacy settings. Visitors moving between them then show the other site as
a referrer, as for any external site.
## Staging and preview domains
Hits from hostnames that aren't the site's domains are dropped, so
staging (`*.vercel.app`, `*.netlify.app`, `staging.example.com`) doesn't
pollute production data. If staging is a subdomain of your domain,
exclude it with `data-domains` or a hostname
[traffic rule](/docs/privacy/traffic-rules).
---
Source: https://privatusanalytics.com/docs/troubleshooting/timezones
# Timezones and daily numbers
> Why today or a day's numbers might not match what you expect: reports use the site's timezone, visits end at midnight UTC, and how the API handles dates.
## Reports use the site's timezone
Every date range ("Today", "Last 7 days", custom dates) is made of calendar
days in the **site's timezone** (Site settings → General). Events are
stored in UTC, so changing the timezone re-buckets all history instantly,
and nothing is lost.
Common confusions:
- **Your browser is in another timezone.** The dashboard doesn't use your
computer's timezone. "Today" starts at midnight where the site is set.
- **Comparing with another tool** (GA4, your server logs) that uses a
different timezone shifts every day's totals. Align them first.
- **Different sites in one report** use their own timezones.
## Visits end at midnight UTC
Visits (and the visit key) never cross **midnight UTC**,
whatever the site's timezone, because the daily salt rotates then. A
visitor browsing across midnight UTC counts as two visits (and two
visitor-days). For sites far from UTC, this happens during local daytime,
for example 5 pm in California or 9 am in Tokyo, and slightly raises
visits for those hours.
## API
`from` and `to` are dates in the site's timezone. Response timestamps are
ISO 8601. Timeseries buckets are wall-clock times in the site's timezone
(see [Stats endpoints](/docs/api/stats)).