> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Request-metrics reader gates: four bounded surfaces

> The four bounded surfaces that decide what the request-metrics read path bills against your aggregate — the window precedence chain, the origin-feature gate, the latency exclusion predicate, and the pipeline skip-list — with the safe drift direction for each.

# Request-metrics reader gates: four bounded surfaces

One rule governs every read on the request-metrics surface: **the invariant check is the one claim that bills.** A completed request writes
exactly one telemetry row, keyed by `request_id` and attributed to your
tenant; the aggregate counts or excludes that row, it never invents one.
Four bounded surfaces decide which rows a given read sees and what the
aggregate does with them:

1. **Window chain** — which time range the query scans.
2. **Origin-feature gate** — whether the advanced-analytics block is
   enabled for your workspace.
3. **Latency exclusion** — which status codes the latency percentiles drop.
4. **Pipeline skip-list** — which request paths never meter a row at all.

Treat each as a predicate the read resolves before it returns a number,
not a setting you tune. The window inputs and the feature flag are
tenant-owned controls; the skip-list and the 429 exclusion are
platform-owned constants. None is a new invariant — all four already
exist in the [request-metrics pipeline](/concepts/request-metrics-and-analytics-pipeline)
and the stats surface.

## 1. Window chain: start, end, trailing bound

Every time-bounded read resolves its window through one precedence order:

| Precedence | Input | Behaviour |
| - | - | - |
| 1 | `start_date` + `end_date` | Inclusive `YYYY-MM-DD` pair; overrides every trailing form. |
| 2 | `days` | Trailing bound the dashboard presets resolve to; capped at 365. |
| 3 | Bucket preset | Request-logs accepts `1h`, `6h`, `24h`, `7d`, `30d`, `90d`. |
| 4 | Default | No input: request-logs reads the trailing 24h, analytics reads 30 days. |

A value that fails shape validation is dropped silently — you get the
default or a wider window, never a 400. **Drift direction: drop.** A
malformed bound widens the range rather than erroring; the read degrades
to a broader window, not a failure.

## 2. Origin-feature gate: the advanced-analytics flag

The `/stats/analytics` block (summary, channels, volume, delivery funnel)
sits behind a per-tenant feature flag. With the flag off, the block
returns `403 FEATURE_DISABLED`; with it on, the window chain runs and
returns the full payload. The always-on widgets (summary, channel-health,
usage, activity, request-logs, dashboard) are available to every reader
with the `analytics:read` scope regardless of the flag. **Treat the 403
as "not enabled", never as an error to retry.** **Drift direction: clamp.** A disabled workspace gets a fixed 403, not a partial payload — the gate holds the surface closed rather than returning thin data.

## 3. Latency exclusion: 429s leave the percentiles

The head aggregate excludes rate-limit rejections (`429`) from the
p50/p95 and the mean: a 429 is answered at the rate-limit guard in
milliseconds, and folding it in would pull the rendered p50 far below
your real handler latency. The volume counters still count every
metered row — 429s included — so the error-rate and request-count cards
stay honest. **Drift direction: degrade.** A 429 spike lowers the
aggregate numerator while the latency percentile stays pinned to the
served subset; the band coarsens toward served traffic, which is the
intended shape, not a contradiction.

## 4. Pipeline skip-list: which paths never meter

The write side names its self-observation and keepalive paths on an
explicit skip list — health probes, the analytics console's own reads,
presence heartbeats, and realtime transports — rather than a blanket
"everything authenticated counts" line. A row that matches the skip
list never enters the aggregate, so the percentiles measure genuine API
traffic instead of the dashboard tab that rendered them. The read side
mirrors the same constant to also exclude historical rows metered before
the skip shipped, for up to a 30-day window. **Drift direction: drop.**
A skipped path contributes zero rows; the counter reads operator-intent
calls only, and a pre-skip row still sitting in a longer window thins
over a few days rather than persisting.

## See also

* [Request-metrics pipeline](/concepts/request-metrics-and-analytics-pipeline) —
  the write-side hook, Redis buffer, and read surface these gates bound.
* [Request Logs model](/concepts/request-logs-model) — the sibling
  Cloud Logging read the window chain drives.
* [Stats surface map](/concepts/observability-stats-surface) — which
  route family answers which question.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.