# Sesiones y grabaciones

> Lista sesiones, lee la línea de tiempo de eventos de una sesión y trae su grabación como enlaces de corta duración.

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/sessions-and-replays/

Para agentes: Referencia de los endpoints de sesiones de la API de Sypnia: listar y traer sesiones, línea de tiempo de eventos, grabación por ventanas con enlaces firmados, personas, cuentas, eventos propios y borrado de datos.

Una sesión es una visita de una persona. El motor guarda un índice de sesiones en Postgres y los eventos de cada sesión como objetos en tu bucket, así que leer una línea de tiempo es una sola lectura de los archivos de esa sesión.

La lista de sesiones está completa a menos de 10 minutos de los eventos. Una grabación se puede ver cuando su sesión lleva 2 minutos sin actividad o ya terminó. `GET /v1/summary` devuelve `data_through`, el momento hasta el que todo está procesado.

Las sesiones son de una **persona** cuando tu app llamó a `identify()` (`person.id`, y `name` y `email` solo si tu app los envió) y, si quieres, de la **cuenta** a la que esa persona pertenece en tu app (un equipo, una empresa). Las sesiones anónimas valen igual: `person` es `null` y la sesión igual aparece en las listas, se puede buscar por id y se cuenta. Los endpoints de personas y cuentas de esta página muestran la actividad por persona y por cuenta.

El contenido de una grabación necesita el permiso `replay`. Un token con solo `read` ve que existe una grabación (`has_replay`) y no puede traerla.

## El objeto sesión

**Campos:**

- `id` (string, opcional): El id de la sesión, 32 caracteres hexadecimales, elegido por el SDK.
- `started_at` (timestamp, opcional): El primer evento.
- `ended_at` (timestamp, opcional): El evento más reciente. Una sesión termina después de 30 minutos sin actividad.
- `duration_ms` (integer, opcional): Del primer evento al más reciente.
- `person` (object o null, opcional): Quién era, si tu app la identificó. `null` en una sesión anónima.
- `person.id` (string): El id que dio tu app. Una cadena opaca.
- `person.name` (string o null): Solo si tu app lo envió.
- `person.email` (string o null): Solo si tu app lo envió.
- `account` (object o null, opcional): La cuenta a la que pertenece la persona en tu app, si tu app la envió.
- `environment` (string, opcional)
- `release` (string o null, opcional): La versión en la que corrió la sesión.
- `device` (string o null, opcional): Según el ancho de la ventana: menos de 768, menos de 1024, o más. Uno de: `mobile`, `tablet`, `desktop`.
- `browser` (string o null, opcional): Nombre y versión mayor, `Chrome 134`.
- `os` (string o null, opcional)
- `locale` (string o null, opcional): El idioma de la página.
- `entry_route` (string o null, opcional): La primera página.
- `routes` (lista de string, opcional): Las páginas visitadas, en orden de primera visita. Hasta 50.
- `page_views` (integer, opcional)
- `clicks` (integer, opcional)
- `rage_clicks` (integer, opcional)
- `dead_clicks` (integer, opcional)
- `errors` (integer, opcional)
- `requests` (integer, opcional)
- `failed_requests` (integer, opcional)
- `trouble` (boolean, opcional): `true` cuando la sesión tiene un error, un clic de rabia, un clic muerto o una petición fallida.
- `has_replay` (boolean, opcional): Si existe una grabación que se pueda reproducir. Pasa a `false` cuando la grabación cumple su retención.
- `url` (URL, opcional): La sesión en la app o en la Consola.

## El objeto evento de sesión

**Campos:**

- `at` (timestamp, opcional): Cuándo pasó, con precisión de milisegundos.
- `offset_ms` (integer, opcional): Milisegundos desde que empezó la sesión.
- `type` (string, opcional): Qué tipo de evento es. Uno de: `page_view`, `page_leave`, `click`, `rage_click`, `dead_click`, `error`, `server_error`, `request`, `vital`, `form_invalid`, `custom`.
- `route` (string o null, opcional): La página donde pasó.
- `text` (string, opcional): El evento en palabras simples, listo para mostrar o para pasarle a un modelo.
- `data` (object, opcional): Los detalles, según el tipo.
  `click`, `rage_click`, `dead_click`: `selector`, `role`, `label`, `context`, `href`; `count` (rabia: clics de la ráfaga); `waited_ms` (muerto: cuánto tiempo no pasó nada).
  `request`: `method`, `path`, `status`, `duration_ms`, `code` y `message` (del cuerpo del error, solo en peticiones fallidas).
  `error`, `server_error`: `name`, `message`, `source`, `problem_id`.
  `page_view`: `navigation` (`load`, `push`, `replace`, `traverse`), `from`.
  `page_leave`: `duration_ms`, `scroll` (hasta dónde bajó, de 0 a 100).
  `vital`: `name`, `value`, `rating`, `selector`, `kind`.
  `form_invalid`: `field`, `context`, `reason`, `selector`.
  `custom`: `name`, `props`.
