# Rendimiento

> Métricas de las páginas en el percentil 75, llamadas a la API lentas o que fallan, el elemento detrás de cada métrica, mapas de clics con clics de rabia y clics muertos, fallas de formularios, eventos propios y las sugerencias semanales.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/api/performance/

Para agentes: Referencia de los endpoints de rendimiento de la API de Sypnia: resumen, páginas, llamadas a la API, elementos detrás de LCP/INP/CLS, mapa de clics, captura de página, fallas de formularios y sugerencias semanales.

Todos los números vienen de visitas reales. Los percentiles se calculan con histogramas de intervalos fijos, para poder mezclarlos entre horas: un p75 es exacto a su intervalo, no al milisegundo. Cuando un percentil cae más allá del último intervalo, la fila lo dice con una marca `_overflow`: el valor real está por encima del número que se muestra.

| Métrica                                       | Buena       | Mala         | Unidad  |
| --------------------------------------------- | ----------- | ------------ | ------- |
| LCP, la pintura del contenido más grande      | hasta 2.500 | más de 4.000 | ms      |
| INP, de la interacción a la siguiente pintura | hasta 200   | más de 500   | ms      |
| CLS, el movimiento acumulado del diseño       | hasta 0,1   | más de 0,25  | puntaje |
| TTFB, el tiempo hasta el primer byte          | hasta 800   | más de 1.800 | ms      |

## Traer el resumen de rendimiento

`GET /v1/performance` \[Motor, Nube]

Los números de toda la app, y qué empeoró: las páginas y las llamadas a la API cuyos números más se movieron frente al periodo justo anterior, de la misma duración. Es lo que devuelve la herramienta MCP `performance`.

Una página aparece en `slower_pages` cuando su LCP en el percentil 75 creció 30 % o más y tuvo al menos 50 vistas en los dos periodos. Una llamada a la API aparece en `failing_api` cuando más del 2 % de sus peticiones respondió `5xx` o nada, con al menos 50 peticiones.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `since` (string, opcional, por defecto `7d`): Inicio del periodo. El periodo de comparación dura lo mismo y va justo antes.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/performance?since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "period": {
    "since": "2026-03-11T10:35:00Z",
    "until": "2026-03-12T10:35:00Z"
  },
  "vitals": {
    "lcp_p75_ms": 2300,
    "inp_p75_ms": 160,
    "cls_p75": 0.03,
    "ttfb_p75_ms": 380,
    "poor_share": 0.12,
    "page_loads": 4210
  },
  "slower_pages": [
    {
      "route": "/search",
      "lcp_p75_ms": 3100,
      "previous_lcp_p75_ms": 1900,
      "views": 1840
    }
  ],
  "slowest_pages": [
    {
      "route": "/search",
      "lcp_p75_ms": 3100,
      "views": 1840
    },
    {
      "route": "/products/:id",
      "lcp_p75_ms": 2200,
      "views": 1310
    },
    {
      "route": "/checkout",
      "lcp_p75_ms": 1400,
      "views": 58
    }
  ],
  "failing_api": [],
  "slowest_api": [
    {
      "method": "POST",
      "route": "/api/checkout",
      "p95_ms": 3900,
      "requests": 36,
      "error_rate": 0.139
    }
  ],
  "rage_click_pages": [
    {
      "route": "/checkout",
      "rage_clicks": 1,
      "views": 58
    }
  ],
  "suggestions": {
    "new": 1
  }
}
```

## Listar el rendimiento de las páginas

`GET /v1/performance/pages` \[Motor, Nube]

Una fila por ruta de página, con vistas, tiempo en la página, las cuatro métricas en el percentil 75, la parte de las cargas calificadas como malas, y cuántos errores, clics de rabia y clics muertos hubo ahí. Cada métrica trae su propio número de muestras: un p75 de 3 muestras no es un hecho.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `since` (string, opcional, por defecto `7d`): Inicio del periodo.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `device` (string, opcional): Solo mediciones de este tipo de dispositivo. Uno de: `mobile`, `tablet`, `desktop`.
- `sort` (string, opcional, por defecto `views`): Por qué columna ordenar, lo peor o lo mayor primero. Uno de: `views`, `sessions`, `seconds`, `lcp`, `inp`, `cls`, `ttfb`, `poor`, `errors`, `rage`, `dead`.
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/performance/pages?sort=lcp&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "route": "/search",
      "views": 1840,
      "sessions": 402,
      "avg_seconds": 38.2,
      "lcp_p75_ms": 3100,
      "lcp_samples": 1612,
      "lcp_overflow": false,
      "inp_p75_ms": 180,
      "inp_samples": 1204,
      "inp_overflow": false,
      "cls_p75": 0.04,
      "ttfb_p75_ms": 410,
      "poor_share": 0.21,
      "errors": 0,
      "rage_clicks": 2,
      "dead_clicks": 9
    },
    {
      "route": "/checkout",
      "views": 58,
      "sessions": 51,
      "avg_seconds": 44.0,
      "lcp_p75_ms": 1400,
      "lcp_samples": 55,
      "lcp_overflow": false,
      "inp_p75_ms": 120,
      "inp_samples": 49,
      "inp_overflow": false,
      "cls_p75": 0.01,
      "ttfb_p75_ms": 320,
      "poor_share": 0.02,
      "errors": 5,
      "rage_clicks": 1,
      "dead_clicks": 0
    }
  ],
  "next_cursor": null
}
```

