# nanolytics > Web and product analytics that is agent-native and cheap at scale. Every view in the dashboard is a query on the same public Query API that agents use, and every answer can explain itself. ## Install - [AGENTS.md](https://app.nanolytics.dev/AGENTS.md): an agent installs nanolytics on the site it works on. It asks for a connect link, a person approves it once in their browser, and the agent gets the site, its snippet, a secret key and the MCP config. - [llms-full.txt](https://app.nanolytics.dev/llms-full.txt): this file with the install steps and the whole OpenAPI spec inline. ## MCP - Endpoint: https://app.nanolytics.dev/mcp (Streamable HTTP). Sign in with OAuth (the server's metadata is at https://app.nanolytics.dev/.well-known/oauth-protected-resource/mcp), or send a site's secret key as the bearer: its session sees that one site. - Claude Code: `claude mcp add --transport http nanolytics https://app.nanolytics.dev/mcp`, or with a key, `--header "Authorization: Bearer sk_…"`. - Tools: list_sites, get_schema, query, funnel, paths, error, replays, replay, create_goal, delete_goal, install_status; and for OAuth sessions, create_site and create_key. Call list_sites, then get_schema, then query (or funnel, paths, or error). - replays lists recorded sessions, newest first, each with its start, duration, pages in order, country, browser, errors and a link to watch it. It takes query's filters, and lists a session when any of its events matches: a page, a country, a browser, or an error (`{"not":{"dimension":"error_group","op":"is","value":[""]}}`). replay, given a session's recording and date from it, reads what happened without watching: its events in order, timed from the session's start, with pages, custom events, errors (with their error_group), engagement and vitals. ## Query API - `POST https://api.nanolytics.dev/v1/sites/{site}/query` with a site's secret API key as a bearer token. The body is below; the answer carries `query_id` and `as_of`. - `GET https://api.nanolytics.dev/v1/sites/{site}/schema`: dimensions, metrics, goals, and event names with their property keys, to ask about. - [OpenAPI spec](https://api.nanolytics.dev/v1/openapi.json): every field, metric and dimension. - `range`: `today`, `yesterday`, `{N}d`, `{N}mo`, `all`, or `{"from":"YYYY-MM-DD","to":"YYYY-MM-DD"}`, in the site's timezone. - Add `"explain": true` for the normalized query and the plan (rollup or scan per run of days). - Event properties: `prop.{key}` is a dimension for breakdowns and filters, with the keys from the schema's `events`. Split an event by a property with a breakdown by it and a filter on `event_name` (example below). A number reads in its shortest form (`2`); an event without the property reads empty and is in no row. - Page speed: `lcp_p75`, `inp_p75`, `cls_p75`, `fcp_p75` and `ttfb_p75` (and `_p95`, `_samples`, and `_good` and `_poor`, the share of reports in Google's good and poor bands) are the Core Web Vitals of real visits, for sites whose tracker loads the `wv` add-on (`data-ext="wv"`). Break them down by `route` (pages grouped into templates, as `/decisions/*`) to find slow page types, then by `lcp_target`, `inp_target` or `cls_target` for the element to fix. - Errors: `errors` counts occurrences of error events (one can stand for several), `first` and `last` are the epoch milliseconds of the first and last matching event, and `error_group` (an error's type and normalized message), `error_type` and `release` are dimensions, empty on other events. Sites send errors with the tracker's `errors` add-on or the Events API (`kind: error`). The examples below list this week's errors and the newest ones. ## Errors - `GET https://api.nanolytics.dev/v1/sites/{site}/errors/{group}?range=28d`, authorized as the Query API: one `error_group` value's call sites (each occurrence's top frame on the site's own host, by occurrences), releases, and latest 10 occurrences with their page, browser, release, message as sent and stack frames. - `GET https://api.nanolytics.dev/v1/sites/{site}/recordings?range=7d`, authorized as the Query API: recorded sessions, newest first, each with its entry page, pages, duration, browser, country, error occurrences and its page loads' recording IDs; `next_before` pages on. `filters`, the Query API's as JSON, lists the sessions with an event that matches. - `GET https://api.nanolytics.dev/v1/sites/{site}/recordings/{id}/session?date=YYYY-MM-DD`, authorized as the Query API: the recorded session the list shows that recording under, with its events in order (up to 1,000), each timed from the session's start. - `GET https://api.nanolytics.dev/v1/sites/{site}/recordings/{id}?date=YYYY-MM-DD`, authorized as the Query API: one session replay recording (a page load; its hits carry it as `rc`, an error occurrence as `recording`), its chunks in order with their gzipped rrweb events in base64, its gaps and its stylesheets. The metric `replays` counts recorded sessions. - Counts are occurrences of human sessions, from the latest 1,000 (`complete` says whether those were all). The group's trend, pages and browsers are Query API queries with a filter on `error_group`. ## Funnels - `POST https://api.nanolytics.dev/v1/sites/{site}/funnel`, authorized as the Query API: of the visitors who did the first step, how many then did each next step, in order, within `window` of the first (`{N}m`, `{N}h`, `{N}d`, up to `90d`; `7d` by default). - A step is `{"page": glob}`, `{"event_name": glob, "where": filter}` (the filter on the event's `prop.{key}` only) or `{"goal": name}`; 2 to 8 steps. A later step needs a strictly later event; one exactly at the window's edge counts. - Counts are exact persons: an anonymous visitor who identifies between the steps stays one person. `breakdown` splits by the first step's event's value; `filters`, `include_bots` and `explain` are the Query API's. - Each step answers `persons` (exact, followed through `identify`; not a query's `visitors`), `conversion_rate` (of step 1), `from_previous` and `median_ms` (the median time from step 1). Of visitors who viewed /pricing in the last 28 days, how many signed up within a day, and how soon: ```json {"range":"28d","steps":[{"page":"/pricing"},{"event_name":"signup"}],"window":"1d"} ``` Any page, then the signup goal, then a pro upgrade within 7 days, by the source of the first visit: ```json {"range":"30d","steps":[{"page":"/*"},{"goal":"signup"},{"event_name":"upgrade","where":{"dimension":"prop.plan","op":"is","value":["pro"]}}],"window":"7d","breakdown":{"dimension":"source","limit":10}} ``` A two-page funnel within 30 minutes, off mobile, with the plan: ```json {"range":"7d","steps":[{"page":"/p/0"},{"page":"/p/1"}],"window":"30m","filters":{"not":{"dimension":"device","op":"is","value":["mobile"]}},"explain":true} ``` ## Paths - `POST https://api.nanolytics.dev/v1/sites/{site}/paths`, authorized as the Query API: from one step `at` (a funnel step), where people went next (`"direction": "after"`, the default) or how they arrived (`"before"`), `depth` steps (1 to 5, 3 by default), each within `window` of the entry (`30m` by default). - Steps are pageviews, by route, and custom or revenue events, by name. A repeat of the step before is no step. Counts are exact persons, as funnels'; `filters`, `include_bots` and `explain` are the Query API's. - The answer: `persons` who entered; `steps`, each step's top `limit` nodes (6 by default) and an `other` node; `links` between adjacent steps; `paths`, the most common exact whole paths, in time order. A node is a funnel step as it stands. Where people went in the 30 minutes after /pricing, three steps deep: ```json {"range":"28d","at":{"page":"/pricing"}} ``` How people arrived at the signup goal within a day, two steps back, off mobile: ```json {"range":"30d","at":{"goal":"signup"},"direction":"before","depth":2,"window":"1d","filters":{"not":{"dimension":"device","op":"is","value":["mobile"]}}} ``` After any page, one step, the top 3, with the plan: ```json {"range":"7d","at":{"page":"/*"},"depth":1,"limit":3,"explain":true} ``` ## Tracker events Sites opt in on the tracker's tag. Their events are ordinary custom events: they are in the schema's event names, take props, and can be goals (`create_goal`). - `data-ext="links"`: `outbound` for a click on a link to another host, `download` for a link to a file (by extension, or the `download` attribute) on any host, never both. Prop `url`: the link without query or fragment. - `data-ext="404"` in a not-found page, or `nl.track('404')` in an app's not-found route: `404`. The add-on's props: `url`, the missing page, and `referrer`, the page with the broken link, when the browser gives one. - `data-ext="errors"`: uncaught errors, unhandled rejections and `nl.error(err, props)` for errors the site catches; `console.error` too with `data-errors="console"`. Each `Error` counts once whichever way it is reported, repeats within 60 s are sent as one event with their count, and `data-release` tags them with a release. They are `error` events, not custom events. - `data-hash`: a site that routes by fragment has each route counted as a page, sent as the path (`#/users/1` is the page `/users/1`). ## Examples 28 days by day and channel, Germany off mobile, against the period before: ```json {"range":"28d","metrics":["visitors","pageviews"],"interval":"day","breakdown":{"dimension":"channel","limit":10},"filters":{"and":[{"dimension":"country","op":"is","value":["DE"]},{"not":{"dimension":"device","op":"is","value":["mobile"]}}]},"compare":"previous"} ``` The top 10 pages of the last 7 days: ```json {"range":"7d","metrics":["visitors","pageviews"],"breakdown":{"dimension":"page","limit":10}} ``` Visitors, bounce rate and visit duration by day over the last 30 days: ```json {"range":"30d","metrics":["visitors","bounce_rate","visit_duration"],"interval":"day"} ``` Where visitors came from this month, against the same month last year: ```json {"range":"1mo","metrics":["visitors"],"breakdown":{"dimension":"source","limit":10},"compare":"year"} ``` A goal's completions, converters and conversion rate by channel over 28 days: ```json {"range":"28d","metrics":["completions","converters","conversion_rate"],"goal":"signup","breakdown":{"dimension":"channel"}} ``` The pages with the slowest LCP for real visitors over 28 days, with INP, CLS and how many reports each figure rests on: ```json {"range":"28d","metrics":["lcp_p75","inp_p75","cls_p75","lcp_samples"],"breakdown":{"dimension":"page","limit":10,"order":"lcp_p75"}} ``` A custom event split by one of its properties over 28 days: signups by plan: ```json {"range":"28d","metrics":["events","visitors"],"breakdown":{"dimension":"prop.plan"},"filters":{"dimension":"event_name","op":"is","value":["signup"]}} ``` The errors of the last 7 days by occurrences: how many, how many visitors met them, and when each was first and last seen: ```json {"range":"7d","metrics":["errors","visitors","first","last"],"breakdown":{"dimension":"error_group","limit":20,"order":"errors"},"filters":{"not":{"dimension":"error_group","op":"is","value":[""]}}} ``` Errors by when they were first seen, newest first, over all time: a group whose `first` falls after a deploy is new since it: ```json {"range":"all","metrics":["errors","first"],"breakdown":{"dimension":"error_group","limit":20,"order":"first"},"filters":{"not":{"dimension":"error_group","op":"is","value":[""]}}} ``` All-time visitors with the plan: the normalized query and, per run of days, rollup or scan: ```json {"range":"all","metrics":["visitors"],"explain":true} ```