Query API
Every view in the dashboard is built on the public Query API, and you can send the same queries from your own code. This page covers queries, funnels, paths, errors and recordings.
Authorization
Send a site's secret key as a bearer token with every request:
curl -s https://api.nanolytics.dev/v1/sites/42/query \
-H "Authorization: Bearer $NANOLYTICS_KEY" \
-H 'content-type: application/json' \
-d '{"range":"28d","metrics":["visitors","pageviews"]}'- Create a key in Settings → API keys, or with the MCP tool
create_key. Each key works for one site only. - You'll find the site's ID in the dashboard's URL, or you can get it from
list_sitesover MCP. - The full spec, with every field, metric and dimension, is at https://api.nanolytics.dev/v1/openapi.json.
Schema
GET https://api.nanolytics.dev/v1/sites/{site}/schema tells you what you can ask about a site: its first day of data and today's date, the dimensions with their cardinalities, the metrics, its goals, and its event names with each one's property keys. It also tells you whether page speed, error and replay data has arrived in the last 28 days (has_vitals, has_errors, has_replays).
Query
POST https://api.nanolytics.dev/v1/sites/{site}/query. A query needs a range and at least one metric. You can also add an interval, a breakdown, filters, a goal and a comparison.
Metrics
Each vital also comes with _p95, _samples, _good and _poor, where the last two are the share of reports in Google's good and poor bands. Metrics explains how each one is calculated.
Dimensions
- Pages:
page,entry_page,exit_page,host, androute, which groups pages into templates such as/blog/*. - Acquisition:
source,channel,referrer,utm_source,utm_medium,utm_campaign,utm_term,utm_content. - Location:
country,region,city. - Device:
browser,browser_version,os,os_version,device,screen. - Events:
event_name, andprop.{key}for an event property. - Errors:
error_group,error_type,release. - Page speed:
lcp_target,inp_target,cls_target(the element responsible for the measurement),inp_type. - Goals: breaking down by
goalgives you one row per goal.
Filters
A condition combines a dimension, an operator and a value:
{ "dimension": "country", "op": "is", "value": ["DE", "AT"] }opcan beis(matching any of 1 to 100 values),contains,globorregex.- Combine conditions with
{"and": [...]},{"or": [...]}and{"not": ...}, up to 32 conditions nested up to 8 levels deep. prop.{key}filters on an event property. Events without that property have an empty value.
Response
totals: each metric, in the order you requested them.nullmeans there's no value, such as a ratio over zero.series: one bucket per interval.partialmarks the bucket that containsas_of.breakdown:rows, each with itsvalueand metrics, andvalues, the number of distinct values in the range.compare: the same fields for the comparison range.error: the relative error of each estimated figure (estimated visitor counts and vitals percentiles).meta.query_ididentifies the query so you can cite it, andmeta.as_ofis the time of the data it read.
Explain
With "explain": true, meta.explain contains the query as it was run (with the range resolved, defaults filled in and goals expanded) and the plan. For each run of days, the plan shows whether the data came from rollups or a scan, and why a scan was needed (filter, metric, hour, bots, values or stale).
Validation errors
If the engine can't answer a query, it rejects it rather than returning an approximation. The response is {"error": {"code", "message", "path"}}, where path points to the field that caused it, such as filters.and[0].value.
Examples
28 days by day and channel, Germany off mobile, against the period before:
{
"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:
{
"range": "7d",
"metrics": [
"visitors",
"pageviews"
],
"breakdown": {
"dimension": "page",
"limit": 10
}
}Visitors, bounce rate and visit duration by day over the last 30 days:
{
"range": "30d",
"metrics": [
"visitors",
"bounce_rate",
"visit_duration"
],
"interval": "day"
}Where visitors came from this month, against the same month last year:
{
"range": "1mo",
"metrics": [
"visitors"
],
"breakdown": {
"dimension": "source",
"limit": 10
},
"compare": "year"
}A goal's completions, converters and conversion rate by channel over 28 days:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"range": "all",
"metrics": [
"visitors"
],
"explain": true
}Funnels
POST https://api.nanolytics.dev/v1/sites/{site}/funnel shows how many of the visitors who did the first step went on to do each following step, in order, within a time window from the first.
steps: 2 to 8. A step is{"page": glob},{"event_name": glob, "where": filter}or{"goal": name}. In a glob,*matches any run of characters, including/.window: from1mto90d,7dby default. Each later step must come strictly after the one before it; a step exactly at the edge of the window still counts.breakdown: splits the funnel by the first step's value of a dimension orprop.{key}.filters,include_botsandexplainwork the same as in a query.
For each step, the response includes persons, conversion_rate (relative to the first step), from_previous, and median_ms, the median time since the first step. persons are exact counts of people: a visitor who signs in between steps (with identify) is still one person. This differs from the Query API's visitors, which is an estimate.
Of visitors who viewed /pricing in the last 28 days, how many signed up within a day, and how soon:
{
"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:
{
"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:
{
"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 shows where people went after a given step, or how they got to it.
at: the starting step, defined the same way as a funnel step.direction:after(the default) orbefore.depth: 1 to 5 steps, 3 by default.window: how long after the starting step each step can happen, 30 minutes by default.limit: how many nodes to keep at each step before grouping the rest intoother, 6 by default.
Steps are pageviews (by route) and custom events (by name). A step that repeats the one before it isn't counted as a new step. The response includes the number of persons who reached the starting step, the steps with their nodes, the links between adjacent steps, and paths, the most common complete paths in time order. Each node is a valid funnel step, so you can paste a path's steps straight into a funnel.
Where people went in the 30 minutes after /pricing, three steps deep:
{
"range": "28d",
"at": {
"page": "/pricing"
}
}How people arrived at the signup goal within a day, two steps back, off mobile:
{
"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:
{
"range": "7d",
"at": {
"page": "/*"
},
"depth": 1,
"limit": 3,
"explain": true
}Errors
GET https://api.nanolytics.dev/v1/sites/{site}/errors/{group}?range=28d returns one error group's call sites, releases and latest occurrences.
groupis anerror_groupvalue from a query, URL-encoded.rangeworks as in the Query API, or you can passfromandtoas dates. The default is28d.- Call sites are the top frame on your site's own host for each occurrence, ranked by occurrences, from the latest 1,000 (
completetells you whether that covers all of them). - The latest 10 occurrences include their page, browser, release, original message and stack frames.
To list the groups themselves, run a query for errors, visitors, first and last broken down by error_group. See Error tracking.
Recordings
GET https://api.nanolytics.dev/v1/sites/{site}/recordings?range=7dlists recorded sessions, newest first, each with its start time, duration, entry page, pages, browser, country, error occurrences and recordings.limitis 50 by default. To get the next page, pass the response'snext_beforeasbefore.filterstakes a query filter as JSON and returns sessions where any event matches.GET https://api.nanolytics.dev/v1/sites/{site}/recordings/{id}/session?date=YYYY-MM-DDreturns the session a recording belongs to, with its events in order (up to 1,000), each timed from the start of the session.GET https://api.nanolytics.dev/v1/sites/{site}/recordings/{id}?date=YYYY-MM-DDreturns one recording's chunks (rrweb events, gzipped and base64-encoded), along with its gaps and stylesheets.
See Session replay.
Health
GET https://api.nanolytics.dev/v1/sites/{site}/health lists the events dropped for the site in the last 15 minutes, by reason, with the last time each happened. The collection endpoint returns 202 even for events it drops, so this is where you'll see them. An event from a host the site doesn't allow, such as a dev server, appears as host_not_allowed along with the host it came from.
Server-side events
POST https://api.nanolytics.dev/v1/events accepts events from your servers, using the same secret key. See Custom events.