- `trace_id` (string o null, opcional): La traza de una petición, o de la petición que falló.
- `problem_id` (string o null, opcional): El problema al que pertenece un error.

## El objeto persona

**Campos:**

- `id` (string, opcional): El id que dio tu app con `identify()`.
- `name` (string o null, opcional): Solo si tu app lo envió.
- `email` (string o null, opcional): Solo si tu app lo envió.
- `account` (object o null, opcional): La cuenta en la que se vio a la persona por última vez.
- `first_seen` (timestamp, opcional)
- `last_seen` (timestamp, opcional)
- `sessions` (integer, opcional): Sesiones en el rango.
- `trouble_sessions` (integer, opcional): Sesiones con dificultades en el rango.
- `errors` (integer, opcional): Errores en el rango.

## El objeto cuenta

**Campos:**

- `id` (string, opcional): El id que dio tu app.
- `name` (string o null, opcional): Solo si tu app lo envió.
- `people` (integer, opcional): Personas distintas activas en el rango.
- `sessions` (integer, opcional)
- `trouble_sessions` (integer, opcional)
- `first_seen` (timestamp, opcional)
- `last_seen` (timestamp, opcional)
- `always_record` (boolean, opcional): Si una regla de «grabar siempre» cubre esta cuenta. Solo al pedir una cuenta.

## Listar sesiones

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

Las sesiones que empezaron en el rango de tiempo. Una sesión «con dificultades» tiene al menos un error, un clic de rabia, un clic muerto o una petición fallida; es la misma regla en todo Sypnia.

**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`): Solo sesiones que empezaron después de este momento.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `trouble` (boolean, opcional, por defecto `false`): `true` devuelve solo las sesiones con dificultades.
- `person` (string, hasta 128 caracteres, opcional): Solo sesiones de esta persona (`person.id`, exacto).
- `account` (string, hasta 128 caracteres, opcional): Solo sesiones de esta cuenta (`account.id`, exacto).
- `route` (string, hasta 500 caracteres, opcional): Solo sesiones que visitaron esta página. Se acepta una URL completa y se normaliza (`/orders/1042` pasa a `/orders/:id`).
- `event` (string, hasta 80 caracteres, opcional): Solo sesiones que enviaron este evento propio (el `name` que se le dio a `track()`).
- `device` (string, opcional): Solo sesiones en este tipo de dispositivo. Uno de: `mobile`, `tablet`, `desktop`.
- `release` (string, opcional): Solo sesiones en esta versión.
- `has_replay` (boolean, opcional): `true` devuelve solo las sesiones que tienen grabación.
- `sort` (string, opcional, por defecto `recent`): `recent` (última actividad primero), `trouble` (más dificultades primero) o `longest` (las más largas).
- `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/sessions?trouble=true&route=/checkout&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "started_at": "2026-03-12T10:31:16Z",
      "ended_at": "2026-03-12T10:31:58Z",
      "duration_ms": 42000,
      "person": {
        "id": "u_1042",
        "name": "Ada Park",
        "email": "ada@example.com"
      },
      "account": {
        "id": "acc_77",
        "name": "Corner Café"
      },
      "environment": "production",
      "release": "4f2a91c",
      "device": "desktop",
      "browser": "Chrome 134",
      "os": "macOS",
      "locale": "en-US",
      "entry_route": "/cart",
      "routes": [
        "/cart",
        "/checkout"
      ],
      "page_views": 2,
      "clicks": 7,
      "rage_clicks": 1,
      "dead_clicks": 0,
      "errors": 1,
      "requests": 6,
      "failed_requests": 1,
      "trouble": true,
      "has_replay": true,
      "url": "https://app.sypnia.com/shop/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wMy0xMlQwOTowNDowMloifQ"
}
```

## Traer una sesión

`GET /v1/sessions/{session}` \[Motor, Nube]

La sesión, más `problems`, los problemas que ocurrieron en ella.

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

**Parámetros de ruta:**

- `session` (string, obligatorio): El id de la sesión, 32 caracteres hexadecimales.

**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`.

