# Metrics

This page explains how every number in nanolytics is defined and calculated, and how to trace any number back to the query that produced it. The dashboard, the API and MCP all read the same Query API, so a number means the same thing wherever you see it.

## Visitors

`visitors` is the number of distinct visitors in the range you're looking at. Someone who visits on ten different days in a month counts as one visitor for that month.

To recognize a visitor, nanolytics uses the first of these identifiers that an event has:

| Order | Identifier | Where it comes from |
|---|---|---|
| 1 | Your user ID | `nl.identify("…")` in the browser, or `visitor.user_id` in the Events API |
| 2 | A stored visitor ID | 16 random bytes the script keeps in `localStorage` (`nl_v`), or `visitor.visitor_id` in the Events API |
| 3 | A daily hash | A hash of a salt, your site, the IP address and the user agent |

The salt behind the daily hash changes at midnight UTC and is deleted after 2 days, so a visitor identified only by the hash shows up as a new visitor each day. That happens when the browser blocks storage, after `nl.consent(false)` (see [Privacy](/docs/privacy)), and for Events API events that only include an IP address and user agent.

Safari deletes storage set by scripts after 7 days without a visit to the site, so a Safari visitor who returns after a longer gap is counted as a new visitor.

### Accuracy

Distinct counts use HyperLogLog++ at precision 14, the same method Google Analytics 4 uses for its user counts:

| Distinct visitors | Typical error |
|---|---|
| Under about 1,000 | Effectively exact |
| 100,000 | ±0.8 % (about ±800) |
| 10,000,000 | ±0.8 % (about ±80,000) |

Every way of answering a query builds the same sketch from the same visitors. You get the same number whether it comes from precomputed rollups or from raw events, and whether you ask today or after the day has been compacted.

When an estimate isn't effectively exact, the response includes its relative standard error:

```json
{ "totals": { "visitors": 48210, "pageviews": 131907, "error": { "visitors": 0.0081 } } }
```

If a metric has no `error` entry, it's effectively exact. Everything else (pageviews, visits, bounces, durations, events, conversions) is an exact sum.

## Pageviews

There's one pageview per distinct page address. The script counts the first page load and, in a single-page app, every address change made through `history.pushState`, `history.replaceState` or the back button. Changing only the fragment (`#…`) isn't a pageview unless you've turned on the site's **hash routes** option (see [Tracking options](/docs/collect)).

A page is identified by its path. The query string is never part of it, and the fragment is dropped, so `/pricing?ref=hn` and `/pricing` are the same page.

If the script resends a pageview because the first attempt wasn't confirmed, it's still stored only once.

## Visits

A visit (`visits`) is a run of one visitor's events with no gap of 30 minutes or more. Visits also end at midnight in the site's time zone, so someone who keeps reading past midnight starts a second visit.

A visit's source, channel, campaign, entry page, country and device all come from its first event. Its exit page is the path of its last pageview.

## Bounce rate

`bounce_rate` is bounces divided by visits. A bounce is a visit with exactly one pageview and no custom or revenue event.

The script sends time-on-page, page speed and identify events on its own, so those don't turn a bounce into a non-bounce. A visit with no pageview at all, such as one made up only of server-side events, isn't a bounce.

## Visit duration

`visit_duration` is the average time from a visit's first event to its last, in milliseconds. A visit with a single event has a duration of 0.

When a page is hidden or closed, the script sends how long it was visible, so the time spent on a visit's last page is included in its duration.

## Events and goals

- `events` counts custom and revenue events: those sent with `nl.track`, and the Events API's `custom` and `revenue` kinds.
- A goal matches a custom event's name or a page's path, with `*` matching any run of characters. Goals apply to all your history, including events sent before you created the goal.
- `completions` is the number of matching events.
- `converters` is the number of distinct visitors with a matching event, counted the same way as `visitors`.
- `conversion_rate` is converters divided by visitors. Its `error` is the sum of the errors of those two estimates.

## Sources and channels

Each visit gets a `source`, such as Google or ChatGPT, and a `channel`, a group such as `organic_search`. nanolytics applies these rules in order and uses the first one that matches:

