Skip to content

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_sites over 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.

FieldAccepts
rangetoday, yesterday, {N}d (the last N days, including today), {N}mo (the last N calendar months, with this one to date), all, or {"from":"YYYY-MM-DD","to":"YYYY-MM-DD"}. Days follow the site's timezone.
metricsOne or more of the metrics below.
intervalhour, day, week or month. Adds a series, up to 1,000 buckets.
breakdown{"dimension": …, "limit": 10, "offset": 0, "order": …, "direction": "desc"}. Returns one row per value.
filtersA condition, or and, or and not over filters.
goalA goal's name, for the goal metrics.
compareprevious (the same number of days just before) or year (364 days before, so weekdays line up). Not allowed with all.
include_botsfalse by default.
explaintrue adds the normalized query and the plan.

Metrics

MetricCounts
visitors, visits, pageviews, eventsPeople, sessions, pageviews and events
bounce_rate, visit_durationThe share of sessions with one pageview and no custom event; the average session length in ms
completions, converters, conversion_rateA goal's completions, the visitors who completed it, and their share
errors, first, lastError occurrences; the first and last matching event, in epoch ms
replaysRecorded sessions
lcp_p75, inp_p75, cls_p75, fcp_p75, ttfb_p75Core Web Vitals at the 75th percentile, in ms (CLS is a score)

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, and route, 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, and prop.{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 goal gives you one row per goal.

Filters

A condition combines a dimension, an operator and a value:

{ "dimension": "country", "op": "is", "value": ["DE", "AT"] }
  • op can be is (matching any of 1 to 100 values), contains, glob or regex.
  • 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. null means there's no value, such as a ratio over zero.
  • series: one bucket per interval. partial marks the bucket that contains as_of.
  • breakdown: rows, each with its value and metrics, and values, 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_id identifies the query so you can cite it, and meta.as_of is 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: from 1m to 90d, 7d by 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 or prop.{key}.
  • filters, include_bots and explain work 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) or before.
  • 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 into other, 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.

  • group is an error_group value from a query, URL-encoded.
  • range works as in the Query API, or you can pass from and to as dates. The default is 28d.
  • Call sites are the top frame on your site's own host for each occurrence, ranked by occurrences, from the latest 1,000 (complete tells 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=7d lists recorded sessions, newest first, each with its start time, duration, entry page, pages, browser, country, error occurrences and recordings. limit is 50 by default. To get the next page, pass the response's next_before as before. filters takes 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-DD returns 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-DD returns 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.