**Petición:**

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

**Respuesta (200):**

```json
{
  "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "started_at": "2026-03-12T10:31:16Z",
  "ended_at": "2026-03-12T10:31:58Z",
  "duration_ms": 42000,
  "person": {
    "id": "u_1042",
    "name": "Ada Park",
    "email": "ada@example.com"
  },
  "account": {
    "id": "acc_77",
    "name": "Corner Café"
  },
  "environment": "production",
  "release": "4f2a91c",
  "device": "desktop",
  "browser": "Chrome 134",
  "os": "macOS",
  "locale": "en-US",
  "entry_route": "/cart",
  "routes": [
    "/cart",
    "/checkout"
  ],
  "page_views": 2,
  "clicks": 7,
  "rage_clicks": 1,
  "dead_clicks": 0,
  "errors": 1,
  "requests": 6,
  "failed_requests": 1,
  "trouble": true,
  "has_replay": true,
  "url": "https://app.sypnia.com/shop/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "problems": [
    {
      "id": "prb_8f3k2m9x4q7w",
      "slug": "pay-button-does-nothing",
      "status": "open",
      "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
      "title": "createPayment answered 400 in POST /api/checkout",
      "occurrences": 1,
      "first_occurrence_at": "2026-03-12T10:31:47Z"
    }
  ],
  "replay": {
    "chunks": 5,
    "bytes": 412380,
    "recorded_from": "2026-03-12T10:31:16Z",
    "recorded_until": "2026-03-12T10:31:58Z",
    "expires_at": "2026-04-11T10:31:58Z"
  }
}
```

**Errores:**

- `404` `not_found`: Ninguna sesión del proyecto tiene este id, o todavía no está procesada (dale 10 minutos).
- `410` `expired`: La sesión es más vieja que la retención del proyecto y se borró.

## Borrar una sesión

`DELETE /v1/sessions/{session}` \[Motor, Nube]

Borra para siempre la sesión, sus eventos, su grabación y sus capturas de página. Los conteos de los problemas y los números de rendimiento quedan como están: son totales y no guardan nada de la persona. La sesión sale de las listas de inmediato; los objetos guardados se quitan en menos de 24 horas.

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

**Parámetros de ruta:**

- `session` (string, obligatorio): El id de la sesión, 32 caracteres hexadecimales.