## Listar el rendimiento de las llamadas a la API

`GET /v1/performance/api` \[Motor, Nube]

Una fila por ruta y método de la API, vista desde los dos lados: desde el navegador (cuánto esperó la persona, cuántas llamadas fallaron) y desde el servidor (cuánto tardó en atender, cuántas llamadas hizo hacia atrás). Las filas que solo tienen datos del servidor vienen de backends que envían trazas sin un SDK de navegador.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `since` (string, opcional, por defecto `7d`): Inicio del periodo.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `route` (string, hasta 500 caracteres, opcional): Solo esta ruta de la API.
- `sort` (string, opcional, por defecto `requests`): `requests`, `error_rate`, `p95` (navegador), `server_p95` o `calls` (llamadas hacia atrás por petición).
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/performance/api?sort=error_rate&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "method": "POST",
      "route": "/api/checkout",
      "requests": 36,
      "ok": 31,
      "client_errors": 5,
      "server_errors": 0,
      "network_errors": 0,
      "error_rate": 0.139,
      "p50_ms": 900,
      "p95_ms": 3900,
      "server_requests": 36,
      "server_p95_ms": 3850,
      "avg_calls": 2.0,
      "avg_calls_ms": 1210
    }
  ],
  "next_cursor": null
}
```

## Traer los elementos detrás de las métricas de una página

`GET /v1/performance/vitals` \[Motor, Nube]

Para una página, los elementos a los que el navegador les atribuyó cada métrica: el que fue la pintura más grande (LCP), el que tardó en responder a una interacción (INP) y el que más movió el diseño (CLS). Es lo que convierte «la página de búsqueda está lenta» en «la primera imagen de la lista de productos está lenta». Hasta 10 elementos por métrica, los de más muestras primero. TTFB no tiene elemento.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `route` (string, hasta 500 caracteres, obligatorio): La ruta de la página, empezando con `/`.
- `since` (string, opcional, por defecto `7d`): Inicio del periodo.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `device` (string, opcional): Solo mediciones de este tipo de dispositivo. Uno de: `mobile`, `tablet`, `desktop`.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/performance/vitals?route=/search&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "route": "/search",
  "device": null,
  "lcp": [
    {
      "selector": "main ul.results > li:nth-child(1) img",
      "kind": "image",
      "samples": 1310,
      "p75_ms": 3200,
      "poor_share": 0.24
    },
    {
      "selector": "main h1",
      "kind": "text",
      "samples": 302,
      "p75_ms": 1300,
      "poor_share": 0.01
    }
  ],
  "inp": [
    {
      "selector": "form.filters select#sort",
      "kind": "pointer",
      "samples": 640,
      "p75_ms": 210,
      "poor_share": 0.03
    }
  ],
  "cls": [
    {
      "selector": "aside.promo",
      "kind": null,
      "samples": 480,
      "p75": 0.06,
      "poor_share": 0.02
    }
  ]
}
```

**Errores:**

- `400` `invalid_request`: Falta `route` o no empieza con `/`.

## Traer el mapa de clics de una página

`GET /v1/clicks` \[Motor, Nube]

Dónde hace clic la gente en una página: los elementos que tocaron, los más tocados primero, con cuántos de esos clics fueron **clics de rabia** (el mismo punto una y otra vez) y **clics muertos** (un clic que no cambió nada). Las filas de una lista que comparten un mismo control se juntan en un elemento (`instances`). Cada elemento trae sesiones de muestra para mirar.

