{
  "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" }
        }
      }
    }
  }
}
