# Referencia de la API de RUM

> Rutas, parámetros y respuestas de la API de lectura de la monitorización de usuarios reales, sus ajustes y las órdenes de CLI y MCP equivalentes.

## Rutas de lectura

Todas las rutas son `GET /v1/orgs/{org}/zones/{zone}/rum/…` en `https://dash.openwaf.dev`. Cualquier rol de la organización puede consultarlas, incluidos los tokens de solo lectura y los limitados a una zona.

| Ruta | Respuesta |
|---|---|
| `…/rum/summary` | `visits`, `prev_visits`, `injection` y, por métrica, `{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}]}` con el p75 de cada métrica por intervalo. `step` es un múltiplo de 60 segundos; por defecto, el menor entre 5 minutos y 1 día que da como mucho 60 puntos. |
| `…/rum/breakdown?by=…&limit=10` | Filas `{key, visits, metrics}` por visitas (como mucho 100). `by` ∈ `path`, `country`, `node`, `device`, `connection`, `nav_type`, `host`, `viewport`. |
| `…/rum/lcp-parts[?by=device\|path]` | `{lcp_p75, count, parts, all}`: las fases del LCP de las vistas lentas (`parts`) y de todas (`all`); con `by`, además `rows` (10). |
| `…/rum/offenders?kind=…&limit=10` | Filas `{key, count, p75, poor, top_path}`. `kind` ∈ `lcp_element`, `lcp_url`, `inp_target`, `inp_script`, `cls_target`. |
| `…/rum/report` | Todo lo que necesita el panel en una llamada: `summary`, `timeseries`, `breakdowns` (path 25 filas; country, node, device, connection 10), `lcp_parts` por dispositivo, `offenders` (`lcp_element`, `inp_target`, `inp_script`, `cls_target`) y los `settings` de RUM de la zona. `breakdowns.device` ignora el filtro `device`. |

## Parámetros comunes

| Parámetro | Significado |
|---|---|
| `since`, `until` | RFC 3339. Por defecto, los últimos 7 días; como mucho 31 días. |
| `host`, `path` | Host y ruta de aterrizaje exactos. |
| `country` | Código ISO 3166-1 alfa-2, p. ej. `ES`. |
| `device` | `mobile`, `tablet` o `desktop`. |
| `connection` | `4g`, `3g`, `2g` o `slow-2g`. |
| `nav_type` | Tipo de navegación que indica el navegador. |
| `node` | El nodo del borde que sirvió la visita. |

## Respuestas

- Los valores de las métricas van en milisegundos, salvo el CLS (sin unidad), con como mucho 4 decimales. Sin datos, `null`.
- `count` es el número de vistas medidas que tienen la métrica; `visits` es la estimación de vistas reales (cada vista medida cuenta `1/sample_rate`).
- Los valores `prev_*` cubren el periodo de la misma duración justo antes de `since`.
- Los intervalos de las series se alinean en UTC e incluyen los vacíos (`visits` `0`, métricas `null`).
- `injection` suma los contadores de inyección del borde del periodo: `injected`, `csp_nonce` (inyectado reutilizando el nonce de tu CSP), `csp_blocked` (no inyectado por tu CSP), `no_head` (sin `</head>` antes del que inyectar) y `sampled_out`.

## Errores

| Estado | Código | Cuándo |
|---|---|---|
| `400` | `bad_request` | Fechas, filtros, `by`, `kind`, `step` o `limit` no válidos. |
| `404` | `not_found` | La zona no existe o es de otra organización. |
| `503` | `unavailable` | La analítica no está disponible temporalmente. |

## Ajustes

`GET /v1/orgs/{org}/zones/{zone}/edge` siempre devuelve `"rum": {"enabled": false, "sample_rate": 1, "exclude_paths": []}` o los valores actuales. Se cambian con `PATCH` en la misma ruta (JSON merge patch: los campos enviados sustituyen a los actuales, `exclude_paths` entera; un campo a `null` vuelve a su valor por defecto y `"rum": null` al objeto por defecto). Consulta [Monitorización de usuarios reales](https://developers.openwaf.dev/es/analytics/real-user-monitoring/#settings).

## CLI y MCP

| | Orden o herramienta |
|---|---|
| Informe | `openwaf-cloud ctl rum report <zona> [--since 7d\|RFC3339] [--until …] [--device …] [--country …] [--node …] [--path …] [--host …] [--connection …] [--nav-type …] [--by path\|country\|node\|device\|connection] [--json]` |
| Ajustes | `openwaf-cloud ctl zones set <zona> [--host <nombre>] rum.enabled=true rum.sample_rate=… rum.exclude_paths=…` |
| Informe por MCP | `rum_report`: `zone`, `period` (`24h`, `7d`, `30d`) o `since`/`until`, los mismos filtros y `by`. |
| Ajustes por MCP | `update_settings` con `settings.rum`. |

## Tráfico y eventos

| Ruta | Consulta |
|---|---|
| `GET /v1/orgs/{org}/zones/{zone}/usage?from=&to=` | [Tráfico](https://developers.openwaf.dev/es/analytics/traffic/) |
| `GET /v1/orgs/{org}/zones/{zone}/events`, `/events/summary`, `/events/histogram`, `/events/stream` | [Eventos de seguridad](https://developers.openwaf.dev/es/analytics/security-events/) |