`label` es lo que dice el control («Pay $64.00»). Solo se guarda cuando la mayoría de los clics en ese elemento mostraban el mismo texto; para filas de listas y enlaces a un registro es `null`, porque ese texto sería el nombre de una persona o un número de pedido.

Para saber qué páginas mirar, lista el rendimiento de las páginas ordenado por `rage` o `dead`. Para dibujar el mapa sobre la página, trae la captura de página.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `route` (string, hasta 500 caracteres, obligatorio): La ruta de la página, empezando con `/`.
- `device` (string, opcional, por defecto `desktop`): Los diseños cambian según el dispositivo, así que un mapa de clics siempre es de uno. Uno de: `mobile`, `tablet`, `desktop`.
- `since` (string, opcional, por defecto `7d`): Inicio del periodo.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `only` (string, opcional): `rage` o `dead` devuelve solo los elementos con clics de ese tipo.
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/clicks?route=/checkout&only=rage" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "route": "/checkout",
  "device": "desktop",
  "totals": {
    "clicks": 214,
    "rage_clicks": 1,
    "dead_clicks": 0,
    "elements": 17
  },
  "elements": [
    {
      "selector": "#pay-button",
      "role": "button",
      "label": "Pay $64.00",
      "context": "Your order",
      "clicks": 41,
      "rage_clicks": 1,
      "dead_clicks": 0,
      "share": 0.19,
      "instances": 1,
      "box": {
        "x": 880,
        "y": 612,
        "width": 240,
        "height": 48
      },
      "sample_sessions": [
        "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0"
      ]
    }
  ]
}
```

**Errores:**

- `400` `invalid_request`: Falta `route` o no empieza con `/`.

## Traer una captura de página

`GET /v1/clicks/snapshot` \[Motor, Nube]

Una captura de la página para dibujar encima un mapa de clics: la más completa de las diez más recientes de la ruta y el dispositivo, como un enlace que funciona 15 minutos. La captura es una captura de rrweb, enmascarada como una grabación, así que necesita el permiso `replay`. Cuando el dispositivo que pediste no tiene ninguna, se devuelve la del dispositivo más cercano y `device_used` dice cuál.

**Autenticación:** Token de API (`replay`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `route` (string, hasta 500 caracteres, obligatorio): La ruta de la página, empezando con `/`.
- `device` (string, opcional, por defecto `desktop`): El diseño de dispositivo que quieres. Uno de: `mobile`, `tablet`, `desktop`.
- `taken_at` (timestamp, opcional): Devuelve exactamente esta captura, una de `candidates`, en vez de la más completa.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/clicks/snapshot?route=/checkout" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "found": true,
  "route": "/checkout",
  "device_requested": "desktop",
  "device_used": "desktop",
  "taken_at": "2026-03-12T10:31:30Z",
  "viewport": {
    "width": 1440,
    "height": 900
  },
  "page_height": 1630,
  "mask": 1,
  "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/snapshots/…?X-Amz-Signature=…",
  "expires_at": "2026-03-12T10:55:00Z",
  "candidates": [
    {
      "taken_at": "2026-03-12T10:31:30Z",
      "device": "desktop"
    },
    {
      "taken_at": "2026-03-12T09:02:55Z",
      "device": "desktop"
    }
  ]
}
```

**Errores:**

- `403` `forbidden`: El token no tiene el permiso `replay`.

## Listar fallas de formularios

`GET /v1/form-failures` \[Motor, Nube]

