# analytics-api Specification

## Purpose
Usage analytics of the deployment read from the rollup collections: dense time series, breakdowns, KPI
summary and CSV export, with the source collection chosen by granularity and every query backed by the
`{ scope, bucket }` index.

## Requirements

### Requirement: Series endpoint

Edition: CE. `GET /api/v1/analytics/series` SHALL accept `metrics` (comma-separated, at least one), `from`, `to`,
`tz`, `granularity` and `scope` (default `global`) and answer the time-series envelope extended with `scope`, one
series per requested metric named as the metric, where `egressEnded` expands into one series per stored end status
named `egressEnded.<status>` (`egressEnded.complete`). Unknown metrics, duplicated metrics and a malformed `scope`
SHALL be rejected with `400`.

#### Scenario: Default request

- **GIVEN** the current time is 2026-10-13T12:00:00Z
- **WHEN** the client requests `GET /api/v1/analytics/series?metrics=roomsCreated,bytesUp`
- **THEN** the response is `200` with `scope: "global"`, `granularity: "5m"`, `from: "2026-10-12T12:00:00.000Z"`,
  `to: "2026-10-13T12:00:00.000Z"` and two series `roomsCreated` and `bytesUp` of 288 points each

#### Scenario: Egress end statuses

- **GIVEN** egresses that ended as `complete` and `failed` in the range (`EGRESS_COMPLETE` and `EGRESS_FAILED` in the
  LiveKit events)
- **WHEN** the client requests `metrics=egressEnded`
- **THEN** the response has the series `egressEnded.complete` and `egressEnded.failed` and no series for statuses
  absent from the range

#### Scenario: Unknown metric

- **WHEN** the client requests `metrics=roomsCreated,roomsDeleted`
- **THEN** the response is `400` with code `VALIDATION_ERROR` and `details.issues[0].path` equal to `["metrics"]`

### Requirement: Metric catalogue and fill values

Edition: CE. The CE metrics SHALL be the eighteen of the "CE metrics" scenario; counters and sums fill empty buckets with
`0`, rates and averages with `null`. Participant figures count STANDARD sessions only, except the `kind` breakdown.
`ingressSessions` SHALL sum the rollups' `ingress.sessionsStarted` and `ingressDurationMs` their `ingress.durationMs`.

#### Scenario: Connection success rate

- **GIVEN** a bucket with `participants.joined: 40` and `participants.active: 38` and an empty bucket
- **WHEN** `metrics=connectionSuccessRate` is requested
- **THEN** the first point is `95.0` (percentage with one decimal) and the empty bucket holds `null`

#### Scenario: Participant minutes

- **GIVEN** a bucket with `participants.minutes: 1234`
- **WHEN** `metrics=participantMinutes` is requested
- **THEN** the point is `1234` and empty buckets hold `0`

#### Scenario: Services are not participants

- **GIVEN** an hour in which 40 STANDARD and 6 EGRESS participants joined
- **WHEN** `metrics=participantsJoined` and the breakdown `dimensions=kind` are requested
- **THEN** the series point is `40` and the breakdown has `STANDARD: 40` and `EGRESS: 6`

#### Scenario: Ingress metrics on CE

- **GIVEN** a valid token on the CE dashboard and one hour of the last 24 h whose hourly document has
  `ingress.sessionsStarted: 3` and `ingress.durationMs: 5400000`
- **WHEN** the client requests `metrics=ingressSessions,ingressDurationMs&granularity=1h`
- **THEN** the response is `200` with the series `ingressSessions` and `ingressDurationMs` of 24 points, that hour
  holds `3` and `5400000` and the other hours hold `0`

#### Scenario: CE metrics

- **WHEN** a CE client requests analytics series
- **THEN** the metrics it can request are `roomsCreated`, `roomsEnded`, `participantsJoined`, `participantsActive`,
  `participantsAborted`, `connectionSuccessRate`, `uniqueIdentities`, `participantMinutes`, `tracksPublished`,
  `egressStarted`, `egressEnded`, `egressDurationMs`, `ingressSessions`, `ingressDurationMs`, `bytesUp`, `bytesDown`,
  `apiCalls` and `apiErrors`

