# 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:

```sh
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](/docs/mcp).
- The full spec, with every field, metric and dimension, is at [https://api.nanolytics.dev/v1/openapi.json](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.

| Field | Accepts |
|---|---|
| `range` | `today`, `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. |
| `metrics` | One or more of the metrics below. |
| `interval` | `hour`, `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. |
| `filters` | A condition, or `and`, `or` and `not` over filters. |
| `goal` | A goal's name, for the goal metrics. |
| `compare` | `previous` (the same number of days just before) or `year` (364 days before, so weekdays line up). Not allowed with `all`. |
| `include_bots` | `false` by default. |
| `explain` | `true` adds the normalized query and the plan. |

### Metrics

| Metric | Counts |
|---|---|
| `visitors`, `visits`, `pageviews`, `events` | People, sessions, pageviews and events |
| `bounce_rate`, `visit_duration` | The share of sessions with one pageview and no custom event; the average session length in ms |
| `completions`, `converters`, `conversion_rate` | A goal's completions, the visitors who completed it, and their share |
| `errors`, `first`, `last` | Error occurrences; the first and last matching event, in epoch ms |
| `replays` | Recorded sessions |
| `lcp_p75`, `inp_p75`, `cls_p75`, `fcp_p75`, `ttfb_p75` | Core 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](/docs/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:

```json
{ "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:

```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
}
```

## 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:

```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` 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:

```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
}
```

## 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](/docs/errors).

## 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](/docs/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](/docs/events).