Formularios que la gente no pudo enviar porque la validación del propio navegador los detuvo: un campo obligatorio vacío, un correo con mala forma. Una fila por página, campo y razón. El campo se nombra por su etiqueta, nunca por lo que se escribió. La gente casi nunca reporta esto; simplemente se va.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `since` (string, opcional, por defecto `7d`): Inicio del periodo.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `route` (string, hasta 500 caracteres, opcional): Solo esta página.
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/form-failures?since=7d" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "route": "/checkout",
      "field": "Postal code",
      "context": "Shipping address",
      "reason": "patternMismatch",
      "count": 12,
      "sessions": 9,
      "sample_sessions": [
        "2b7d9e4f1a6c4830b5d2f7e9c1a3b5d7"
      ]
    }
  ],
  "next_cursor": null
}
```

## Listar las sugerencias semanales

`GET /v1/suggestions` \[Motor, Nube]

Una vez por semana el agente mira los números de la semana y propone mejoras de rendimiento y de uso de la app: una página lenta y el elemento que la frena, un botón al que la gente le hace clics de rabia, una llamada a la API que hace demasiadas consultas a la base de datos. Cada sugerencia viene con su evidencia. Algunas son reglas simples (INP por encima de 500 ms en p75, más de 3 clics de rabia por cada 100 vistas, `5xx` por encima de 2 %) y salen aun sin proveedor de IA; las que necesitan un modelo se saltan cuando el agente está apagado.

La corrida es el lunes a las 07:00 UTC, sobre la semana que terminó. `last_run` dice cuándo corrió por última vez y cómo.

**Autenticación:** Token de API (`read`)

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.
- `environment` (string, opcional, por defecto `production`): El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o `all`.
- `status` (string, opcional, por defecto `new`): Qué sugerencias devolver. Uno de: `new`, `accepted`, `dismissed`, `done`, `all`.
- `category` (string, opcional): Solo de este tipo. Uno de: `performance`, `usability`, `reliability`.
- `since` (string, opcional, por defecto `56d`): Solo sugerencias de semanas que empezaron después de este momento.
- `limit` (integer, 1 a 200, opcional, por defecto `50`): Máximo de elementos que se devuelven.
- `cursor` (string, opcional): El `next_cursor` de la página anterior. Deja iguales todos los demás parámetros.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/suggestions" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "sug_3h7j1k5l9p2o",
      "week": "2026-03-02",
      "category": "performance",
      "status": "new",
      "title": "The search page's first product image loads slowly",
      "text": "Three of four visits wait more than 3 seconds for the search page to show its main content. The element is the first product image. Serve it smaller, or load it before the rest.",
      "route": "/search",
      "rule": "lcp_p75",
      "evidence": [
        "LCP at p75 is 3,100 ms over 1,612 page loads; it was 1,900 ms the week before.",
        "In 81 % of slow loads the LCP element is `main ul.results > li:nth-child(1) img`."
      ],
      "created_at": "2026-03-09T07:02:14Z"
    }
  ],
  "counts": {
    "new": 1,
    "accepted": 2,
    "dismissed": 1,
    "done": 3
  },
  "last_run": {
    "week": "2026-03-02",
    "status": "ok",
    "suggestions": 1,
    "model_used": true
  },
  "next_cursor": null
}
```

## Cambiar el estado de una sugerencia

`PATCH /v1/suggestions/{suggestion_id}` \[Motor, Nube]

Marca una sugerencia como aceptada, descartada o hecha, o la devuelve a nueva. Una sugerencia descartada no se vuelve a proponer durante 8 semanas.

**Autenticación:** Token de API (`read`)

**Parámetros de ruta:**

- `suggestion_id` (string, obligatorio): El id de la sugerencia (`sug_…`).

**Parámetros de consulta:**

- `project` (string, opcional): El id o el slug del proyecto. Solo hace falta con una credencial que ve varios proyectos (el token raíz). Con un token de API se ignora, salvo que nombre otro proyecto, que es `403`.

**Cuerpo:**

- `status` (string, obligatorio): El estado nuevo. Uno de: `new`, `accepted`, `dismissed`, `done`.

**Petición:**

```bash
curl -X PATCH "https://api.sypnia.com/v1/suggestions/sug_3h7j1k5l9p2o" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted"}'
```

**Respuesta (200):**

```json
{
  "id": "sug_3h7j1k5l9p2o",
  "week": "2026-03-02",
  "category": "performance",
  "status": "accepted",
  "title": "The search page's first product image loads slowly",
  "text": "Three of four visits wait more than 3 seconds for the search page to show its main content. The element is the first product image. Serve it smaller, or load it before the rest.",
  "route": "/search",
  "rule": "lcp_p75",
  "evidence": [
    "LCP at p75 is 3,100 ms over 1,612 page loads; it was 1,900 ms the week before.",
    "In 81 % of slow loads the LCP element is `main ul.results > li:nth-child(1) img`."
  ],
  "created_at": "2026-03-09T07:02:14Z"
}
```

**Errores:**

- `404` `not_found`: Ninguna sugerencia del proyecto tiene este id.

Los errores que cualquier endpoint puede responder (`401`, `403`, `429`, `500`, `503`) están en [Errores, límites, paginación](https://docs.sypnia.com/es/api/errors-limits-pagination).