### Requirement: Granularity and source collection

Edition: CE. Analytics series SHALL accept `granularity` `auto`, `5m`, `15m`, `1h`, `6h` and `1d`, reject `1m`,
read `analytics_5min` for `5m` and `15m`, `analytics_hourly` for `1h` and `6h` and `analytics_daily` for `1d`, and
SHALL never read entity or stats collections. Sub-hour values SHALL require a range of at most 24 h whose `from` is
inside the 5-minute rollup retention. `auto` SHALL resolve to `5m` (≤ 24 h inside that retention), `1h` (≤ 7 d), `6h`
(≤ 90 d), otherwise `1d`.

#### Scenario: Automatic resolution by range

- **WHEN** series are requested with `granularity=auto` for ranges of 24 h, 7 d, 30 d and 100 d
- **THEN** the responses use `5m`, `1h`, `6h` and `1d` and the integration test observes reads of `analytics_5min`,
  `analytics_hourly`, `analytics_hourly` and `analytics_daily` respectively

#### Scenario: Sub-hour granularity on a long range

- **WHEN** the client requests `granularity=5m` with `from=now-48h`
- **THEN** the response is `400` with code `VALIDATION_ERROR` and a message stating that `5m` and `15m` require a range
  of at most 24 hours

#### Scenario: Day-old range beyond the stats retention

- **GIVEN** the stats and 5-minute rollup retentions are 7 d
- **WHEN** the client requests `granularity=auto` for a 24 h range that ended 30 days ago
- **THEN** the response uses `granularity: "1h"` read from `analytics_hourly`, and an explicit `granularity=5m` for
  the same range is rejected with `400` stating "5m and 15m require a range inside the 5-minute rollup retention
  (7 days)"

#### Scenario: 5-minute rollups kept apart from the stats

- **GIVEN** a stats retention of 7 d and a 5-minute rollup retention of 2 d
- **WHEN** the client requests `granularity=auto` for a 24 h range that ended 3 days ago
- **THEN** the response uses `granularity: "1h"`

#### Scenario: Retention named in hours

- **GIVEN** a 5-minute rollup retention of 36 h
- **WHEN** the client requests `granularity=5m` for a 24 h range that ended 2 days ago
- **THEN** the response is `400` stating "5m and 15m require a range inside the 5-minute rollup retention (36 hours)"

#### Scenario: Minute granularity and the bucket cap

- **WHEN** the client requests `granularity=1m` for any range, or `granularity=1h` for a 60-day range
- **THEN** both responses are `400`, the first stating that the finest analytics granularity is `5m` and the second
  stating the 1 000-bucket limit

### Requirement: Hourly-only metrics

Edition: CE. `participantMinutes`, `tracksPublished`, `egressEnded`, `egressDurationMs`, `ingressSessions`,
`ingressDurationMs`, `apiCalls` and `apiErrors` SHALL be served only at `1h` or coarser; a request for any of them
with an explicit or resolved granularity below `1h` SHALL be rejected with `400` naming the metric and the
granularity.

#### Scenario: Hourly-only metric at five minutes

- **WHEN** the client requests `metrics=egressStarted,egressEnded` with `granularity=auto` over 24 h
- **THEN** the response is `400` with code `VALIDATION_ERROR` and a message stating that `egressEnded` requires a
  granularity of at least `1h`, and the same metrics with `granularity=1h` answer `200` with 24 points per series

### Requirement: Timezone-aware buckets

Edition: CE. `6h` and `1d` buckets SHALL start at local midnight boundaries of `tz`; in a zone other than `UTC`,
`1d` buckets SHALL be built by summing hourly documents per local day while the range is inside the hourly
retention and SHALL otherwise fall back to UTC-day documents. `uniqueIdentities` SHALL always be reported per UTC
day, marked `basis: "utcDay"` on the series.

#### Scenario: Daily buckets in New York

- **GIVEN** `tz=America/New_York` and `granularity=1d` over 7 days
- **WHEN** the series is requested
- **THEN** every `ts` is a local midnight serialised in UTC (`…T04:00:00.000Z` or `…T05:00:00.000Z`) and each point
  equals the sum of the 24 hourly documents of that local day (23 or 25 on a DST change day)