**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`.

**Petición:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/sessions/c4e1a8f3d7b24c69a0e5d3b1f9c7a5e3" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Errores:**

- `404` `not_found`: Ninguna sesión del proyecto tiene este id.

## Traer la línea de tiempo de una sesión

`GET /v1/sessions/{session}/events` \[Motor, Nube]

Los eventos de la sesión en el orden en que pasaron, cada uno con una frase en palabras simples (`text`) y sus detalles (`data`). Las peticiones que hizo el navegador vienen unidas a su traza del servidor (`trace_id`).

Lo que la persona escribió nunca está en una línea de tiempo, porque nunca se recoge: un clic en un campo se nombra por la etiqueta del campo. Los clics dentro de un elemento enmascarado no traen etiqueta.

Usa `notable=true` para traer solo lo que importa al leer una falla: vistas de página, clics, clics de rabia y muertos, errores, peticiones fallidas, fallas de formularios y eventos propios. Las peticiones exitosas y las métricas quedan por fuera.

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

**Parámetros de ruta:**

- `session` (string, obligatorio): El id de la sesión, 32 caracteres hexadecimales.

**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`.
- `types` (string, opcional): Tipos de evento que devolver, separados por comas: `page_view`, `page_leave`, `click`, `rage_click`, `dead_click`, `error`, `server_error`, `request`, `vital`, `form_invalid`, `custom`. Todos por defecto.
- `notable` (boolean, opcional, por defecto `false`): `true` deja por fuera las peticiones exitosas, las métricas y las salidas de página.
- `around` (timestamp, opcional): Una fecha ISO 8601. Devuelve los eventos alrededor de ese momento (la mitad de `limit` antes, la mitad después) en vez de empezar por el principio.
- `limit` (integer, 1 a 1,000, opcional, por defecto `200`): Máximo de eventos 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/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0/events?notable=true" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "at": "2026-03-12T10:31:16.004Z",
      "offset_ms": 0,
      "type": "page_view",
      "route": "/cart",
      "text": "Opened /cart",
      "data": {
        "navigation": "load",
        "from": null
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:28.412Z",
      "offset_ms": 12412,
      "type": "page_view",
      "route": "/checkout",
      "text": "Opened /checkout (from /cart)",
      "data": {
        "navigation": "push",
        "from": "/cart"
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:43.090Z",
      "offset_ms": 27090,
      "type": "click",
      "route": "/checkout",
      "text": "Clicked button «Pay $64.00» in «Your order»",
      "data": {
        "selector": "#pay-button",
        "role": "button",
        "label": "Pay $64.00",
        "context": "Your order",
        "href": null
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:45.310Z",
      "offset_ms": 29310,
      "type": "rage_click",
      "route": "/checkout",
      "text": "Clicked button «Pay $64.00» 4 more times",
      "data": {
        "selector": "#pay-button",
        "role": "button",
        "label": "Pay $64.00",
        "context": "Your order",
        "count": 4
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:47.000Z",
      "offset_ms": 31000,
      "type": "request",
      "route": "/checkout",
      "text": "POST /api/checkout answered 400 amount_required after 3,870 ms",
      "data": {
        "method": "POST",
        "path": "/api/checkout",
        "status": 400,
        "duration_ms": 3870,
        "code": "amount_required",
        "message": "amount is required"
      },
      "trace_id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:47.004Z",
      "offset_ms": 31004,
      "type": "error",
      "route": "/checkout",
      "text": "ApiError: POST /api/checkout failed with 400 (amount_required)",
      "data": {
        "name": "ApiError",
        "message": "POST /api/checkout failed with 400 (amount_required)",
        "source": "promise"
      },
      "trace_id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
      "problem_id": "prb_8f3k2m9x4q7w"
    },
    {
      "at": "2026-03-12T10:31:58.230Z",
      "offset_ms": 42230,
      "type": "page_leave",
      "route": "/checkout",
      "text": "Left /checkout after 30 s",
      "data": {
        "duration_ms": 29818,
        "scroll": 100
      },
      "trace_id": null,
      "problem_id": null
    }
  ],
  "omitted": {},
  "next_cursor": null
}
```

**Errores:**

- `404` `not_found`: Ninguna sesión del proyecto tiene este id.
- `410` `expired`: Los eventos de la sesión son más viejos que la retención del proyecto.

## Traer la grabación de una sesión

`GET /v1/sessions/{session}/replay` \[Motor, Nube]

Devuelve la grabación como una **ventana** de trozos, cada uno con un enlace que funciona 15 minutos. Tu cliente descarga los trozos directo del almacenamiento, en orden, y une sus `events` (eventos de rrweb) para reproducirlos. Una grabación nunca pasa por la API, porque una larga puede pesar más de 100 MB.

Una ventana siempre empieza en un trozo que tiene una captura completa de la página, así se puede reproducir desde su primer evento. Por defecto la ventana empieza al comienzo. Pasa `at` para empezar en la última captura completa anterior a un momento, por ejemplo la hora de un error. Una ventana trae tantos trozos como quepan en `max_bytes`. Cuando `window.has_more` es `true`, pide otra vez con `from_seq` igual a `window.next_seq`.

Los enlaces vencen. Cuando uno vence, el almacenamiento responde `403`: llama a este endpoint otra vez para tener enlaces nuevos.

`gaps` lista los tramos que no se grabaron (al SDK se le dijo que parara, o hubo trozos que nunca llegaron), para que un reproductor los muestre en vez de congelarse.

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

**Parámetros de ruta:**

- `session` (string, obligatorio): El id de la sesión, 32 caracteres hexadecimales.

**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`.
- `at` (timestamp, opcional): Una fecha ISO 8601 dentro de la sesión. La ventana empieza en la última captura completa de ese momento o anterior.
- `from_seq` (integer, 0 a 719, opcional): Empieza la ventana en este trozo. Usa el `window.next_seq` de la respuesta anterior. No se combina con `at`.
- `max_bytes` (integer, 1,000,000 a 40,000,000, opcional, por defecto `40000000`): Máximo de bytes comprimidos de trozos en la ventana.

**Petición:**

```bash
curl "https://api.sypnia.com/v1/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0/replay?at=2026-03-12T10:31:47Z" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta: Una ventana que empieza antes de la falla (200):**

```json
{
  "available": true,
  "session_id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "duration_ms": 42000,
  "recorded_from": "2026-03-12T10:31:16Z",
  "recorded_until": "2026-03-12T10:31:58Z",
  "mask": 1,
  "total_chunks": 5,
  "total_bytes": 412380,
  "window": {
    "from_seq": 0,
    "to_seq": 4,
    "starts_at": "2026-03-12T10:31:16Z",
    "ends_at": "2026-03-12T10:31:58Z",
    "bytes": 412380,
    "has_more": false,
    "next_seq": null
  },
  "chunks": [
    {
      "seq": 0,
      "starts_at": "2026-03-12T10:31:16Z",
      "ends_at": "2026-03-12T10:31:26Z",
      "bytes": 301204,
      "full": true,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000000.json.gz?X-Amz-Signature=…"
    },
    {
      "seq": 1,
      "starts_at": "2026-03-12T10:31:26Z",
      "ends_at": "2026-03-12T10:31:36Z",
      "bytes": 58110,
      "full": false,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000001.json.gz?X-Amz-Signature=…"
    },
    {
      "seq": 2,
      "starts_at": "2026-03-12T10:31:36Z",
      "ends_at": "2026-03-12T10:31:46Z",
      "bytes": 21930,
      "full": false,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000002.json.gz?X-Amz-Signature=…"
    },
    {
      "seq": 3,
      "starts_at": "2026-03-12T10:31:46Z",
      "ends_at": "2026-03-12T10:31:56Z",
      "bytes": 24716,
      "full": false,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000003.json.gz?X-Amz-Signature=…"
    },
    {
      "seq": 4,
      "starts_at": "2026-03-12T10:31:56Z",
      "ends_at": "2026-03-12T10:31:58Z",
      "bytes": 6420,
      "full": false,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000004.json.gz?X-Amz-Signature=…"
    }
  ],
  "gaps": [],
  "expires_at": "2026-03-12T10:50:00Z"
}
```

**Respuesta: Una sesión sin grabación (200):**

```json
{
  "available": false,
  "reason": "not_recorded",
  "session_id": "2b7d9e4f1a6c4830b5d2f7e9c1a3b5d7",
  "chunks": []
}
```

**Errores:**

- `400` `invalid_request`: `at` y `from_seq` juntos, o `at` por fuera de la sesión.
- `403` `forbidden`: El token no tiene el permiso `replay`.
- `404` `not_found`: Ninguna sesión del proyecto tiene este id.

## Listar personas

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

Las personas que usaron tu app en el rango de tiempo, con su actividad. Una persona existe desde que tu app llamó a `identify()` con un id. Los visitantes anónimos no aparecen aquí; se cuentan en `people` de los problemas y en el resumen, por dispositivo.

**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 `30d`): Solo personas activas después de este momento. Los conteos cubren este rango.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `account` (string, hasta 128 caracteres, opcional): Solo personas de esta cuenta.
- `q` (string, hasta 120 caracteres, opcional): Texto que buscar en el id, el nombre o el correo.
- `sort` (string, opcional, por defecto `last_seen`): `last_seen`, `sessions` o `trouble` (primero quienes tienen más sesiones con dificultades).
- `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/people?sort=trouble&since=7d" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "active": 412,
  "data": [
    {
      "id": "u_1042",
      "name": "Ada Park",
      "email": "ada@example.com",
      "account": {
        "id": "acc_77",
        "name": "Corner Café"
      },
      "first_seen": "2026-02-18T16:02:11Z",
      "last_seen": "2026-03-12T10:31:58Z",
      "sessions": 6,
      "trouble_sessions": 1,
      "errors": 1
    },
    {
      "id": "u_0977",
      "name": null,
      "email": null,
      "account": null,
      "first_seen": "2026-03-01T11:45:09Z",
      "last_seen": "2026-03-12T09:49:02Z",
      "sessions": 3,
      "trouble_sessions": 1,
      "errors": 2
    }
  ],
  "next_cursor": "eyJvIjoyfQ"
}
```

## Traer una persona

`GET /v1/people/{person_id}` \[Motor, Nube]

Una persona con su actividad en el rango y sus cinco sesiones más recientes. Para todas, lista sesiones con `person`.

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

**Parámetros de ruta:**

- `person_id` (string, hasta 128 caracteres, obligatorio): El id de la persona, tal como lo envió tu app. Codifícalo para URL.

**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 `30d`): Los conteos cubren este rango.

**Petición:**

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

**Respuesta (200):**

```json
{
  "id": "u_1042",
  "name": "Ada Park",
  "email": "ada@example.com",
  "account": {
    "id": "acc_77",
    "name": "Corner Café"
  },
  "first_seen": "2026-02-18T16:02:11Z",
  "last_seen": "2026-03-12T10:31:58Z",
  "sessions": 6,
  "trouble_sessions": 1,
  "errors": 1,
  "always_record": false,
  "latest_sessions": [
    {
      "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "started_at": "2026-03-12T10:31:16Z",
      "duration_ms": 42000,
      "trouble": true,
      "has_replay": true
    }
  ]
}
```

**Errores:**

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

## Borrar los datos de una persona

`DELETE /v1/people/{person_id}` \[Motor, Nube]

Borra todo lo que Sypnia tiene de una persona: su nombre y su correo, sus sesiones, eventos, grabaciones y capturas de página. Sirve para responder a una solicitud de eliminación de datos. Los totales (a cuántas personas afectó un problema, el rendimiento de una página) conservan sus números y no guardan nada de la persona.

La persona sale de todas las listas de inmediato. Los objetos guardados, incluidos los archivos de eventos crudos que tenían sus eventos, se reescriben sin ellos en menos de 24 horas. Si llegan eventos nuevos con el mismo id, la persona se crea otra vez: primero deja de enviarlos.

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

**Parámetros de ruta:**

- `person_id` (string, hasta 128 caracteres, obligatorio): El id de la persona, tal como lo envió tu app. Codifícalo para URL.

**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`.

