# RUM API reference

> Routes, parameters and answers of the Real User Monitoring read API, the RUM settings, and the matching CLI and MCP commands.

## Read routes

All routes are `GET /v1/orgs/{org}/zones/{zone}/rum/…` on `https://dash.openwaf.dev`. Any role of the organization can read them, including read-only and zone-scoped tokens.

| Route | Answer |
|---|---|
| `…/rum/summary` | `visits`, `prev_visits`, `injection` and, per metric, `{p50, p75, p90, count, good, needs_improvement, poor, prev_p75, prev_count}`. |
| `…/rum/timeseries?step=<s>` | `{step, points: [{ts, visits, lcp, inp, cls, fcp, ttfb}]}` with the p75 of each metric per interval. `step` is a multiple of 60 seconds; by default the smallest of 5 minutes to 1 day that gives at most 60 points. |
| `…/rum/breakdown?by=…&limit=10` | Rows `{key, visits, metrics}` by visits (at most 100). `by` ∈ `path`, `country`, `node`, `device`, `connection`, `nav_type`, `host`, `viewport`. |
| `…/rum/lcp-parts[?by=device\|path]` | `{lcp_p75, count, parts, all}`: the LCP phases of the slow views (`parts`) and of all views (`all`); with `by`, also `rows` (10). |
| `…/rum/offenders?kind=…&limit=10` | Rows `{key, count, p75, poor, top_path}`. `kind` ∈ `lcp_element`, `lcp_url`, `inp_target`, `inp_script`, `cls_target`. |
| `…/rum/report` | Everything the dashboard needs in one call: `summary`, `timeseries`, `breakdowns` (path 25 rows; country, node, device, connection 10), `lcp_parts` by device, `offenders` (`lcp_element`, `inp_target`, `inp_script`, `cls_target`) and the zone's RUM `settings`. `breakdowns.device` ignores the `device` filter. |

## Common parameters

| Parameter | Meaning |
|---|---|
| `since`, `until` | RFC 3339. Default: the last 7 days; at most 31 days. |
| `host`, `path` | Exact host and landing path. |
| `country` | ISO 3166-1 alpha-2 code, e.g. `ES`. |
| `device` | `mobile`, `tablet` or `desktop`. |
| `connection` | `4g`, `3g`, `2g` or `slow-2g`. |
| `nav_type` | Navigation type reported by the browser. |
| `node` | The edge node that served the visit. |

## Answers

- Metric values are in milliseconds, except CLS (unitless), with at most 4 decimals. Without data, `null`.
- `count` is the number of measured page views that have the metric; `visits` is the estimate of real views (each measured view counts `1/sample_rate`).
- `prev_*` values cover the period of the same length just before `since`.
- Time series intervals are aligned to UTC and include empty intervals (`visits` `0`, metrics `null`).
- `injection` sums the edge's injection counters for the period: `injected`, `csp_nonce` (injected reusing your CSP nonce), `csp_blocked` (not injected because of your CSP), `no_head` (no `</head>` to inject before) and `sampled_out`.

## Errors

| Status | Code | When |
|---|---|---|
| `400` | `bad_request` | Invalid times, filter, `by`, `kind`, `step` or `limit`. |
| `404` | `not_found` | The zone doesn't exist or belongs to another organization. |
| `503` | `unavailable` | Analytics are temporarily unavailable. |

## Settings

`GET /v1/orgs/{org}/zones/{zone}/edge` always returns `"rum": {"enabled": false, "sample_rate": 1, "exclude_paths": []}` or the current values. Change them with `PATCH` on the same route (JSON merge patch: fields given replace the current ones, `exclude_paths` as a whole; a field set to `null` returns to its default and `"rum": null` to the default object). See [Real User Monitoring](https://developers.openwaf.dev/analytics/real-user-monitoring/#settings).

## CLI and MCP

| | Command or tool |
|---|---|
| Report | `openwaf-cloud ctl rum report <zone> [--since 7d\|RFC3339] [--until …] [--device …] [--country …] [--node …] [--path …] [--host …] [--connection …] [--nav-type …] [--by path\|country\|node\|device\|connection] [--json]` |
| Settings | `openwaf-cloud ctl zones set <zone> [--host <name>] rum.enabled=true rum.sample_rate=… rum.exclude_paths=…` |
| MCP report | `rum_report`: `zone`, `period` (`24h`, `7d`, `30d`) or `since`/`until`, the same filters and `by`. |
| MCP settings | `update_settings` with `settings.rum`. |

## Traffic and events

| Route | See |
|---|---|
| `GET /v1/orgs/{org}/zones/{zone}/usage?from=&to=` | [Traffic](https://developers.openwaf.dev/analytics/traffic/) |
| `GET /v1/orgs/{org}/zones/{zone}/events`, `/events/summary`, `/events/histogram`, `/events/stream` | [Security events](https://developers.openwaf.dev/analytics/security-events/) |