#### Scenario: Unique identities in Madrid

- **GIVEN** `tz=Europe/Madrid` and `granularity=1d`
- **WHEN** `metrics=uniqueIdentities,roomsCreated` is requested
- **THEN** the `uniqueIdentities` series carries `basis: "utcDay"` with `ts` at `…T00:00:00.000Z` and
  `roomsCreated` has no `basis` and `ts` at local midnight

### Requirement: Dense series and bucket aggregation

Edition: CE. Every series SHALL contain exactly one point per bucket from `from` floored to the bucket start up to
and including the bucket containing `to`; when a bucket spans several rollup documents, counters SHALL be summed and
`connectionSuccessRate` SHALL be computed from the summed numerators and denominators.

#### Scenario: Sparse documents in a day

- **GIVEN** `analytics_5min` holds documents for only three 5-minute buckets of the last 24 h
- **WHEN** `metrics=roomsCreated,connectionSuccessRate` is requested with `granularity=5m`
- **THEN** both series have 288 points, `roomsCreated` holds `0` outside the three buckets and
  `connectionSuccessRate` holds `null`

#### Scenario: Fifteen-minute rate from three documents

- **GIVEN** three consecutive 5-minute documents with `participants.active` 1, 2 and 0 and
  `participants.joined` 2, 2 and 1
- **WHEN** `granularity=15m` is requested with `metrics=connectionSuccessRate,participantsJoined`
- **THEN** the bucket holds `connectionSuccessRate: 60` (3 / 5, one decimal) and `participantsJoined: 5`

### Requirement: Unique identities only at daily granularity

Edition: CE. `uniqueIdentities` SHALL be served only with `granularity=1d`; requesting it with any other explicit
or resolved granularity SHALL be rejected with `400` naming the metric.

#### Scenario: Unique identities on a 24 h range

- **WHEN** the client requests `metrics=uniqueIdentities` with `granularity=auto` over 24 h
- **THEN** the response is `400` with code `VALIDATION_ERROR` and a message stating that `uniqueIdentities` requires
  `granularity=1d`

### Requirement: Breakdowns endpoint

Edition: CE. `GET /api/v1/analytics/breakdowns` SHALL accept `dimensions` (comma-separated, at least one), `from`,
`to`, `tz` and `scope` and answer `{ from, to, scope, breakdowns: [{ dimension, total, items: [{ key, count,
percent }] }] }` with items sorted by `count` descending, `percent` as one decimal of `total`, keys as stored
(protocol enums in `UPPER_SNAKE`, dashboard vocabularies in lower case) and an unknown dimension rejected with `400`.

#### Scenario: SDK breakdown

- **GIVEN** rollups in range with `participants.bySdk` summing to `js: 600`, `swift: 300`, `android: 100`
- **WHEN** `dimensions=sdk` is requested
- **THEN** the breakdown has `total: 1000` and items `js` 600 / 60.0, `swift` 300 / 30.0, `android` 100 / 10.0

#### Scenario: Dimension without data

- **GIVEN** no egress in the range
- **WHEN** `dimensions=egressType` is requested
- **THEN** the breakdown has `total: 0` and `items: []`

### Requirement: Breakdown and summary source and range snapping

Edition: CE. Breakdowns and the summary SHALL read `analytics_hourly` for ranges up to 90 days, snapping `from` down
and `to` up to whole hours, and `analytics_daily` beyond, snapping to whole UTC days; the response `from`/`to` SHALL
report the snapped range. Entity and stats collections SHALL never be read by these endpoints.

#### Scenario: One-hour preset

- **GIVEN** the current time is 12:40:00Z
- **WHEN** breakdowns are requested with `from=now-1h&to=now`
- **THEN** the response has `from: "…T11:00:00.000Z"`, `to: "…T13:00:00.000Z"` and the integration test observes two
  hourly documents read per scope

#### Scenario: Long range reads daily documents

- **WHEN** the summary is requested for the last 120 days
- **THEN** `analytics_daily` is read, `from` and `to` are UTC midnights and no hourly document is read

### Requirement: Summary endpoint