**Petición:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/people/u_0977" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Respuesta (202):**

```json
{
  "person_id": "u_0977",
  "sessions": 3,
  "status": "deleting",
  "done_by": "2026-03-13T10:40:00Z"
}
```

**Errores:**

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

## Listar cuentas

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

Las cuentas (equipos, empresas, lo que tu app use para agrupar personas) que estuvieron activas en el rango, con su actividad. Una cuenta existe desde que tu app envió `account.id` con `identify()`. Un proyecto que nunca envía cuentas recibe una lista vacía.

**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 `30d`): Solo cuentas activas después de este momento. Los conteos cubren este rango.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `q` (string, hasta 120 caracteres, opcional): Texto que buscar en el id o el nombre.
- `sort` (string, opcional, por defecto `last_seen`): `last_seen`, `sessions`, `people` o `trouble`.
- `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/accounts?since=30d" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "id": "acc_77",
      "name": "Corner Café",
      "people": 14,
      "sessions": 96,
      "trouble_sessions": 4,
      "first_seen": "2026-02-03T08:11:40Z",
      "last_seen": "2026-03-12T10:02:19Z"
    }
  ],
  "next_cursor": null
}
```

## Traer una cuenta

`GET /v1/accounts/{account_id}` \[Motor, Nube]

Una cuenta con su actividad en el rango. Para sus personas, lista personas con `account`; para sus sesiones, lista sesiones con `account`.

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