1. The page address has a `utm_source` (or `ref` or `source`) that names an AI assistant: the source is that assistant, and the channel is `ai_assistant`. AI assistants often tag their links but don't send a referrer.
2. The address has an ad-click ID (`gclid`, `gbraid`, `wbraid`, `msclkid`): the source is Google or Bing, and the channel is `paid_search`.
3. `utm_medium` names a medium (`cpc`, `email`, `social`, `display`, `affiliate`, …): the channel is the one that matches, adjusted for the kind of source. A paid click from a social network, for example, is `paid_social`.
4. The referrer is a site nanolytics recognizes: the source is its name and the channel follows from its kind, such as Google and `organic_search`, or Reddit and `organic_social`.
5. The referrer is any other site: the source is its host, and the channel is `referral`.
6. There's only a `utm_source`: the source is its value, and the channel is the organic channel for its kind, or `unassigned`.
7. None of the above: there's no source, and the channel is `direct`.

A referrer from one of your site's own hosts is treated as no referrer. nanolytics recognizes a curated list of about 120 sites, including these AI assistants: ChatGPT, Claude, Perplexity, Gemini, Copilot, DeepSeek, Mistral, Grok, Meta AI, You.com, Phind, Poe, Qwen, Kimi, Doubao, Felo, Google AI Studio and NotebookLM.

The channels are `direct`, `referral`, `organic_search`, `paid_search`, `organic_social`, `paid_social`, `organic_video`, `paid_video`, `organic_shopping`, `paid_shopping`, `email`, `affiliates`, `display`, `ai_assistant` and `unassigned`.

For ad-click IDs, nanolytics only checks whether one is present. The value identifies a single click, so it's never stored.

## Location and device

- **Country, region and city** come from the location Cloudflare derives from the visitor's IP address. Events sent through the Events API come from your servers, so they have no location.
- **Browser, OS and device** come from the user agent. The user agent is stored as the browser sent it, so when parsing improves, your history is re-read with the better parser.
- **Screen** is the window's width, grouped into one of 7 bands, from `xs` (under 576 px) to `3xl` (1920 px and over).

## Bots

Bot traffic is stored, never dropped, and never counted toward your plan's events.

| Class | How it's decided |
|---|---|
| `known` | The user agent identifies itself as a crawler or monitor, or the browser reports that it's automated (`navigator.webdriver`) |
| `suspected` | A visitor with a `HeadlessChrome` user agent that day, or one with 60 pageviews within 60 seconds |
| `human` | Everything else |

Every number counts humans only. To count all three classes, add `"include_bots": true` to your query.

## Days and time zones

- Days start at midnight in the site's time zone. That applies to `today`, `30d` and every daily bucket.
- An event is counted at the time it happened, not when it arrived, so an event sent late keeps its original time. The script drops events older than 72 hours.
- If you change a site's time zone, the change takes effect at the next midnight in the old time zone. Earlier days keep the time zone they were counted in.
- The bucket that holds the most recent data is marked `"partial": true`.
- `null` means there's no value, such as a day before the site's first, or an average over zero visits. `0` is a real zero.

## Excluded traffic

These are never counted:

- Visits on a local dev server (`localhost`, `127.0.0.1`, `[::1]`, `*.localhost`), unless the script tag has `data-local`.
- Visits from a browser where `localStorage.nl_ignore` is set. Set it in your own browser to leave out your own visits.
- Events from a host that isn't one of the site's allowed hosts, so if someone copies your snippet onto their site, their traffic doesn't count.

## Tracing a number to its query

Every response includes two fields in `meta`:

- `query_id` identifies the query. Queries are logged for 30 days, so your agent can cite the query behind every number it gives you.
- `as_of` is the moment the data was read.

Add `"explain": true` to a query to also get the query as it was actually run (range resolved, defaults filled in, goals expanded) and the plan, which splits the range into runs of days:

```json
{ "from": "2026-11-01", "to": "2026-11-15", "source": "rollup" }
```

When a run was read from raw events (`"source": "scan"`), its `reason` explains why: `stale` (the day isn't closed yet), `filter` or `metric` (the rollups can't answer that question), `hour`, `bots` or `values`. The plan also includes a digest of every input the answer depends on, so the same digest and query always give the same answer.

See [Query API](/docs/api) for the full request and response, and [MCP server](/docs/mcp) for asking from your agent.