Edition: CE. `GET /api/v1/analytics/summary` SHALL accept `from`, `to`, `tz` and `scope` and answer the fifteen KPI
values of the "KPI keys" scenario, omitting any value the stored documents cannot derive. `ingressSessions` and
`ingressDurationMs` SHALL be the sums of `ingress.sessionsStarted` and `ingress.durationMs` over the snapped range, `0`
without ingress activity.

#### Scenario: Summary values

- **GIVEN** hourly documents in range summing to `rooms.created: 120`, `rooms.ended: 110`, `participants.joined:
  900`, `participants.active: 880`, `apiCalls.total: 5000`, `apiErrors.total: 50`
- **WHEN** the summary is requested
- **THEN** the body has `roomsCreated: 120`, `roomsEnded: 110`, `participantSessions: 900`,
  `connectionSuccessRate: 97.8`, `apiCalls: 5000` and `apiErrorRate: 1.0`

#### Scenario: Average room size and duration

- **GIVEN** hourly documents summing to `rooms.ended: 110`, `rooms.participantsSum: 440` and
  `rooms.durationMsSum: 39600000`
- **WHEN** the summary is requested
- **THEN** the body has `avgRoomSize: 4.0` and `avgRoomDurationMs: 360000`

#### Scenario: Writer without the room sums

- **GIVEN** hourly documents written by a writer that stores no `rooms.participantsSum`
- **WHEN** the summary is requested
- **THEN** `avgRoomSize` and `avgRoomDurationMs` are absent from the body and the other values are present

#### Scenario: Unique identities over several days

- **GIVEN** `analytics_daily` documents for the three UTC days overlapping the range with `uniqueIdentities` 100, 120
  and 90
- **WHEN** the summary is requested
- **THEN** the body has `uniqueIdentities: { value: 310, basis: "utcDays", days: 3 }`

#### Scenario: Ingress totals

- **GIVEN** a valid token on the CE dashboard and hourly documents in range summing to `ingress.sessionsStarted: 12`
  and `ingress.durationMs: 7200000`
- **WHEN** the summary is requested
- **THEN** the response is `200` with `ingressSessions: 12` and `ingressDurationMs: 7200000`

#### Scenario: No ingress in the range

- **GIVEN** hourly documents in range without `ingress` counters
- **WHEN** the summary is requested
- **THEN** the body has `ingressSessions: 0` and `ingressDurationMs: 0`

#### Scenario: KPI keys

- **WHEN** the client requests `GET /api/v1/analytics/summary` over a range whose stored documents derive every value
- **THEN** the response carries the KPI values `roomsCreated`, `roomsEnded`, `participantSessions`, `uniqueIdentities`,
  `connectionSuccessRate`, `avgRoomSize`, `avgRoomDurationMs`, `bytesUp`, `bytesDown`, `egressStarted`,
  `egressDurationMs`, `ingressSessions`, `ingressDurationMs`, `apiCalls` and `apiErrorRate`

### Requirement: PRO metrics, dimensions and scopes

Edition: CE. `scoreAvg`, `poorSamples` and `lostSamples` SHALL require `analytics-quality`;
`tracksSubscribeFailed`, `disconnectReason`, `roomEndReason` and `apiMethod` SHALL require `analytics-diagnostics`;
`scope=node:<id>` SHALL require `per-node-breakdown`. `ingressSessions` and `ingressDurationMs` are CE metrics and
require no feature. On CE a request containing any of the gated items SHALL be rejected whole with `403`
`PRO_FEATURE`.

#### Scenario: Mixed request on CE

- **GIVEN** a valid token on the CE dashboard
- **WHEN** the client requests `metrics=roomsCreated,scoreAvg`
- **THEN** the response is `403` with code `PRO_FEATURE`, `details.feature: "analytics-quality"` and no series

#### Scenario: Node scope on CE

- **WHEN** the CE client requests the summary with `scope=node:n1`
- **THEN** the response is `403` with `details.feature: "per-node-breakdown"`

#### Scenario: Diagnostics dimension on CE

- **GIVEN** a valid token on the CE dashboard
- **WHEN** the client requests `GET /api/v1/analytics/breakdowns?dimensions=sdk,disconnectReason`
- **THEN** the response is `403` with code `PRO_FEATURE`, `details.feature: "analytics-diagnostics"` and no
  breakdowns

