Docs

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 MotorNube Al lanzar

Ver como Markdown
En esta página
  1. El objeto sesión
  2. El objeto evento de sesión
  3. El objeto persona
  4. El objeto cuenta
  5. Listar sesiones
  6. Traer una sesión
  7. Borrar una sesión
  8. Traer la línea de tiempo de una sesión
  9. Traer la grabación de una sesión
  10. Listar personas
  11. Traer una persona
  12. Borrar los datos de una persona
  13. Listar cuentas
  14. Traer una cuenta
  15. Listar eventos propios

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 MotorNube

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

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Solo sesiones que empezaron después de este momento.

    Por defecto: 7d

  • until
    string opcional

    Fin del rango de tiempo. Una fecha ISO 8601 o un valor relativo. Por defecto, ahora.

  • trouble
    boolean opcional

    true devuelve solo las sesiones con dificultades.

    Por defecto: false

  • 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

    recent (última actividad primero), trouble (más dificultades primero) o longest (las más largas).

    Por defecto: recent

  • limit
    integer, 1 a 200 opcional

    Máximo de elementos que se devuelven.

    Por defecto: 50

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

Terminal
curl "https://api.sypnia.com/v1/sessions?trouble=true&route=/checkout&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

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} MotorNube

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

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

Respuesta200

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

  • 404not_found

    Ninguna sesión del proyecto tiene este id, o todavía no está procesada (dale 10 minutos).

  • 410expired

    La sesión es más vieja que la retención del proyecto y se borró.

Borrar una sesión

DELETE /v1/sessions/{session} MotorNube

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

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

Errores

  • 404not_found

    Ninguna sesión del proyecto tiene este id.

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

GET /v1/sessions/{session}/events MotorNube

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

    true deja por fuera las peticiones exitosas, las métricas y las salidas de página.

    Por defecto: false

  • 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

    Máximo de eventos que se devuelven.

    Por defecto: 200

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

Terminal
curl "https://api.sypnia.com/v1/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0/events?notable=true" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

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

  • 404not_found

    Ninguna sesión del proyecto tiene este id.

  • 410expired

    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 MotorNube

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

    Máximo de bytes comprimidos de trozos en la ventana.

    Por defecto: 40000000

Petición

Terminal
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 falla200

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ón200

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

Errores

  • 400invalid_request

    at y from_seq juntos, o at por fuera de la sesión.

  • 403forbidden

    El token no tiene el permiso replay.

  • 404not_found

    Ninguna sesión del proyecto tiene este id.

Listar personas

GET /v1/people MotorNube

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

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Solo personas activas después de este momento. Los conteos cubren este rango.

    Por defecto: 30d

  • 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

    last_seen, sessions o trouble (primero quienes tienen más sesiones con dificultades).

    Por defecto: last_seen

  • limit
    integer, 1 a 200 opcional

    Máximo de elementos que se devuelven.

    Por defecto: 50

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

Terminal
curl "https://api.sypnia.com/v1/people?sort=trouble&since=7d" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

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} MotorNube

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

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Los conteos cubren este rango.

    Por defecto: 30d

Petición

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

Respuesta200

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

  • 404not_found

    Ninguna persona del proyecto tiene este id.

Borrar los datos de una persona

DELETE /v1/people/{person_id} MotorNube

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

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

Respuesta202

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

Errores

  • 404not_found

    Ninguna persona del proyecto tiene este id.

Listar cuentas

GET /v1/accounts MotorNube

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

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Solo cuentas activas después de este momento. Los conteos cubren este rango.

    Por defecto: 30d

  • 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

    last_seen, sessions, people o trouble.

    Por defecto: last_seen

  • limit
    integer, 1 a 200 opcional

    Máximo de elementos que se devuelven.

    Por defecto: 50

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

Terminal
curl "https://api.sypnia.com/v1/accounts?since=30d" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

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} MotorNube

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

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Los conteos cubren este rango.

    Por defecto: 30d

Petición

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

Respuesta200

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

  • 404not_found

    Ninguna cuenta del proyecto tiene este id.

Listar eventos propios

GET /v1/custom-events MotorNube

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

    El entorno que se lee. Cualquier nombre que el proyecto haya enviado, o all.

    Por defecto: production

  • since
    string opcional

    Los conteos cubren este rango.

    Por defecto: 7d

  • 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

    Máximo de elementos que se devuelven.

    Por defecto: 50

  • cursor
    string opcional

    El next_cursor de la página anterior. Deja iguales todos los demás parámetros.

Petición

Terminal
curl "https://api.sypnia.com/v1/custom-events?since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"

Respuesta200

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.

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar