# 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} ``` ## Install nanolytics > For coding agents. nanolytics is web and product analytics. Install it on the site you work on, then ask about its traffic through MCP or the Query API. A person approves once in their browser; you get the site, its snippet, a secret key and the MCP config. ### Given a code If the person pasted a prompt from nanolytics with a `device_code`, they approved it there: skip steps 1 to 3. The prompt's one call saved the result to the file its `curl -o` names; go on at step 4 with that file as `$RESULT`. If the file's `error` is `expired_token` or `invalid_grant`, the code is spent: ask them for a new prompt, or start at step 1. ### 1. Ask for a connect link ```sh curl -s -X POST https://app.nanolytics.dev/api/connect -H 'content-type: application/json' \ -d '{"domain":"example.com","timezone":"Europe/Athens","client":"Claude Code"}' ``` - `domain`: the site's production hostname. It becomes the one host the tracker may report from. - `timezone`: an IANA name, the machine's or the site's; days start at midnight there. UTC by default. - `client`: your name. The person sees it, and it names the key. The answer is RFC 8628's: `device_code` (keep it to yourself), `user_code`, `verification_uri_complete`, `expires_in` (900 s) and `interval` (5 s). Nothing is created yet. ### 2. Give the person the link Show `verification_uri_complete` and `user_code`, and ask them to approve. They sign in or sign up, check that the code matches yours, and pick the organization. ### 3. Poll until they decide ```sh RESULT="${TMPDIR:-/tmp}/nanolytics-$USER_CODE.json" curl -s -X POST https://app.nanolytics.dev/api/connect/token -o "$RESULT" \ -d grant_type=urn:ietf:params:oauth:grant-type:device_code -d device_code=$DEVICE_CODE jq -r '.error // "ready"' "$RESULT" ``` The result holds a secret key, so it goes to a file, named by your request, and never to the screen. One call every `interval` seconds; each answers at once, so run it in a loop of short calls, not one that waits. While there's no result, the file's `error`: - `authorization_pending`: not yet; ask again after `interval`. - `slow_down`: add 5 seconds to `interval`. - `access_denied`: the person said no. Stop. - `expired_token`: nobody approved within 15 minutes. Start again at step 1. - `invalid_grant`: no such request, or its result was already handed out. Start again at step 1. `ready` is the result, handed out once: keep the file until step 4 is done. If the domain is already one of the organization's sites, it is that site with a new key, not a second site. ### 4. Put each piece where it goes The result in `$RESULT` holds the site's secret key, `access_token`. Keep it out of the transcript and the repository: never print it (`jq 'del(.access_token)' "$RESULT"` shows the rest), save it before anything else, and make the repository's own `.gitignore` cover `.env.local`: ```sh echo "NANOLYTICS_KEY=$(jq -r .access_token "$RESULT")" >> .env.local git -c core.excludesFile=/dev/null check-ignore -q .env.local || printf '\n.env.local\n' >> .gitignore ``` - `snippet.html` in the `` of every page (`index.html` for Vite), or `snippet.nextjs` inside `` in Next.js's `app/layout.tsx`. It holds only the site's public key, so commit it. - MCP: run `mcp.claude_code` in Claude Code. It reads the key from `.env.local` and keeps the server for this project on this machine, not in the repository; its tools appear in the next session. Other clients take `mcp.config`, which reads `${NANOLYTICS_KEY}` from the environment. ### 5. Check it before deploying Run `check.hit`, then `check.health`, from the project's root. The hit is one test pageview as if from a dev server, sent without a browser or a change to the project; it answers 202. Within 10 seconds the health lists it under `host_not_allowed` with `localhost` as the sample, and nothing is counted: the site, its public key and the endpoint work. A new key also takes up to 10 seconds: if the health answers `unauthorized`, wait and run it again. Then delete `$RESULT`. After the deploy, the MCP tool `install_status` shows the first real hit, and the dashboard (`site.dashboard`) the visit within seconds. ### Already signed in to MCP With an OAuth session, `create_site` makes the site (or returns the one the organization has for that domain) and its snippet, `install_status` checks it, and `create_key` makes a key for server-side events. ### Then - [llms.txt](https://app.nanolytics.dev/llms.txt): the MCP tools and the Query API, with examples. - [llms-full.txt](https://app.nanolytics.dev/llms-full.txt): all of it, with the OpenAPI spec inline. ## OpenAPI ```json { "openapi": "3.1.0", "info": { "title": "nanolytics data plane", "version": "0.1.0", "description": "The public endpoints of a nanolytics instance (ARCHITECTURE §12.1): Collect, the Events API, and the site-scoped Query, Funnel, Paths, Schema and Live endpoints. Written by hand next to the handlers (crates/nl-http); `packages/api` is generated from it, and its tests run every example below against a running instance and validate each answer against these schemas." }, "servers": [ { "url": "https://e.nanolytics.dev" } ], "security": [], "paths": { "/v1/e": { "post": { "operationId": "collect", "summary": "Collect: one tracker hit or a batch", "description": "Sent as `text/plain`, so a browser needs no CORS preflight. A malformed hit rejects only itself and is counted, and the answer is still 202: a tracker can't act on a rejection. 503 only for backpressure or draining, which the tracker retries. Every answer carries `Access-Control-Allow-Origin: *`.", "requestBody": { "required": true, "content": { "text/plain": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Hit" }, { "type": "array", "items": { "$ref": "#/components/schemas/Hit" }, "maxItems": 100 } ] } } } }, "responses": { "202": { "description": "Every accepted hit is durable." }, "503": { "description": "Nothing could be acknowledged: retry." } } } }, "/v1/r": { "post": { "operationId": "replayChunk", "summary": "Session replay: one chunk of a recording", "description": "Sent by the replay add-on (ADR 0023) as `text/plain`, so no CORS preflight: a JSON header, a newline, then the chunk: rrweb events as JSON lines, gzipped, or plain when a hidden page sends its last events at once (the reader tells them apart by gzip's magic bytes), up to 1 MiB in all. The header is a hit (`Hit`'s keys) of kind `rp` with `rc` (its recording), `q` (its place, from 0), `d` (its duration in ms) and `css` (the SHA-256s of the linked stylesheets it first names). The bytes are stored once, encrypted under a key that only the chunk's row holds; the server never reads them. Every answer carries `Access-Control-Allow-Origin: *`.", "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string" } } } }, "responses": { "202": { "description": "The chunk is durable. `missing`: the stylesheets it names that the site lacks, to upload to `/v1/r/css`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "missing" ], "properties": { "missing": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "A chunk the page should not resend: malformed, over a limit, or for no site." }, "403": { "description": "Not recorded: replay is off for the site, the page's host isn't one the site allows, or the user agent declares a bot. The page stops recording." }, "413": { "description": "Over 1 MiB." }, "429": { "description": "The site's blob bytes for the day are used up. The page stops recording." }, "503": { "description": "Nothing was stored: retry." } } } }, "/v1/r/css": { "post": { "operationId": "replayStylesheet", "summary": "Session replay: a stylesheet a recording uses", "description": "A JSON header (`s`, the site's public key; `h`, the SHA-256 of the text in hex), a newline, then the stylesheet's text, up to 2 MiB, as `text/plain`. Stored as a site asset once per site and hash; the player resolves recordings' stylesheets through them.", "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string" } } } }, "responses": { "202": { "description": "Stored, or the site already had it." }, "400": { "description": "Malformed, for no site, or the text's SHA-256 is not `h`." }, "403": { "description": "Replay is off for the site." }, "413": { "description": "Over 2 MiB." }, "429": { "description": "The site's blob bytes for the day are used up." }, "503": { "description": "Nothing was stored: retry." } } } }, "/v1/events": { "post": { "operationId": "events", "summary": "Events API: server-side events", "security": [ { "bearer": [] } ], "description": "Authorized by a secret API key (`sk_…`). Whether an event is a duplicate is known only at merge time, so it is never reported here.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiEvent" }, { "type": "array", "items": { "$ref": "#/components/schemas/ApiEvent" }, "maxItems": 1000 } ] } } } }, "responses": { "200": { "description": "One result per event, in order, once the accepted ones are durable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsResponse" } } } }, "400": { "$ref": "#/components/responses/EventsError" }, "401": { "$ref": "#/components/responses/EventsError" }, "413": { "$ref": "#/components/responses/EventsError" }, "503": { "$ref": "#/components/responses/EventsError" } } } }, "/v1/sites/{site}/query": { "post": { "operationId": "query", "summary": "Query API", "description": "The body is the query IR (ARCHITECTURE §11.1) in JSON. A relative range resolves against the site's today. A request the engine can't answer is rejected, never approximated: the error names the field (`path`) and the valid choices.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "examples": { "dashboard": { "summary": "28 days by day and channel, Germany off mobile, against the period before", "value": { "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" } }, "top_pages": { "summary": "The top 10 pages of the last 7 days", "value": { "range": "7d", "metrics": [ "visitors", "pageviews" ], "breakdown": { "dimension": "page", "limit": 10 } } }, "traffic_trend": { "summary": "Visitors, bounce rate and visit duration by day over the last 30 days", "value": { "range": "30d", "metrics": [ "visitors", "bounce_rate", "visit_duration" ], "interval": "day" } }, "sources": { "summary": "Where visitors came from this month, against the same month last year", "value": { "range": "1mo", "metrics": [ "visitors" ], "breakdown": { "dimension": "source", "limit": 10 }, "compare": "year" } }, "goal_by_channel": { "summary": "A goal's completions, converters and conversion rate by channel over 28 days", "value": { "range": "28d", "metrics": [ "completions", "converters", "conversion_rate" ], "goal": "signup", "breakdown": { "dimension": "channel" } } }, "slow_pages": { "summary": "The pages with the slowest LCP for real visitors over 28 days, with INP, CLS and how many reports each figure rests on", "value": { "range": "28d", "metrics": [ "lcp_p75", "inp_p75", "cls_p75", "lcp_samples" ], "breakdown": { "dimension": "page", "limit": 10, "order": "lcp_p75" } } }, "event_by_property": { "summary": "A custom event split by one of its properties over 28 days: signups by plan", "value": { "range": "28d", "metrics": [ "events", "visitors" ], "breakdown": { "dimension": "prop.plan" }, "filters": { "dimension": "event_name", "op": "is", "value": [ "signup" ] } } }, "top_errors": { "summary": "The errors of the last 7 days by occurrences: how many, how many visitors met them, and when each was first and last seen", "value": { "range": "7d", "metrics": [ "errors", "visitors", "first", "last" ], "breakdown": { "dimension": "error_group", "limit": 20, "order": "errors" }, "filters": { "not": { "dimension": "error_group", "op": "is", "value": [ "" ] } } } }, "new_errors": { "summary": "Errors by when they were first seen, newest first, over all time: a group whose `first` falls after a deploy is new since it", "value": { "range": "all", "metrics": [ "errors", "first" ], "breakdown": { "dimension": "error_group", "limit": 20, "order": "first" }, "filters": { "not": { "dimension": "error_group", "op": "is", "value": [ "" ] } } } }, "explained": { "summary": "All-time visitors with the plan: the normalized query and, per run of days, rollup or scan", "value": { "range": "all", "metrics": [ "visitors" ], "explain": true } } } } } }, "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/funnel": { "post": { "operationId": "funnel", "summary": "Funnel", "description": "Of the visitors who did the first step, how many then did each next step, in order, within the window of the first, and how soon (ADR 0015). Counts are exact `persons`: a visitor ID, with an anonymous ID that an `identify` event in the range paired with a user counted as that user. A later step needs a strictly later event; one exactly at the window's edge counts. Always a scan of the range's events, so `meta.explain.plan` gives `funnel` as each run's reason.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelRequest" }, "examples": { "pricing_to_signup": { "summary": "Of visitors who viewed /pricing in the last 28 days, how many signed up within a day, and how soon", "value": { "range": "28d", "steps": [ { "page": "/pricing" }, { "event_name": "signup" } ], "window": "1d" } }, "signup_by_source": { "summary": "Any page, then the signup goal, then a pro upgrade within 7 days, by the source of the first visit", "value": { "range": "30d", "steps": [ { "page": "/*" }, { "goal": "signup" }, { "event_name": "upgrade", "where": { "dimension": "prop.plan", "op": "is", "value": [ "pro" ] } } ], "window": "7d", "breakdown": { "dimension": "source", "limit": 10 } } }, "explained": { "summary": "A two-page funnel within 30 minutes, off mobile, with the plan", "value": { "range": "7d", "steps": [ { "page": "/p/0" }, { "page": "/p/1" } ], "window": "30m", "filters": { "not": { "dimension": "device", "op": "is", "value": [ "mobile" ] } }, "explain": true } } } } } }, "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/paths": { "post": { "operationId": "paths", "summary": "Paths", "description": "From one step, where people went next, a few steps deep (`after`), or how they arrived at it (`before`) (ADR 0017). Steps are pageviews, by the page's route, and custom or revenue events, by name; automatic hits never are. A person enters at their earliest event matching `at`, and their path follows their step events strictly after it (or before it, nearest first), each within `window` of the entry, up to `depth`. A repeat of the step before is no step, and one millisecond makes at most one. Counts are exact `persons`, as funnels': a visitor ID, an anonymous ID an `identify` in the range paired with a user counted as that user. Each step keeps its top `limit` nodes and folds the rest into `other`. A node is a funnel step as it stands; a listed path's persons are at most the funnel's through it, which also counts later steps. Always a scan of the range's events, so `meta.explain.plan` gives `paths` as each run's reason.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathsRequest" }, "examples": { "after_pricing": { "summary": "Where people went in the 30 minutes after /pricing, three steps deep", "value": { "range": "28d", "at": { "page": "/pricing" } } }, "before_signup": { "summary": "How people arrived at the signup goal within a day, two steps back, off mobile", "value": { "range": "30d", "at": { "goal": "signup" }, "direction": "before", "depth": 2, "window": "1d", "filters": { "not": { "dimension": "device", "op": "is", "value": [ "mobile" ] } } } }, "explained": { "summary": "After any page, one step, the top 3, with the plan", "value": { "range": "7d", "at": { "page": "/*" }, "depth": 1, "limit": 3, "explain": true } } } } } }, "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathsResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/health": { "get": { "operationId": "health", "summary": "The site's hits dropped in the last 15 minutes, by reason", "description": "Collect answers 202 to a hit it drops, because a tracker can't act on the reason. This is where the site's owner sees it: each reason with its count across all instances, when it last happened, and for host_not_allowed the host the hits came from.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" } ], "responses": { "200": { "description": "The site's recent rejections; empty when none.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/errors/{group}": { "get": { "operationId": "errorGroup", "summary": "One error group: where it is thrown, in which releases, and its latest occurrences", "description": "An error group is an `error_group` value: an error's type and normalized message (ADR 0022). This reads the group's occurrences in the range, newest first, from human sessions only, as the rollups count them: its call sites (each occurrence's top frame on the page's own host, `null` when it has none) and releases, by occurrences, from the latest 1,000 (`complete` says whether those were all), and its latest 10 with their parsed frames. The group's figures over time are the Query API's, filtered on `error_group`.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" }, { "name": "group", "in": "path", "required": true, "description": "The `error_group` value, URL-encoded.", "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } }, { "name": "range", "in": "query", "description": "The Query API's `today`, `yesterday`, `{N}d`, `{N}mo` or `all`; `28d` when absent.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "With `to`, a range of YYYY-MM-DD dates instead of `range`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The group in the range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorGroup" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/recordings": { "get": { "operationId": "recordings", "summary": "Recorded sessions, newest first, with their page loads' recordings", "description": "Human sessions with a session replay recording (ADR 0023), newest first: when each started, how long it lasted, its entry page, pageviews, error occurrences, browser, OS, device and country, and its recordings, one per recorded page load in order. Read from the rows, newest day first, until `limit` sessions are found; `next_before` pages on.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" }, { "name": "range", "in": "query", "description": "The Query API's `today`, `yesterday`, `{N}d`, `{N}mo` or `all`; `28d` when absent.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "With `to`, a range of YYYY-MM-DD dates instead of `range`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "filters", "in": "query", "description": "A `Filter` as JSON, the Query API's: a session is listed when one of its events matches, as `visits` counts it. With an error: `{\"not\":{\"dimension\":\"error_group\",\"op\":\"is\",\"value\":[\"\"]}}`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Sessions to return, 50 by default.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "before", "in": "query", "description": "Only sessions that started before this, epoch milliseconds: the last answer's `next_before`.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The recorded sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordingList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/recordings/{id}": { "get": { "operationId": "recording", "summary": "One session replay recording: its chunks in order, its gaps and its stylesheets", "description": "A recording is one page load's session replay (ADR 0023); every hit of the page load names it in `rc`. Its chunks come in `seq` order, the earliest copy of each, with their gzipped rrweb events in base64; `gaps` lists the missing `seq`s below the last, chunks lost when the page closed. Each stylesheet the chunks name is its text, or `null` when the site never uploaded it (a player falls back to its URL). Pending deletions apply.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" }, { "name": "id", "in": "path", "required": true, "description": "The recording, as 32 hex digits.", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } }, { "name": "date", "in": "query", "required": true, "description": "A site-local date the recording was seen on, YYYY-MM-DD: that of any hit naming it. The days on each side are read too.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The recording.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recording" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/recordings/{id}/session": { "get": { "operationId": "recordingSession", "summary": "The recorded session a recording is listed under, with its events in order", "description": "What happened in a recorded session, for a reader that won't play the replay: the session as the list shows it, where it came from, and its events in order (up to 1,000), each timed from the session's start, with its page, a custom event's name and properties, an error's group, type and message, engagement, vitals and revenue, and its page load's recording. The session is the one the list shows the recording under; of two days that list it, the earlier.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" }, { "name": "id", "in": "path", "required": true, "description": "The recording, as 32 hex digits.", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } }, { "name": "date", "in": "query", "required": true, "description": "A site-local date the recording was seen on, YYYY-MM-DD. The days on each side are read too.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The session and its events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTimeline" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/sourcemaps": { "post": { "operationId": "uploadSourcemap", "summary": "Store a source map, by the debug ID it holds", "description": "The body is the map file, with a top-level `debugId` (ECMA-426; `@nanolytics/cli sourcemaps inject` writes it, and uploads with `sourcemaps upload`). Up to 32 MiB. Stored encrypted, once per site and debug ID; read only to symbolicate the site's stacks, when they are read (ADR 0022), so a map uploaded late applies to every stack already stored.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" }, { "name": "release", "in": "query", "description": "The release the map's bundle belongs to, at most 64 bytes.", "schema": { "type": "string", "maxLength": 64 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Durable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "debug_id", "stored" ], "properties": { "debug_id": { "type": "string", "description": "32 hex digits." }, "stored": { "type": "boolean", "description": "`false`: the site already had it." } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "413": { "description": "Over 32 MiB." }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/schema": { "get": { "operationId": "schema", "summary": "What a client needs to write a query, over the last 28 days", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" } ], "responses": { "200": { "description": "The site's schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schema" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/sites/{site}/live": { "get": { "operationId": "live", "summary": "Live: Server-Sent Events from the tail", "description": "Events: `visitors` every 5 s (the first at once), data `LiveVisitors`; `hit` per human pageview, custom or revenue event, data `LiveHit`. There is no replay: a reconnect starts from now.", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Site" } ], "responses": { "200": { "description": "An event stream.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "The app's service credential (any site the config knows), or a site's secret API key (`sk_…`, its own site only)." } }, "parameters": { "Site": { "name": "site", "in": "path", "required": true, "description": "The site's id.", "schema": { "type": "integer", "minimum": 0 } } }, "responses": { "Error": { "description": "`400 invalid_query`, `401 unauthorized`, `403 forbidden`, `404 not_found`, `500 internal`, `503 not_ready` or `unavailable` (retry), `504 timeout` (60 s).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "EventsError": { "description": "`400 body_not_json`, `401 unauthorized`, `413 too_large` or `body_too_large`, `503 unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsError" } } } } }, "schemas": { "Frame": { "type": "object", "required": [ "file", "function", "line", "column", "in_app", "source", "unsymbolicated" ], "description": "A stack frame as the browser wrote it (Chrome's `at fn (url:line:col)`, Firefox's and Safari's `fn@url:line:col`), and its source when the bundle's source map is uploaded.", "properties": { "file": { "type": "string" }, "function": { "type": "string", "description": "Empty when the engine gave none." }, "line": { "type": "integer" }, "column": { "type": "integer" }, "in_app": { "type": "boolean", "description": "On the page's own host." }, "source": { "oneOf": [ { "type": "object", "required": [ "file", "function", "line", "column", "context" ], "properties": { "file": { "type": "string" }, "function": { "type": "string" }, "line": { "type": "integer" }, "column": { "type": "integer" }, "context": { "oneOf": [ { "type": "object", "required": [ "before", "line", "after" ], "description": "Three lines either side, where the map holds `sourcesContent`.", "properties": { "before": { "type": "array", "items": { "type": "string" } }, "line": { "type": "string" }, "after": { "type": "array", "items": { "type": "string" } } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "unsymbolicated": { "type": [ "string", "null" ], "enum": [ "no_debug_id", "no_map", "no_mapping", null ], "description": "Why `source` is null: the file sent no debug ID, none of the site's maps has it, or the map has nothing at that position." } } }, "SessionTimeline": { "type": "object", "required": [ "start_ms", "duration_ms", "host", "entry_page", "pageviews", "pages", "errors", "browser", "os", "device", "country", "recordings", "source", "channel", "referrer_host", "events", "truncated" ], "properties": { "start_ms": { "type": "integer" }, "duration_ms": { "type": "integer" }, "host": { "type": "string" }, "entry_page": { "type": "string" }, "pageviews": { "type": "integer" }, "pages": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "integer", "description": "Error occurrences in the session." }, "browser": { "type": "string" }, "os": { "type": "string" }, "device": { "type": "string" }, "country": { "type": "string" }, "recordings": { "type": "array", "items": { "type": "object", "required": [ "id", "start_ms", "duration_ms", "path" ], "properties": { "id": { "type": "string" }, "start_ms": { "type": "integer" }, "duration_ms": { "type": "integer" }, "path": { "type": "string" } } } }, "source": { "type": "string", "description": "The first event's source." }, "channel": { "type": "string" }, "referrer_host": { "type": "string" }, "events": { "type": "array", "maxItems": 1000, "items": { "type": "object", "required": [ "at_ms", "kind", "path" ], "properties": { "at_ms": { "type": "integer", "description": "Milliseconds since the session started." }, "kind": { "type": "string", "enum": [ "pageview", "custom", "engagement", "revenue", "vitals", "identify", "error" ] }, "path": { "type": "string" }, "name": { "type": "string", "description": "A custom or revenue event's name." }, "props": { "type": "object", "additionalProperties": { "type": "string" } }, "error": { "type": "object", "required": [ "group", "type", "message", "count", "handled" ], "properties": { "group": { "type": "string", "description": "The error_group value, for the Query API and the error group endpoint." }, "type": { "type": "string" }, "message": { "type": "string" }, "count": { "type": "integer" }, "handled": { "type": "boolean" } } }, "engagement_ms": { "type": "integer" }, "vitals": { "type": "object", "properties": { "lcp": { "type": "number" }, "inp": { "type": "number" }, "cls": { "type": "number" }, "fcp": { "type": "number" }, "ttfb": { "type": "number" }, "lcp_target": { "type": "string" }, "inp_target": { "type": "string" }, "cls_target": { "type": "string" } } }, "revenue": { "type": "object", "required": [ "amount_minor", "currency" ], "properties": { "amount_minor": { "type": "integer" }, "currency": { "type": "string" } } }, "recording": { "type": "string", "description": "The page load's recording, 32 hex digits." } } } }, "truncated": { "type": "boolean", "description": "The session had more than 1,000 events: these are the first." } } }, "RecordingList": { "type": "object", "required": [ "from", "to", "filters", "sessions", "next_before" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "filters": { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "type": "null" } ], "description": "The filter applied, normalized; `null` for none." }, "sessions": { "type": "array", "items": { "type": "object", "required": [ "start_ms", "duration_ms", "host", "entry_page", "pageviews", "pages", "errors", "browser", "os", "device", "country", "recordings" ], "properties": { "start_ms": { "type": "integer" }, "duration_ms": { "type": "integer" }, "host": { "type": "string" }, "entry_page": { "type": "string" }, "pageviews": { "type": "integer" }, "pages": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Its pageviews' paths in order, a page repeated at once named once; at most 20. A single-page app's routes are here, where `recordings` has one page load." }, "errors": { "type": "integer", "description": "Error occurrences in the session." }, "browser": { "type": "string" }, "os": { "type": "string" }, "device": { "type": "string" }, "country": { "type": "string" }, "recordings": { "type": "array", "items": { "type": "object", "required": [ "id", "start_ms", "duration_ms", "path" ], "properties": { "id": { "type": "string" }, "start_ms": { "type": "integer" }, "duration_ms": { "type": "integer" }, "path": { "type": "string", "description": "The page the recording started on." } } } } } } }, "next_before": { "type": [ "integer", "null" ], "description": "When there are older sessions: `before` for the next page." } } }, "Recording": { "type": "object", "required": [ "id", "start_ms", "duration_ms", "host", "path", "browser", "os", "device", "country", "chunks", "gaps", "errors", "stylesheets" ], "properties": { "id": { "type": "string" }, "start_ms": { "type": "integer", "description": "The first chunk's start, epoch milliseconds." }, "duration_ms": { "type": "integer", "description": "From the first chunk's start to the last one's end." }, "host": { "type": "string" }, "path": { "type": "string" }, "browser": { "type": "string" }, "os": { "type": "string" }, "device": { "type": "string" }, "country": { "type": "string" }, "chunks": { "type": "array", "items": { "type": "object", "required": [ "seq", "ts_ms", "duration_ms", "data" ], "properties": { "seq": { "type": "integer" }, "ts_ms": { "type": "integer", "description": "Its first event's time, epoch milliseconds." }, "duration_ms": { "type": "integer" }, "data": { "type": "string", "description": "The page's JSON lines (rrweb events), gzipped or plain (gzip's magic bytes tell), in base64." } } } }, "gaps": { "type": "array", "items": { "type": "integer" } }, "errors": { "type": "array", "description": "The errors the page load threw, in time order.", "items": { "type": "object", "required": [ "ts_ms", "group", "message" ], "properties": { "ts_ms": { "type": "integer" }, "group": { "type": "string", "description": "Its `error_group`." }, "message": { "type": "string", "description": "The message as sent." } } } }, "stylesheets": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "description": "Each stylesheet the chunks name, by SHA-256: its text, or `null` when the site never uploaded it." } } }, "ErrorGroup": { "type": "object", "required": [ "group", "from", "to", "read", "complete", "call_sites", "releases", "latest" ], "properties": { "group": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "read": { "type": "integer", "description": "The occurrences `call_sites` and `releases` were read from: the range's latest, at most 1,000." }, "complete": { "type": "boolean", "description": "Whether those were all the range's occurrences." }, "call_sites": { "type": "array", "items": { "type": "object", "required": [ "frame", "count" ], "description": "A call site is its source position when symbolicated, so two builds of one line are one call site.", "properties": { "frame": { "oneOf": [ { "$ref": "#/components/schemas/Frame" }, { "type": "null" } ], "description": "`null`: no frame on the page's host (a third-party script's error, or no stack). Without `context`." }, "count": { "type": "integer", "description": "Occurrences thrown there." } } } }, "releases": { "type": "array", "items": { "type": "object", "required": [ "release", "count" ], "properties": { "release": { "type": "string", "description": "Empty when unknown." }, "count": { "type": "integer" } } } }, "latest": { "type": "array", "description": "The latest 10, newest first.", "items": { "type": "object", "required": [ "ts_ms", "host", "path", "browser", "os", "country", "release", "message", "mechanism", "handled", "count", "recording", "frames" ], "properties": { "ts_ms": { "type": "integer", "description": "Epoch milliseconds." }, "host": { "type": "string" }, "path": { "type": "string" }, "browser": { "type": "string" }, "os": { "type": "string" }, "country": { "type": "string" }, "release": { "type": "string" }, "message": { "type": "string", "description": "As sent, before normalizing." }, "mechanism": { "type": "string", "enum": [ "onerror", "rejection", "console", "manual" ] }, "handled": { "type": "boolean" }, "count": { "type": "integer", "description": "The occurrences this one stands for." }, "recording": { "type": [ "string", "null" ], "description": "The page load's replay recording, 32 hex digits." }, "frames": { "type": "array", "items": { "$ref": "#/components/schemas/Frame" } } } } } } }, "Hit": { "type": "object", "description": "One tracker hit, with short keys (ARCHITECTURE §12.1).", "required": [ "s", "t", "i", "a" ], "properties": { "s": { "type": "string", "description": "The site's public key." }, "t": { "type": "string", "enum": [ "pv", "ev", "en", "rv", "wv", "id", "er" ], "description": "Kind: pageview, custom event, engagement, revenue, vitals, identify, error." }, "i": { "type": "string", "description": "Event id: 16 random bytes, base64 without padding." }, "a": { "type": "integer", "description": "Milliseconds since the hit was created, on the client's clock." }, "rs": { "type": "integer", "enum": [ 1 ], "description": "Present on a resend." }, "u": { "type": "string", "description": "Page URL (required except for `id`)." }, "r": { "type": "string", "description": "Referrer URL." }, "n": { "type": "string", "description": "Event name (`ev`, `rv`)." }, "p": { "type": "object", "additionalProperties": { "type": [ "string", "number" ] }, "maxProperties": 30 }, "w": { "type": "integer", "description": "Viewport width in CSS pixels." }, "d": { "type": "integer", "description": "Engagement milliseconds (`en`)." }, "v": { "type": "object", "properties": { "lcp": { "type": "number" }, "inp": { "type": "number" }, "cls": { "type": "number" }, "fcp": { "type": "number" }, "ttfb": { "type": "number" } } }, "l": { "type": "string", "description": "The page load a `wv` report measures: 16 random bytes, base64. A load's latest report is the one that counts." }, "vt": { "type": "object", "description": "A `wv` report's attribution: the CSS selector of the element its LCP, its INP interaction and its largest layout shift blame. Cut to 256 bytes.", "properties": { "lcp": { "type": "string" }, "inp": { "type": "string" }, "cls": { "type": "string" } } }, "vi": { "type": "string", "description": "The INP interaction's kind (`wv`): `pointer` or `keyboard`." }, "rv": { "type": "object", "required": [ "m", "c" ], "properties": { "m": { "type": "integer" }, "c": { "type": "string" } } }, "et": { "type": "string", "description": "An error's type (`er`), such as `TypeError`. Cut to 128 bytes." }, "em": { "type": "string", "description": "An error's message (`er`). Cut to 1 KiB. An `er` hit needs `et` or `em`." }, "es": { "type": "string", "description": "An error's stack as the browser wrote it (`er`). Cut to 8 KiB." }, "ek": { "type": "string", "enum": [ "e", "r", "c", "m" ], "description": "How the error was caught (`er`): `e` onerror (the default), `r` an unhandled rejection, `c` console.error, `m` nl.error." }, "eh": { "type": "integer", "enum": [ 1 ], "description": "Present when the site caught the error (`er`)." }, "ec": { "type": "integer", "minimum": 1, "description": "The occurrences the hit stands for (`er`): repeats within the tracker's 60 s window are sent once. Absent means 1." }, "rl": { "type": "string", "description": "The site's release (`er`). Cut to 64 bytes." }, "dbg": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The debug IDs (ECMA-426, UUIDs) of the bundles in the stack, by file URL (`er`). At most 10; one that doesn't parse is dropped." }, "rc": { "type": "string", "description": "The page load's replay recording: 16 random bytes, base64." }, "vid": { "type": "string", "description": "Persistent visitor id: 16 random bytes, base64." }, "uid": { "type": "string", "description": "The user id passed to `identify()`." }, "x": { "type": "string", "description": "Tracker version." }, "wd": { "type": "boolean", "description": "The browser is driven by automation (`navigator.webdriver`): its hits are stored as a declared bot's." } } }, "ApiEvent": { "type": "object", "required": [ "event_id", "kind", "visitor" ], "properties": { "event_id": { "type": "string", "description": "32 hex digits or a UUID." }, "kind": { "type": "string", "enum": [ "pageview", "custom", "engagement", "revenue", "vitals", "identify", "error" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "referrer": { "type": "string" }, "props": { "type": "object", "additionalProperties": { "type": [ "string", "number" ] } }, "revenue": { "type": "object", "required": [ "amount_minor", "currency" ], "properties": { "amount_minor": { "type": "integer" }, "currency": { "type": "string" } } }, "error": { "type": "object", "description": "Required for `error` events. Texts are cut to their caps: type 128 bytes, message 1 KiB, stack 8 KiB, release 64 bytes; a type or a message is required.", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "stack": { "type": "string" }, "mechanism": { "type": "string", "enum": [ "onerror", "rejection", "console", "manual" ], "description": "Default `manual`." }, "handled": { "type": "boolean", "description": "Default true for `manual`, else false." }, "count": { "type": "integer", "minimum": 1, "description": "The occurrences the event stands for. Default 1." }, "release": { "type": "string" }, "debug_ids": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "file", "id" ], "properties": { "file": { "type": "string" }, "id": { "type": "string", "description": "32 hex digits or a UUID." } } } } } }, "recording": { "type": "string", "description": "The page load's replay recording: 32 hex digits or a UUID." }, "ts": { "type": "string", "format": "date-time", "description": "RFC 3339, within [now − 7 d, now + 5 min]." }, "visitor": { "oneOf": [ { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string" } } }, { "type": "object", "required": [ "visitor_id" ], "properties": { "visitor_id": { "type": "string" } } }, { "type": "object", "required": [ "ip", "user_agent" ], "properties": { "ip": { "type": "string" }, "user_agent": { "type": "string" } } } ] } } }, "EventsResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "status" ], "properties": { "status": { "const": "accepted" } }, "additionalProperties": false }, { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "const": "rejected" }, "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false } ] } } } }, "EventsError": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string", "description": "The query body's field at fault, as `filters.and[0].value`; empty for the body as a whole." } } } } }, "Metric": { "type": "string", "enum": [ "visitors", "visits", "pageviews", "events", "bounce_rate", "visit_duration", "completions", "converters", "conversion_rate", "errors", "first", "last", "replays", "lcp_p75", "lcp_p95", "lcp_samples", "lcp_good", "lcp_poor", "inp_p75", "inp_p95", "inp_samples", "inp_good", "inp_poor", "cls_p75", "cls_p95", "cls_samples", "cls_good", "cls_poor", "fcp_p75", "fcp_p95", "fcp_samples", "fcp_good", "fcp_poor", "ttfb_p75", "ttfb_p95", "ttfb_samples", "ttfb_good", "ttfb_poor" ], "description": "Counts and rates; `errors`, the occurrences of the matching error events (an error event can stand for several); `first` and `last`, the time of the first and last matching event in epoch milliseconds (`null` without one); `replays`, recorded sessions: sessions whose hits name a session replay recording with a chunk that day (counted like `visits`); then the Core Web Vitals: for each of LCP, INP, CLS, FCP and TTFB, its 75th and 95th percentile over the reports of the matching events (whole milliseconds; CLS a score), how many reports there are, and the share of them that is good (`_good`, at most the good threshold) and poor (`_poor`, above the poor threshold), the rest needing improvement. A percentile is within 1 % of a reported value at its rank; a share counts a report within 1 % of a threshold on either side, as the percentile reads it, so the two never disagree about which side of a threshold a report is on. Both are `null` without reports. Google's thresholds: good at most LCP 2500, INP 200, CLS 0.1, FCP 1800, TTFB 800; poor above LCP 4000, INP 500, CLS 0.25, FCP 3000, TTFB 1800. `revenue` is reserved (P1) and rejected for now." }, "Dimension": { "type": "string", "enum": [ "entry_page", "exit_page", "source", "channel", "referrer", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "country", "region", "city", "browser", "browser_version", "os", "os_version", "device", "screen", "page", "host", "event_name", "lcp_target", "inp_target", "inp_type", "cls_target", "error_group", "error_type", "release" ], "description": "`error_group` is an error's group, its type and normalized message (`TypeError: Cannot read properties of undefined (reading 'map')`), and `error_type` and `release` its type and release; all three are empty on other events. `lcp_target`, `inp_target` and `cls_target` are the CSS selectors of the element a Web Vitals report attributes its LCP, its INP interaction and its largest layout shift to, and `inp_type` that interaction's kind (`pointer`, `keyboard`); empty on other events. A page load reports again whenever it is hidden with something new measured, and only its latest report counts." }, "QueryRequest": { "type": "object", "required": [ "range", "metrics" ], "additionalProperties": false, "properties": { "range": { "description": "`today`, `yesterday`, `{N}d` (the last N local days, today included), `{N}mo` (the last N calendar months, this one to date), `all` (from the site's first day), or local dates, inclusive.", "oneOf": [ { "type": "string", "pattern": "^(today|yesterday|all|[1-9][0-9]*d|[1-9][0-9]*mo)$" }, { "type": "object", "required": [ "from", "to" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } ] }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" }, "minItems": 1, "uniqueItems": true }, "interval": { "type": [ "string", "null" ], "enum": [ "hour", "day", "week", "month", null ], "description": "Adds `series`, at most 1,000 buckets (an hour counts 25 a day)." }, "breakdown": { "type": [ "object", "null" ], "required": [ "dimension" ], "additionalProperties": false, "properties": { "dimension": { "oneOf": [ { "$ref": "#/components/schemas/Dimension" }, { "$ref": "#/components/schemas/Property" }, { "const": "goal" }, { "const": "route" } ], "description": "`goal`: a row per goal, holding the goal metrics. `route`: pages grouped into the site's route templates, as `/decisions/*`; rows hold only the metrics that add up across pages (no visits, bounce rate, visit duration or goal metrics). `prop.{key}`: a row per value of the property; events without it are in the totals and in no row." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 }, "offset": { "type": "integer", "minimum": 0, "default": 0 }, "order": { "$ref": "#/components/schemas/Metric", "description": "A requested metric; the first by default." }, "direction": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } } }, "filters": { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "type": "null" } ] }, "goal": { "type": [ "string", "null" ], "description": "A goal name, for the goal metrics." }, "compare": { "type": [ "string", "null" ], "enum": [ "previous", "year", null ] }, "include_bots": { "type": [ "boolean", "null" ], "default": false }, "explain": { "type": [ "boolean", "null" ], "default": false } } }, "Property": { "type": "string", "pattern": "^prop\\..+$", "description": "An event property, `prop.{key}`, with a key of 1 to 64 bytes: event-scoped, like `page`. The schema's `events` list each event's keys. A query reading only `event_name` and one property, with metrics that add up across events (no visits, bounce rate, visit duration or goal metrics), is answered from rollups; any other is scanned." }, "Filter": { "description": "A predicate on events: a condition, or `and` / `or` over filters, or `not` one. 32 conditions, nesting depth 8, 100 values per `is`, patterns up to 1 KiB.", "oneOf": [ { "$ref": "#/components/schemas/Condition" }, { "type": "object", "required": [ "and" ], "additionalProperties": false, "properties": { "and": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Filter" } } } }, { "type": "object", "required": [ "or" ], "additionalProperties": false, "properties": { "or": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Filter" } } } }, { "type": "object", "required": [ "not" ], "additionalProperties": false, "properties": { "not": { "$ref": "#/components/schemas/Filter" } } } ] }, "Condition": { "type": "object", "required": [ "dimension", "op", "value" ], "additionalProperties": false, "properties": { "dimension": { "oneOf": [ { "$ref": "#/components/schemas/Dimension" }, { "$ref": "#/components/schemas/Property" }, { "const": "route" } ], "description": "`prop.{key}`: the event's property, empty for an event without it, a number in its shortest form (`2`, `0.5`). `route`: the page's route template, as `/decisions/*`. A site's routes are learned from every page it has had: a segment that takes more than 20 values under one prefix (200 for the first segment) is a parameter, `*`. They are the same in any range, and grow coarser, never finer, as pages are added." }, "op": { "type": "string", "enum": [ "is", "contains", "glob", "regex" ] }, "value": { "description": "A list of 1 to 100 values for `is` (any of), a string otherwise.", "oneOf": [ { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100 }, { "type": "string", "maxLength": 1024 } ] } } }, "Figures": { "type": "object", "description": "The requested metrics' values, in request order: a number, or `null` for no value (a bucket before the site's first day or after `as_of`, a ratio over zero). `error` holds each estimate's relative error: the standard error of a dense visitor count, the bound on a vital's percentile.", "properties": { "error": { "$ref": "#/components/schemas/Errors" } }, "additionalProperties": { "type": [ "number", "null" ] } }, "Errors": { "type": "object", "additionalProperties": { "type": "number" } }, "Bucket": { "type": "object", "required": [ "start" ], "properties": { "start": { "type": "string", "description": "A local date, or for `hour` a local time with its offset." }, "partial": { "type": "boolean", "description": "The bucket holds `as_of`." }, "error": { "$ref": "#/components/schemas/Errors" } }, "additionalProperties": { "type": [ "number", "null" ] } }, "DateRange": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "Row": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" }, "error": { "$ref": "#/components/schemas/Errors" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/Bucket" } }, "compare": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Errors" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/Bucket" } } }, "additionalProperties": { "type": [ "number", "null" ] } } }, "additionalProperties": { "type": [ "number", "null" ] } }, "QueryResponse": { "type": "object", "required": [ "range", "totals", "meta" ], "additionalProperties": false, "properties": { "range": { "$ref": "#/components/schemas/DateRange" }, "totals": { "$ref": "#/components/schemas/Figures" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/Bucket" } }, "breakdown": { "type": "object", "required": [ "dimension", "values", "rows" ], "additionalProperties": false, "properties": { "dimension": { "type": "string" }, "values": { "type": "integer", "description": "The distinct values in the range." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/Row" } } } }, "compare": { "type": "object", "required": [ "range", "totals" ], "additionalProperties": false, "properties": { "range": { "$ref": "#/components/schemas/DateRange" }, "totals": { "$ref": "#/components/schemas/Figures" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/Bucket" } } } }, "meta": { "type": "object", "required": [ "query_id", "as_of" ], "additionalProperties": false, "properties": { "query_id": { "type": "string", "pattern": "^q_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Cites the query in the query log." }, "as_of": { "type": "string", "format": "date-time", "description": "The snapshot's time." }, "explain": { "type": "object", "required": [ "query", "plan", "inputs" ], "additionalProperties": false, "properties": { "query": { "type": "object", "description": "The normalized query: range resolved, defaults filled, goals expanded." }, "plan": { "type": "array", "items": { "type": "object", "required": [ "from", "to", "source" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "source": { "type": "string", "enum": [ "rollup", "scan" ] }, "reason": { "type": "string", "enum": [ "stale", "filter", "metric", "hour", "bots", "values" ], "description": "`values`: a property had more values that day than its rollup keeps (1,000 per event name)." } } } }, "inputs": { "type": "string", "description": "A digest of everything the answer depends on besides the query." } } } } } } }, "FunnelStep": { "description": "One event: `page`, a pageview of a matching path; `event_name`, a custom or revenue event of a matching name (the automatic hits' names never match), with `where` filtering its properties; `goal`, the site's goal as a step of its kind. Globs: only `*` is special, matching any run of characters including `/`.", "type": "object", "additionalProperties": false, "properties": { "page": { "type": "string", "maxLength": 1024 }, "event_name": { "type": "string", "maxLength": 1024 }, "goal": { "type": "string" }, "where": { "$ref": "#/components/schemas/Filter", "description": "`prop.{key}` conditions only, on an `event_name` step." } }, "oneOf": [ { "required": [ "page" ] }, { "required": [ "event_name" ] }, { "required": [ "goal" ] } ] }, "FunnelRequest": { "type": "object", "required": [ "range", "steps" ], "additionalProperties": false, "properties": { "range": { "description": "`today`, `yesterday`, `{N}d` (the last N local days, today included), `{N}mo` (the last N calendar months, this one to date), `all` (from the site's first day), or local dates, inclusive.", "oneOf": [ { "type": "string", "pattern": "^(today|yesterday|all|[1-9][0-9]*d|[1-9][0-9]*mo)$" }, { "type": "object", "required": [ "from", "to" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } ] }, "steps": { "type": "array", "minItems": 2, "maxItems": 8, "items": { "$ref": "#/components/schemas/FunnelStep" } }, "window": { "type": "string", "pattern": "^[1-9][0-9]*[mhd]$", "default": "7d", "description": "How long after the first step's event the last may come: `{N}m`, `{N}h` or `{N}d`, from `1m` to `90d`." }, "breakdown": { "type": [ "object", "null" ], "required": [ "dimension" ], "additionalProperties": false, "properties": { "dimension": { "oneOf": [ { "$ref": "#/components/schemas/Dimension" }, { "$ref": "#/components/schemas/Property" } ], "description": "Rows by the first step's event's value (its session's, for a session-scoped dimension). A person who entered with several values is in each row; an event without the property is in no row. Rows are ordered by entrants." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 } } }, "filters": { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "type": "null" } ], "description": "A predicate on events: an event that doesn't match is no step." }, "include_bots": { "type": [ "boolean", "null" ], "default": false }, "explain": { "type": [ "boolean", "null" ], "default": false } } }, "FunnelSteps": { "type": "array", "items": { "type": "object", "required": [ "persons", "conversion_rate", "from_previous", "median_ms" ], "additionalProperties": false, "properties": { "persons": { "type": "integer", "minimum": 0, "description": "Persons reaching the step, exact: a visitor ID, an anonymous one an `identify` in the range paired with a user counted as that user. Not the Query API's `visitors` (an estimate, by visitor ID)." }, "conversion_rate": { "type": [ "number", "null" ], "description": "Of the first step's persons, 0 to 1; `null` when none entered." }, "from_previous": { "type": [ "number", "null" ], "description": "Of the previous step's persons, 0 to 1; `null` for the first step or when the previous had none." }, "median_ms": { "type": [ "integer", "null" ], "description": "The median time from the first step to this one, in milliseconds, over the persons reaching it: from the start of the chain that first reached it to the event that did. `null` for the first step and for a step nobody reached." } } } }, "FunnelResponse": { "type": "object", "required": [ "range", "window", "steps", "meta" ], "additionalProperties": false, "properties": { "range": { "$ref": "#/components/schemas/DateRange" }, "window": { "type": "string" }, "steps": { "$ref": "#/components/schemas/FunnelSteps" }, "breakdown": { "type": "object", "required": [ "dimension", "values", "rows" ], "additionalProperties": false, "properties": { "dimension": { "type": "string" }, "values": { "type": "integer", "description": "The values the first step was entered with." }, "rows": { "type": "array", "items": { "type": "object", "required": [ "value", "steps" ], "additionalProperties": false, "properties": { "value": { "type": "string" }, "steps": { "$ref": "#/components/schemas/FunnelSteps" } } } } } }, "meta": { "type": "object", "required": [ "query_id", "as_of" ], "additionalProperties": false, "properties": { "query_id": { "type": "string", "pattern": "^q_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Cites the funnel in the query log." }, "as_of": { "type": "string", "format": "date-time", "description": "The snapshot's time." }, "explain": { "type": "object", "required": [ "query", "plan", "inputs" ], "additionalProperties": false, "properties": { "query": { "type": "object", "description": "The normalized funnel: range resolved, defaults filled, goal steps expanded." }, "plan": { "type": "array", "items": { "type": "object", "required": [ "from", "to", "source", "reason" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "source": { "const": "scan" }, "reason": { "const": "funnel" } } } }, "inputs": { "type": "string", "description": "A digest of everything the answer depends on besides the funnel." } } } } } } }, "PathsRequest": { "type": "object", "required": [ "range", "at" ], "additionalProperties": false, "properties": { "range": { "description": "`today`, `yesterday`, `{N}d` (the last N local days, today included), `{N}mo` (the last N calendar months, this one to date), `all` (from the site's first day), or local dates, inclusive.", "oneOf": [ { "type": "string", "pattern": "^(today|yesterday|all|[1-9][0-9]*d|[1-9][0-9]*mo)$" }, { "type": "object", "required": [ "from", "to" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } } ] }, "at": { "$ref": "#/components/schemas/FunnelStep", "description": "The step the paths start from, in funnels' grammar." }, "direction": { "type": [ "string", "null" ], "enum": [ "after", "before", null ], "default": "after", "description": "`after`: where people went next; `before`: how they arrived, nearest step first." }, "depth": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5, "default": 3, "description": "How many steps from `at`." }, "window": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]*[mhd]$", "default": "30m", "description": "How far from the entry every step may be: `{N}m`, `{N}h` or `{N}d`, from `1m` to `90d`. An event exactly at the edge counts." }, "limit": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 20, "default": 6, "description": "The nodes each step keeps before `other`, and the whole paths listed." }, "filters": { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "type": "null" } ], "description": "A predicate on events: an event that doesn't match is no step and no entry." }, "include_bots": { "type": [ "boolean", "null" ], "default": false }, "explain": { "type": [ "boolean", "null" ], "default": false } } }, "PathNode": { "description": "One step's node and its persons: `page` (a route), `event_name`, or `other`, the nodes past `limit` folded into one.", "type": "object", "required": [ "persons" ], "additionalProperties": false, "properties": { "page": { "type": "string", "description": "A pageview's node: the page's route, `*` for each segment that varies. As a funnel step's glob it also matches deeper pages." }, "event_name": { "type": "string", "description": "A custom or revenue event's node: its name." }, "other": { "type": "integer", "minimum": 1, "description": "How many nodes it folds." }, "persons": { "type": "integer", "minimum": 1 } }, "oneOf": [ { "required": [ "page" ] }, { "required": [ "event_name" ] }, { "required": [ "other" ] } ] }, "PathsResponse": { "type": "object", "required": [ "range", "at", "direction", "window", "depth", "persons", "steps", "links", "paths", "meta" ], "additionalProperties": false, "properties": { "range": { "$ref": "#/components/schemas/DateRange" }, "at": { "type": "object", "description": "`at`, normalized: a goal expanded to its rule." }, "direction": { "enum": [ "after", "before" ] }, "window": { "type": "string" }, "depth": { "type": "integer" }, "persons": { "type": "integer", "minimum": 0, "description": "The persons who entered at `at`, exact. Not the Query API's `visitors` (an estimate, by visitor ID)." }, "steps": { "type": "array", "description": "`steps[k]` is the step k + 1 away from `at` (earlier, for `before`); always `depth` of them.", "items": { "type": "object", "required": [ "persons", "nodes" ], "additionalProperties": false, "properties": { "persons": { "type": "integer", "minimum": 0, "description": "The persons who took at least this many steps: the nodes' sum." }, "nodes": { "type": "array", "description": "By persons, ties by node (pages first, then bytewise); `other` last.", "items": { "$ref": "#/components/schemas/PathNode" } } } } }, "links": { "type": "array", "description": "Persons from one step's node to the next's. Who ended at a node is its persons minus its links out.", "items": { "type": "object", "required": [ "step", "from", "to", "persons" ], "additionalProperties": false, "properties": { "step": { "type": "integer", "minimum": 1, "description": "The step the link goes to." }, "from": { "type": "integer", "minimum": 0, "description": "Index into the nodes of the step nearer `at`; 0, `at` itself, for step 1." }, "to": { "type": "integer", "minimum": 0, "description": "Index into `steps[step - 1].nodes`." }, "persons": { "type": "integer", "minimum": 1 } } } }, "paths": { "type": "array", "description": "The most common exact whole paths, at most `limit`, never with `other`: `[A, B]` counts those who stopped after B. Ties go by the sequence.", "items": { "type": "object", "required": [ "steps", "persons" ], "additionalProperties": false, "properties": { "steps": { "type": "array", "minItems": 1, "description": "In time order: a funnel's steps after `at` (`after`) or before it (`before`).", "items": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "string", "description": "A pageview's node: the page's route, `*` for each segment that varies. As a funnel step's glob it also matches deeper pages." }, "event_name": { "type": "string", "description": "A custom or revenue event's node: its name." } }, "oneOf": [ { "required": [ "page" ] }, { "required": [ "event_name" ] } ] } }, "persons": { "type": "integer", "minimum": 1 } } } }, "meta": { "type": "object", "required": [ "query_id", "as_of" ], "additionalProperties": false, "properties": { "query_id": { "type": "string", "pattern": "^q_[0-9A-HJKMNP-TV-Z]{26}$", "description": "Cites the paths in the query log." }, "as_of": { "type": "string", "format": "date-time", "description": "The snapshot's time." }, "explain": { "type": "object", "required": [ "query", "plan", "inputs" ], "additionalProperties": false, "properties": { "query": { "type": "object", "description": "The normalized request: range resolved, defaults filled, a goal `at` expanded." }, "plan": { "type": "array", "items": { "type": "object", "required": [ "from", "to", "source", "reason" ], "additionalProperties": false, "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "source": { "const": "scan" }, "reason": { "const": "paths" } } } }, "inputs": { "type": "string", "description": "A digest of everything the answer depends on besides the request, the site's routes included." } } } } } } }, "Health": { "type": "object", "required": [ "window_minutes", "rejected" ], "additionalProperties": false, "properties": { "window_minutes": { "type": "integer", "description": "The window counted, in minutes." }, "rejected": { "type": "array", "description": "One row per reason, most recent first.", "items": { "type": "object", "required": [ "site", "code", "count", "last_at" ], "additionalProperties": false, "properties": { "site": { "type": "integer" }, "code": { "type": "string", "description": "Why: host_not_allowed, too_old, bad_url, bad_event_id, bad_visitor_id, missing_field, malformed, unknown_kind, bad_prop, over_limit, …" }, "count": { "type": "integer" }, "last_at": { "type": "integer", "description": "The latest, in unix milliseconds." }, "sample": { "type": "string", "description": "For host_not_allowed: the host the hits came from." } } } } } }, "Schema": { "type": "object", "required": [ "timezone", "currency", "first_day", "today", "has_revenue", "has_vitals", "has_errors", "has_replays", "dimensions", "metrics", "goals", "events", "meta" ], "additionalProperties": false, "properties": { "timezone": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "first_day": { "type": [ "string", "null" ], "format": "date" }, "today": { "type": "string", "format": "date" }, "has_revenue": { "type": "boolean" }, "has_vitals": { "type": "boolean", "description": "Whether any Web Vitals arrived in the 28 days: the tracker's `wv` add-on is on." }, "has_errors": { "type": "boolean", "description": "Whether any errors arrived in the 28 days: the tracker's `errors` add-on is on, or a server sends them." }, "has_replays": { "type": "boolean", "description": "Whether any session in the 28 days was recorded: the tracker's `replay` add-on is on." }, "dimensions": { "type": "array", "items": { "type": "object", "required": [ "name", "class", "values" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "class": { "type": "string", "enum": [ "session", "event" ] }, "values": { "type": "integer" } } } }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } }, "goals": { "type": "array", "items": { "type": "object", "required": [ "name", "match" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "match": { "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": false, "properties": { "event_name": { "type": "string" }, "page": { "type": "string" } } } } } }, "events": { "type": "array", "items": { "type": "object", "required": [ "name", "count", "props" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "count": { "type": "integer" }, "props": { "type": "array", "items": { "type": "object", "required": [ "key", "values" ], "additionalProperties": false, "properties": { "key": { "type": "string", "description": "Query it as `prop.{key}`." }, "values": { "type": [ "integer", "null" ], "description": "Distinct values in the 28 days; `null` when the key had more than 1,000 on a day: too many to count, and breakdowns by it scan." } } } } } } }, "meta": { "type": "object", "required": [ "as_of" ], "additionalProperties": false, "properties": { "as_of": { "type": "string", "format": "date-time" } } } } }, "LiveVisitors": { "type": "object", "required": [ "current", "minutes", "as_of" ], "properties": { "current": { "type": "integer", "description": "Visitors with an event in the last 5 minutes." }, "minutes": { "type": "array", "items": { "type": "integer" }, "description": "Visitors per minute, the last 30, oldest first; the last is partial." }, "as_of": { "type": "string", "format": "date-time" } } }, "LiveHit": { "type": "object", "required": [ "ts", "kind", "name", "page", "source", "country", "device" ], "properties": { "ts": { "type": "string", "format": "date-time" }, "kind": { "type": "string" }, "name": { "type": "string" }, "page": { "type": "string" }, "source": { "type": "string" }, "country": { "type": "string" }, "device": { "type": "string" } } } } } } ```