### Requirement: CSV export

Edition: CE. `GET /api/v1/analytics/export.csv` SHALL accept `kind` (`series` or `breakdowns`) with the parameters
of the matching endpoint and answer `200` `text/csv; charset=utf-8` as an attachment named
`analytics-<kind>-<from>-<to>.csv` (colons removed), RFC 4180 with CRLF line ends and a header row, with the same
validation and PRO gating as the JSON endpoints.

#### Scenario: Breakdown CSV

- **WHEN** the client requests `export.csv?kind=breakdowns&dimensions=sdk,os`
- **THEN** the body has the header `dimension,key,count,percent` followed by the `sdk` rows and then the `os` rows,
  each sorted by count descending

#### Scenario: PRO metric in a CE export

- **WHEN** the CE client requests `export.csv?kind=series&metrics=scoreAvg`
- **THEN** the response is `403` JSON with code `PRO_FEATURE`, not a CSV body

#### Scenario: Series CSV on CE

- **WHEN** the client requests `export.csv?kind=series&metrics=bytesUp,roomsCreated&granularity=1h` over 24 h
- **THEN** the body has the header `bucket,bytesUp,roomsCreated` and 24 data rows whose first cell is the bucket
  start in ISO 8601 UTC

### Requirement: Index-backed analytics queries

Edition: CE. Every rollup read SHALL be a bounded index scan on `{ scope, bucket }` of the chosen collection;
integration tests SHALL assert the plans with `explain()`.

#### Scenario: Explain plans on the generated database

- **GIVEN** a database generated by the data generator at scenario M
- **WHEN** the integration suite explains every analytics query
- **THEN** no plan contains `COLLSCAN` and rollup plans report the `{ scope, bucket }` index with
  `totalKeysExamined` at most the number of buckets in range plus one

### Requirement: Ingress input type breakdown

Edition: CE. The breakdowns endpoint SHALL accept the dimension `ingressInputType`, which sums `ingress.byInputType`
of the hourly and daily rollups in range under the keys `rtmp`, `whip` and `url`: the ingress sessions started in the
range by input type. It is not gated by any feature.

#### Scenario: Sessions by input type

- **GIVEN** rollups in range with `ingress.byInputType` summing to `rtmp: 8`, `whip: 3` and `url: 1`
- **WHEN** `dimensions=ingressInputType` is requested on CE
- **THEN** the breakdown has `total: 12` and items `rtmp` 8 / 66.7, `whip` 3 / 25.0 and `url` 1 / 8.3

#### Scenario: No ingress in the range

- **GIVEN** no ingress session started in the range
- **WHEN** `dimensions=ingressInputType` is requested
- **THEN** the breakdown has `total: 0` and `items: []`

### Requirement: Media statistics coverage

Edition: CE. The summary SHALL carry `mediaStats: "none"` when every `nodes` document of its scope whose heartbeat span
(`firstSeenAt` to `lastSeenAt`) overlaps the range has `mediaStats: false`, `mediaStats: "partial"` when only some do,
and no `mediaStats` property when none does or no node document overlaps the range. The `global` scope covers every
node, a `node:<id>` scope that node only.

#### Scenario: No server reports media statistics

- **GIVEN** two nodes seen during the range, both with `mediaStats: false`
- **WHEN** the summary is requested
- **THEN** the body has `mediaStats: "none"` and still carries `bytesUp` and `bytesDown`

#### Scenario: Some servers report media statistics

- **GIVEN** a node with `mediaStats: false` and a node with `mediaStats: true` seen during the range
- **WHEN** the summary is requested with the `global` scope
- **THEN** the body has `mediaStats: "partial"`

#### Scenario: Node scope

- **GIVEN** the same two nodes and `scope=node:<id>` of the node with `mediaStats: true`
- **WHEN** the summary is requested
- **THEN** the body has no `mediaStats` property

#### Scenario: Node seen outside the range

- **GIVEN** a node with `mediaStats: false` whose `lastSeenAt` is earlier than `from`, and a node with
  `mediaStats: true` seen during the range
- **WHEN** the summary is requested
- **THEN** the body has no `mediaStats` property