**Parámetros de ruta:**

- `account_id` (string, hasta 128 caracteres, obligatorio): El id de la cuenta, tal como lo envió tu app. Codifícalo para URL.

**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 `30d`): Los conteos cubren este rango.

**Petición:**

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

**Respuesta (200):**

```json
{
  "id": "acc_77",
  "name": "Corner Café",
  "people": 14,
  "sessions": 96,
  "trouble_sessions": 4,
  "first_seen": "2026-02-03T08:11:40Z",
  "last_seen": "2026-03-12T10:02:19Z",
  "always_record": false
}
```

**Errores:**

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

## Listar eventos propios

`GET /v1/custom-events` \[Motor, Nube]

Los eventos que tu app envió con `track(name, props)`, por nombre, con cuántas veces ocurrió cada uno en el rango. Para ver las sesiones detrás de uno, lista sesiones con `event`. Un proyecto guarda hasta 500 nombres distintos; los eventos con un nombre nuevo por encima de eso quedan en sus sesiones y no se cuentan aquí.

**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`): Los conteos cubren este rango.
- `until` (string, opcional): Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.
- `name` (string, hasta 80 caracteres, opcional): Solo nombres que empiezan con este texto.
- `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/custom-events?since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Respuesta (200):**

```json
{
  "data": [
    {
      "name": "checkout_started",
      "count": 58,
      "sessions": 51,
      "people": 49,
      "last_seen": "2026-03-12T10:31:28Z"
    },
    {
      "name": "order_paid",
      "count": 31,
      "sessions": 31,
      "people": 30,
      "last_seen": "2026-03-12T07:52:10Z"
    }
  ],
  "next_cursor": null
}
```

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).
