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:
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), 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:
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:
{ "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).
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
eventscounts custom and revenue events: those sent withnl.track, and the Events API'scustomandrevenuekinds.- 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. completionsis the number of matching events.convertersis the number of distinct visitors with a matching event, counted the same way asvisitors.conversion_rateis converters divided by visitors. Itserroris 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:
- The page address has a
utm_source(orreforsource) that names an AI assistant: the source is that assistant, and the channel isai_assistant. AI assistants often tag their links but don't send a referrer. - The address has an ad-click ID (
gclid,gbraid,wbraid,msclkid): the source is Google or Bing, and the channel ispaid_search. utm_mediumnames 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, ispaid_social.- 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 andorganic_social. - The referrer is any other site: the source is its host, and the channel is
referral. - There's only a
utm_source: the source is its value, and the channel is the organic channel for its kind, orunassigned. - 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) to3xl(1920 px and over).
Bots
Bot traffic is stored, never dropped, and never counted toward your plan's events.
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,30dand 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. nullmeans there's no value, such as a day before the site's first, or an average over zero visits.0is 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 hasdata-local. - Visits from a browser where
localStorage.nl_ignoreis 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_ididentifies the query. Queries are logged for 30 days, so your agent can cite the query behind every number it gives you.as_ofis 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:
{ "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 for the full request and response, and MCP server for asking from your agent.