InicioGuíasReferencia de la API
API de Analytics

Notas de la versión

Cambios en la API pública de Analytics, de los más recientes a los más antiguos.

Versión 1.7.3 (2026-06-23)

Mejoras

  • User-Agent ahora es un encabezado obligatorio: Toda solicitud debe incluir un User-Agent no vacío que identifique tu integración (junto con X-Api-Token y X-Api-Version). Las solicitudes sin él se rechazan en el edge, antes de llegar a la API. Define un valor estable y descriptivo, como mi-integracion/1.0.

    curl https://analytics.vturb.com/quota/usage \
  -H 'X-Api-Token: <token>' \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: mi-integracion/1.0'

Versión 1.7.2 (2026-05-15)

Mejoras

  • Nuevo dominio de la API analytics.vturb.com: La API ahora está disponible en https://analytics.vturb.com, que es nuestro nuevo dominio canónico. Actualmente, ambos dominios sirven la misma API, así que hoy no se rompe nada.

    Te recomendamos encarecidamente migrar tu integración a analytics.vturb.com lo antes posible. El dominio anterior, https://analytics.vturb.net, queda obsoleto y se retirará a lo largo de 2026. Aún no tenemos una fecha exacta de apagado — en cuanto se defina, la anunciaremos aquí con antelación. Para migrar, basta con cambiar la URL base de tu integración de analytics.vturb.net a analytics.vturb.com; no se requiere ningún otro cambio (la autenticación, los endpoints y los payloads siguen siendo los mismos).

Versión 1.7.1 (2026-05-07)

Correcciones de errores

  • /headlines/stats_by_player, /turbo/stats_by_player, /smart_autoplays/stats_by_player ahora respetan end_date: Estos tres endpoints descartaban silenciosamente el parámetro end_date y siempre devolvían datos desde start_date hasta "ahora", lo que producía totales inflados, casi acumulados — algo especialmente visible cuando se solicitaba una ventana corta del pasado. Ahora end_date se aplica como límite superior sobre events.created_at, sessions.created_at, times.created_at y conversions.click_created_at. El límite es inclusivo hasta el final del minuto, así que pasar 23:59:59 (o 23:59:59.999) para el último minuto de un día captura correctamente todos los eventos de ese día. end_date sigue siendo opcional — quien lo omita (o lo envíe vacío) obtiene el comportamiento anterior, sin límite, así que las integraciones existentes no se ven afectadas; si end_date está presente pero tiene un formato incorrecto, la solicitud devuelve 400.

Versión 1.7.0 (2026-04-27)

Nuevas funcionalidades

  • Nuevo endpoint GET /quota/usage: Devuelve el estado actual de la cuota de ClickHouse para tu API key — una entrada por intervalo de cuota (normalmente uno por minuto y otro por día). Para cada intervalo obtienes interval_seconds, interval_starts_at, interval_ends_at y { used, limit, remaining } tanto para queries como para read_bytes. Úsalo desde tu cliente para autolimitar tu ritmo de solicitudes antes de lanzar solicitudes de analytics costosas.

    Notas:

    • Cuando ClickHouse define una cuota como ilimitada (valor bruto 0), la respuesta muestra limit: null y remaining: null para que no dividas entre cero.
    • Una sola llamada a la API puede contar como más de una consulta frente a max_queries_per_minute, así que este contador puede subir más rápido que tu ritmo de solicitudes. La respuesta incluye queries.note para señalarlo. read_bytes refleja los datos realmente escaneados y es la señal más fiable para dimensionar tu uso.
    • El propio endpoint cuenta como 1 consulta frente a max_queries_per_minute.
    GET /quota/usage
    {
  "quotas": [
    {
      "interval_seconds": 60,
      "interval_starts_at": "2026-04-27T12:34:00Z",
      "interval_ends_at":   "2026-04-27T12:35:00Z",
      "queries":    { "used": 20, "limit": 60, "remaining": 40, "note": "a single API request may count as more than one query against this limit" },
      "read_bytes": { "used": 92535478, "limit": null, "remaining": null }
    }
  ]
}

Mejoras

  • details estructurado en 429 Too Many Requests: Cuando una solicitud falla porque la API key agotó una cuota de ClickHouse (code: 201), la respuesta ahora incluye un objeto details junto al texto de error que ya existía:

    {
  "error": "Query quota exceeded for this API key. ...",
  "code": 201,
  "details": {
    "limit_kind": "queries",
    "used": 60,
    "limit": 60,
    "remaining": 0,
    "interval_seconds": 60,
    "resets_at": "2026-04-27T12:35:00Z"
  }
}

    Los campos error y code anteriores no cambian, así que los clientes existentes que dependen de ellos siguen funcionando. Los SDK y los paneles ahora pueden mostrar "reintentar después de resets_at" en lugar de tratar la limitación como algo opaco.

Versión 1.6.0 (2026-04-27)

Nuevas funcionalidades

  • Búsqueda por nombre en /players/list: El endpoint ahora acepta un filtro opcional name y un modo opcional name_match (contains (predeterminado), starts_with, ends_with o exact). La búsqueda no distingue entre mayúsculas y minúsculas — incluso en letras con diacríticos (JOSÉ coincide con José Silva). Los caracteres especiales como %, _, \ y [] se tratan de forma literal, así que una consulta como name=[campaign_1] devuelve solo los reproductores cuyo nombre contiene exactamente esa etiqueta. name debe tener entre 3 y 128 caracteres después de eliminar los espacios de los extremos; enviar name_match sin name devuelve 400.

Ejemplo de uso

GET /players/list?name=campaign_1
GET /players/list?name=Black&name_match=starts_with
GET /players/list?name=_v2&name_match=ends_with
GET /players/list?name=[VSL]%20Black%20Friday&name_match=exact

Correcciones de errores

  • /comparison_groups/stats ya no devuelve 500 ante búsquedas de reproductores vacías transitorias: Una inconsistencia breve en las tablas subyacentes de reproductores/vídeos (normalmente de unos segundos) se guardaba en caché durante una hora entera, lo que hacía que todas las solicitudes posteriores fallaran con Engagement is invalid by :valid? (invalid: video_ids). Ahora el endpoint se degrada de forma controlada — devuelve métricas de engagement a cero en lugar de un error — y la caché de analytics ya no guarda resultados vacíos, así que un fallo transitorio puntual se recupera en la siguiente solicitud.

Versión 1.5.0 (2026-04-20)

Nuevas funcionalidades

  • Nuevo endpoint /comparison_groups/list: Lista las pruebas A/B (comparison groups) registradas para tu empresa. Cada entrada incluye el nombre de la prueba, los reproductores inscritos con sus porcentajes de tráfico y las marcas de tiempo de inicio/fin. Los resultados se ordenan por fecha de creación (los más recientes primero) y se pueden acotar con los filtros opcionales start_date / end_date.
  • Nuevo endpoint /comparison_groups/stats: Devuelve el conjunto completo de métricas de analytics para hasta 2 reproductores de una prueba A/B en una sola solicitud — views, plays, finishes, clicks, conversiones (con ingresos en USD, BRL y EUR), engagement, pitch retention y las métricas derivadas play rate, conversion rate e ingresos por visitante (RPV). El start_date de cada elemento es opcional — si se omite, se usa el started_at del propio reproductor (de la lista de reproductores de la prueba A/B) y, si ese no está definido, el started_at del comparison group. Si se omite end_date, los resultados llegan hasta el momento actual.

Solicitud

  • Hasta 2 items por solicitud (las pruebas A/B se comparan por pares).
  • Cada elemento: { player_id (required), start_date (YYYY-MM-DD HH:MM:SS, optional), end_date (optional) }.
  • events es opcional y su valor predeterminado es ["started", "viewed", "finished"].
  • timezone es opcional (el valor predeterminado es Etc/UTC). Si se define, cada cadena start_date / end_date — las que pasas en items y las predeterminadas que se resuelven a partir del comparison group — se interpreta en esa zona horaria al ejecutarse la consulta.

Respuesta

{
  "comparison_group": {
    "id": "...",
    "name": "...",
    "player_ids": ["...", "..."],
    "started_at": "2026-02-26 00:41:00",
    "finished_at": null
  },
  "stats": [
    {
      "player_id": "...",
      "pitch_time": 1317,
      "video_duration": 1732,
      "views": { "total": 12626, "total_uniq_sessions": 11491, "total_uniq_device": 11411 },
      "plays": { "total": 9984, "total_uniq_sessions": 9587, "total_uniq_device": 9574 },
      "finishes": { "total": 286, "total_uniq_sessions": 284, "total_uniq_device": 283 },
      "clicks": { "total": 515, "total_uniq_sessions": 488, "total_uniq_device": 485 },
      "conversions": {
        "total": 17,
        "total_uniq_sessions": 17,
        "total_uniq_device": 17,
        "total_amount_usd": 3740.0,
        "total_amount_brl": 19329.57,
        "total_amount_eur": 3179.82
      },
      "engagement": {
        "average_watched_time": 842.3,
        "engagement_rate": 48.63,
        "grouped_timed": [
          { "timed": 0, "total_users": 1420 },
          { "timed": 5, "total_users": 980 }
        ]
      },
      "pitch_audience": 2411,
      "pitch_retention_rate": 23.57,
      "play_rate": 83.89,
      "conversion_rate": 0.18,
      "rpv_usd": 0.3907,
      "rpv_brl": 2.019,
      "rpv_eur": 0.3322
    }
  ]
}
  • comparison_group.player_ids devuelve todos los reproductores registrados en la prueba A/B, aunque solicites estadísticas solo de un subconjunto.
  • Los elementos cuyo player_id no forma parte del comparison group se descartan silenciosamente; la solicitud falla con 422 solo cuando no queda ningún elemento válido.
  • Un comparison_group_id que no pertenece a tu cuenta devuelve 404.
  • Los campos de ingresos (conversions.total_amount_{usd,brl,eur} y rpv_{usd,brl,eur}) se devuelven en unidades monetarias principales (dólares, reales, euros) como floats — p. ej., 3740.0 significa USD $3,740.00.

Ejemplo de uso

# 1. List the company's AB tests
curl -X POST https://{host}/comparison_groups/list \
  -H 'X-Api-Token: <token>' \
  -H 'X-Api-Version: v1' \
  -H 'Content-Type: application/json' \
  -d '{"start_date":"2026-01-01 00:00:00"}'

# 2. Pull stats for up to 2 players
curl -X POST https://{host}/comparison_groups/stats \
  -H 'X-Api-Token: <token>' \
  -H 'X-Api-Version: v1' \
  -H 'Content-Type: application/json' \
  -d '{
        "comparison_group_id": "699f9683dfeab82d6246e13b",
        "items": [
          {"player_id": "699f92f01dd8bb9e2b6aab3a", "start_date": "2026-02-26 00:41:00"},
          {"player_id": "699f9363c4b02ade5c5f1881", "start_date": "2026-02-26 00:41:00"}
        ]
      }'

Versión 1.4.4 (2025-08-05)

Mejoras de rendimiento

  • Endpoint de usuarios activos: El endpoint de usuarios activos excluía a los usuarios que estaban navegando por la página; ahora, si el usuario estuvo en la página en los últimos X minutos, debe contarse (y se contará). El endpoint sigue filtrando lo que identificamos como bots.

Versión 1.4.3 (2025-08-04)

Mejoras de rendimiento

  • Optimización de caché para los endpoints de analytics: Se implementaron mejoras significativas de caché en todos los endpoints de analytics para reducir la carga de la base de datos y mejorar los tiempos de respuesta:
    • Normalización de fechas: Se añadió un procesamiento de todos los parámetros de fecha para garantizar aciertos de caché consistentes dentro del mismo minuto
    • Consistencia entre endpoints: Se aplicaron patrones de optimización de caché en todos los ejecutores de analytics, incluidos los endpoints de sesiones, eventos, conversiones, clics, tiempos, origen del tráfico, titulares, Smart Autoplay y Turbo

Versión 1.4.2 (2025-08-03)

Correcciones de errores

  • El endpoint /sessions/stats tenía un problema al consultar una fecha con el mismo día/hora de inicio y de fin, lo que hacía que el endpoint fallara.

Versión 1.4.1 (2025-08-01)

Correcciones de errores

  • El endpoint /sessions/live_users tenía un problema por el que la caché se mantenía durante 60 minutos de forma predeterminada. La corrección incluye ahora una caché de 30 segundos con una estrategia de revalidación de 15 segundos. Esto debería bastar para consultar usuarios activos.

Versión 1.4.0 (2025-07-29)

Nuevas funcionalidades

  • Nuevo endpoint /sessions/live_users: Se añadió una funcionalidad de seguimiento de usuarios activos en tiempo real que ofrece analíticas por dominio de los usuarios activos en este momento:
    • Seguimiento de la actividad en tiempo real: Supervisa la actividad de los usuarios dentro de una ventana de tiempo configurable (1-720 minutos)
    • Agrupación por dominio: Agrupa a los usuarios activos por dominio para entender la distribución del tráfico
    • Validación de sesiones: Solo cuenta las sesiones de las últimas 12 horas con actividad reciente
    • Filtrado de bots: Excluye automáticamente el tráfico de bots para obtener recuentos de usuarios precisos
    • Resultados ordenados: Devuelve los dominios ordenados por número de usuarios activos en orden descendente

Ejemplo de uso

# Get live users from the last 60 minutes (default)
GET /sessions/live_users?player_id=64a5c8072e6fd10009828db2

# Get live users from the last 30 minutes
GET /sessions/live_users?player_id=64a5c8072e6fd10009828db2&minutes=30

# Get live users from the last 2 hours
GET /sessions/live_users?player_id=64a5c8072e6fd10009828db2&minutes=120

Detalles de los parámetros

  • player_id (obligatorio): El ID del reproductor cuya actividad de usuarios activos quieres supervisar
  • minutes (opcional): Ventana de tiempo en minutos que se considera actividad reciente. Debe estar entre 1 y 720. El valor predeterminado es 60 minutos

Formato de respuesta

[
  {
    "domain": "example.com",
    "live_users": 15
  },
  {
    "domain": "test.com",
    "live_users": 8
  },
  {
    "domain": "another-site.com",
    "live_users": 3
  }
]

Comprender el seguimiento de usuarios activos

El endpoint funciona así:

  1. Filtrado de sesiones: Identifica las sesiones de las últimas 12 horas que no provienen de bots
  2. Validación de la actividad: Comprueba si hay actividad reciente (registros de times) dentro de la ventana de minutos especificada
  3. Agrupación por dominio: Agrupa las sesiones activas por dominio
  4. Agregación de recuentos: Cuenta las sesiones únicas por dominio para determinar el número de usuarios activos
  5. Ordenación de resultados: Devuelve los dominios ordenados por número de usuarios activos (de mayor a menor)

Manejo de errores

  • 400 Bad Request: Devuelve mensajes de error detallados para los parámetros no válidos:
    • Formato de player_id no válido
    • Minutos fuera del rango válido (1-720)
  • 401 Unauthorized: Mantiene los requisitos de autenticación existentes

Casos de uso

Este endpoint te permite:

  • Supervisión en tiempo real: Seguir el engagement actual de los usuarios en distintos dominios
  • Análisis de tráfico: Entender qué dominios atraen más usuarios activos
  • Optimización del rendimiento: Identificar los dominios con mucho tráfico para asignar recursos
  • Insights de marketing: Supervisar la eficacia de las campañas en tiempo real
  • Decisiones operativas: Tomar decisiones inmediatas según la actividad actual de los usuarios
  • Sistemas de alertas: Crear sistemas de supervisión para patrones de tráfico inusuales

Versión 1.3.0 (2025-07-18)

Nuevas funcionalidades

  • Endpoint /players/list mejorado con filtrado por fecha: Se añadieron parámetros de consulta opcionales para mejorar el filtrado de reproductores:
    • Filtrado por rango de fechas: Se añadieron los parámetros start_date y end_date para filtrar los reproductores por fecha de creación
    • Soporte de zona horaria: Se añadió el parámetro timezone para filtrar fechas con precisión en distintas zonas horarias
    • Validación de parámetros: Se añadió una validación completa de los parámetros de fecha para garantizar un formato datetime correcto
    • Compatibilidad con versiones anteriores: Todos los parámetros nuevos son opcionales, así que las integraciones existentes siguen funcionando sin cambios

Características principales

El endpoint /players/list mejorado ahora admite:

  • Filtrado por fecha: Filtra los reproductores creados dentro de un rango de fechas específico con los parámetros start_date y end_date
  • Manejo de zona horaria: Especifica la zona horaria para calcular las fechas con precisión (UTC de forma predeterminada si no se indica)

Ejemplo de uso

# Basic request (unchanged)
GET /players/list

# Filter players created in the last 30 days
GET /players/list?start_date=2023-10-01 00:00:00&end_date=2023-10-31 23:59:59

# Filter with timezone specification
GET /players/list?start_date=2023-10-01 00:00:00&end_date=2023-10-31 23:59:59&timezone=America/Sao_Paulo

# Filter players created after a specific date
GET /players/list?start_date=2023-10-01 00:00:00&timezone=America/Sao_Paulo

Detalles de los parámetros

  • start_date (opcional): Fecha de inicio del periodo para filtrar reproductores. Usa la comparación >=. Admite formatos como "2023-10-26 18:24:05" o "2023-10-26 18:24:05 UTC"
  • end_date (opcional): Fecha de fin del periodo para filtrar reproductores. Usa la comparación <=. Admite los mismos formatos de fecha que start_date
  • timezone (opcional): Zona horaria que se usa para filtrar por fecha. El valor predeterminado es 'Etc/UCT' si no se especifica

Formato de respuesta

El formato de respuesta no cambia, lo que garantiza la compatibilidad con versiones anteriores:

[
  {
    "id": "player1",
    "name": "My Player",
    "pitch_time": 0,
    "duration": 3600,
    "created_at": "2025-07-18T10:00:00Z"
  }
]

Casos de uso

Esta mejora te permite:

  • Analíticas basadas en el tiempo: Filtrar los reproductores creados dentro de campañas o periodos específicos
  • Informes: Generar informes de los reproductores creados durante periodos comerciales específicos
  • Auditoría: Seguir los patrones de creación de reproductores a lo largo del tiempo
  • Gestión de datos: Consultar reproductores de forma eficiente según sus marcas de tiempo de creación

Versión 1.2.0 (2025-06-27)

Nuevas funcionalidades

  • Nuevo endpoint /sessions/stats_by_day: Se añadieron analíticas diarias completas de sesiones que ofrecen estadísticas detalladas desglosadas por día dentro de un rango de fechas especificado.

Características principales

El endpoint /sessions/stats_by_day ofrece:

  • Métricas diarias de sesiones: Total de visualizaciones, inicios, finalizaciones y clics agregados por día
  • Seguimiento de usuarios únicos: Recuentos separados de sesiones únicas y dispositivos únicos en todas las métricas
  • Análisis de engagement: Cálculo de la tasa de engagement basado en el tiempo medio de visualización
  • Análisis del umbral del pitch: Registra a los usuarios que vieron por encima/por debajo del umbral del pitch time
  • Seguimiento de conversiones: Recuentos diarios de conversiones con importes en varias monedas (USD, BRL, EUR)
  • Cálculo de la tasa de reproducción: Porcentaje de espectadores que empezaron a reproducir después de la visualización
  • Filtrado por rango de fechas: Filtrado flexible por fechas con soporte de zona horaria

Ejemplo de solicitud

{
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "start_date": "2023-01-01 00:00:00",
  "end_date": "2023-01-31 23:59:59",
  "timezone": "America/Sao_Paulo",
  "video_duration": 3600,
  "pitch_time": 30
}

Ejemplo de respuesta

[
  {
    "date_key": "2023-01-01",
    "total_viewed": 200,
    "total_viewed_device_uniq": 180,
    "total_viewed_session_uniq": 190,
    "total_started": 250,
    "total_started_session_uniq": 230,
    "total_started_device_uniq": 220,
    "total_finished": 150,
    "total_finished_session_uniq": 140,
    "total_finished_device_uniq": 130,
    "engagement_rate": 75.56,
    "total_clicked": 50,
    "total_clicked_device_uniq": 45,
    "total_clicked_session_uniq": 40,
    "total_over_pitch": 30,
    "total_under_pitch": 10,
    "over_pitch_rate": 75.0,
    "total_conversions": 10,
    "overall_conversion_rate": 2.56,
    "total_amount_usd": 1000,
    "total_amount_brl": 1000,
    "total_amount_eur": 1000,
    "play_rate": 2.56
  },
  {
    "date_key": "2023-01-02",
    "total_viewed": 180,
    "total_viewed_device_uniq": 160,
    "total_viewed_session_uniq": 170,
    "total_started": 220,
    "total_started_session_uniq": 210,
    "total_started_device_uniq": 200,
    "total_finished": 130,
    "total_finished_session_uniq": 120,
    "total_finished_device_uniq": 110,
    "engagement_rate": 72.3,
    "total_clicked": 40,
    "total_clicked_device_uniq": 35,
    "total_clicked_session_uniq": 30,
    "total_over_pitch": 25,
    "total_under_pitch": 8,
    "over_pitch_rate": 75.76,
    "total_conversions": 8,
    "overall_conversion_rate": 2.27,
    "total_amount_usd": 800,
    "total_amount_brl": 800,
    "total_amount_eur": 800,
    "play_rate": 2.27
  }
]

Comprender las métricas diarias

El endpoint /sessions/stats_by_day ofrece desgloses diarios detallados de:

  • Métricas de sesión: Recuentos completos de visualizaciones, inicios, finalizaciones y clics para cada día
  • Seguimiento de únicos: Recuentos únicos separados por sesión y dispositivo para entender el comportamiento de los usuarios
  • Análisis de engagement: Tasas de engagement diarias que muestran qué parte del vídeo ven los usuarios
  • Rendimiento del pitch: Análisis diario de cuántos usuarios ven más allá de tu umbral de pitch
  • Seguimiento de conversiones: Datos completos de conversión con importes monetarios en varias monedas
  • Análisis de tendencias: Comparación día a día para identificar patrones y tendencias

Casos de uso

Este endpoint te permite:

  • Seguir las tendencias diarias de rendimiento: Supervisar cómo varía el engagement día a día
  • Identificar los días de mayor rendimiento: Encontrar qué días generan más engagement y conversiones
  • Analizar patrones estacionales: Entender cómo cambia el comportamiento de los usuarios con el tiempo
  • Seguimiento del rendimiento de las campañas: Medir el impacto diario de las campañas de marketing
  • Optimización del contenido: Identificar qué días tienen tasas de engagement más altas para planificar el contenido
  • Análisis de conversiones: Seguir los patrones diarios de conversión y las tendencias de ingresos
  • Insights sobre el comportamiento de los usuarios: Entender los patrones de visualización en distintos días de la semana o del mes

Versión 1.1.0 (2025-06-25)

Nuevas funcionalidades

  • Se amplió el endpoint /custom_metrics/list con mejoras significativas:
    • Nuevo método POST: Se añadió un endpoint POST en /custom_metrics/list para gestionar mejor los parámetros
    • Cálculo de la tasa de engagement: Ahora calcula y devuelve la tasa de engagement de cada métrica personalizada
    • Filtrado por rango de fechas: Se añadieron los parámetros opcionales start_date y end_date para filtrar las métricas por periodo
    • Soporte de zona horaria: Se añadió el parámetro timezone para filtrar fechas con precisión en distintas zonas horarias
    • Analíticas de usuarios ampliadas: Devuelve total_users, users_above y engagement_rate para cada métrica personalizada

Ruta de migración

El endpoint GET original /custom_metrics/{player_id}/list ahora está obsoleto y se eliminará el 25 de julio de 2025. Migra al nuevo endpoint POST.

Ejemplo de solicitud (nuevo método POST)

{
  "player_id": "64a5c8072e6fd10009828db2",
  "start_date": "2023-01-01 00:00:00",
  "end_date": "2023-12-31 23:59:59",
  "timezone": "America/Sao_Paulo"
}

Ejemplo de respuesta (ampliada con datos de engagement)

[
  {
    "id": "685acdfa39be67017b9be72d",
    "name": "Custom Metric 1",
    "time": 600,
    "sequential_number": 1,
    "engagement_rate": 18.18,
    "total_users": 55,
    "users_above": 10
  },
  {
    "id": "685acdfa39be67017b9be72e",
    "name": "Custom Metric 2",
    "time": 1200,
    "sequential_number": 2,
    "engagement_rate": 12.73,
    "total_users": 55,
    "users_above": 7
  }
]

Comprender las nuevas métricas

El endpoint mejorado ahora ofrece analíticas de engagement detalladas:

  • engagement_rate: Porcentaje de usuarios que vieron más allá de la marca de tiempo de la métrica personalizada
  • total_users: Número total de usuarios que vieron el vídeo en el periodo especificado
  • users_above: Número de usuarios que vieron más allá de la marca de tiempo de esta métrica personalizada
  • Filtrado por fecha: Cuando se proporcionan start_date y end_date, las analíticas se calculan solo para las sesiones dentro de ese periodo
  • Manejo de zona horaria: Las fechas se tratan correctamente según la zona horaria especificada

Casos de uso

Esta mejora te permite:

  • Analizar la retención a lo largo del tiempo: Comparar las tasas de engagement de las mismas métricas personalizadas en distintos periodos
  • Seguir patrones estacionales: Usar el filtrado por fecha para entender cómo varía el engagement de los usuarios según la temporada o los periodos de campaña
  • Calcular tasas de retención precisas: Obtener los porcentajes exactos de usuarios que alcanzan cada hito personalizado
  • Generar informes basados en el tiempo: Crear informes periódicos que muestren las tendencias de engagement en momentos clave del vídeo
  • Pruebas A/B: Comparar las tasas de engagement de distintas versiones de vídeo o campañas de marketing

Cambios incompatibles

  • Aviso de obsolescencia: El endpoint GET /custom_metrics/{player_id}/list está obsoleto y se eliminará el 25 de julio de 2025
  • Migración necesaria: Las aplicaciones que usan el endpoint GET deben migrar al nuevo endpoint POST antes de la fecha de obsolescencia

Versión 1.0.9 (2025-06-24)

Nuevas funcionalidades

  • Se añadió el nuevo endpoint /sessions/stats, que ofrece estadísticas completas de sesiones para un reproductor específico:
    • Devuelve métricas de sesión detalladas, incluidos el total de visualizaciones, inicios, finalizaciones y clics
    • Ofrece recuentos de sesiones únicas y dispositivos únicos para cada tipo de métrica
    • Calcula las tasas de engagement y las métricas de conversión
    • Incluye un análisis del pitch time que muestra los usuarios que vieron por encima/por debajo del umbral del pitch
    • Devuelve datos de conversión con importes en varias monedas (USD, BRL, EUR)
    • Admite el filtrado por rango de fechas y la configuración de la zona horaria

Ejemplo de solicitud

{
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "start_date": "2023-01-01 00:00:00",
  "end_date": "2024-01-31 23:59:59",
  "timezone": "America/Sao_Paulo",
  "video_duration": 3600,
  "pitch_time": 30
}

Ejemplo de respuesta

{
  "total_viewed": 200,
  "total_viewed_device_uniq": 180,
  "total_viewed_session_uniq": 190,
  "total_started": 250,
  "total_started_session_uniq": 230,
  "total_started_device_uniq": 220,
  "total_finished": 150,
  "total_finished_session_uniq": 140,
  "total_finished_device_uniq": 130,
  "engagement_rate": 75.56,
  "total_clicked": 50,
  "total_clicked_device_uniq": 45,
  "total_clicked_session_uniq": 40,
  "total_over_pitch": 30,
  "total_under_pitch": 10,
  "over_pitch_rate": 75,
  "total_conversions": 10,
  "overall_conversion_rate": 2.56,
  "total_amount_usd": 1000,
  "total_amount_brl": 1000,
  "total_amount_eur": 1000,
  "play_rate": 2.56
}

Comprender las métricas

El endpoint /sessions/stats ofrece varias métricas clave:

  • Métricas de visualización: Total de visualizaciones y visualizaciones únicas por sesión y dispositivo
  • Métricas de engagement: Tasas de inicio/finalización y porcentajes generales de engagement
  • Análisis del pitch: Muestra cuántos usuarios vieron más allá del umbral de pitch time configurado
  • Datos de conversión: Métricas de conversión completas con importes monetarios en varias monedas
  • Tasa de reproducción: Porcentaje de espectadores que empezaron a reproducir el vídeo después de la visualización

Este endpoint es especialmente útil para:

  • Obtener una visión general completa del rendimiento del reproductor
  • Analizar los patrones de engagement de los usuarios
  • Entender la eficacia de las conversiones
  • Seguir la retención en el umbral del pitch
  • Comparar el rendimiento entre distintos periodos

Versión 1.0.8 (2025-06-17)

Mejoras

  • Se corrigió un problema por el que, a veces, al obtener el listado de reproductores (/players/list) algunos valores podían aparecer duplicados

Versión 1.0.7 (2025-06-05)

Mejoras

  • Se amplió el endpoint /players/list con información adicional del reproductor:
    • Se añadió el campo pitch_time para mostrar la configuración de pitch time del reproductor
    • Se añadió el campo duration para mostrar la duración del vídeo asociado
    • Mantiene la compatibilidad con las implementaciones existentes

Ejemplo de respuesta

[
  {
    "id": "player1",
    "name": "My Player",
    "pitch_time": 0,
    "duration": 3600,
    "created_at": "2025-06-05T10:00:00Z"
  }
]

Versión 1.0.6 (2025-05-30)

Nuevas funcionalidades

  • Se añadió el nuevo endpoint /custom_metrics/{player_id}/list, que ofrece una lista de todas las métricas personalizadas de un reproductor específico:
    • Devuelve la información de cada métrica personalizada, incluidos el ID, el nombre, el tiempo y el número secuencial
    • Permite seguir puntos de tiempo específicos del vídeo para analizar la retención
    • Permite calcular los porcentajes de engagement de los usuarios en marcas de tiempo específicas del vídeo

Ejemplo de respuesta

[
  {
    "id": "metric1",
    "name": "First Key Point",
    "time": 30,
    "sequential_number": 1
  },
  {
    "id": "metric2",
    "name": "Second Key Point",
    "time": 60,
    "sequential_number": 2
  }
]

Comprender las métricas personalizadas y el engagement de los usuarios

El endpoint de métricas personalizadas funciona junto con el endpoint /times/user_engagement para ayudar a calcular las tasas de retención en marcas de tiempo específicas del vídeo. Así se usan juntos:

  1. Primero, lista tus métricas personalizadas para las marcas de tiempo importantes del vídeo con el endpoint /custom_metrics/{player_id}/list
  2. Después, usa el endpoint /times/user_engagement para obtener el número de usuarios en cada marca de tiempo proporcionando:
    • player_id: El ID de tu reproductor
    • video_duration: Duración total del vídeo en segundos
    • start_date y end_date: El periodo que quieres analizar
    • timezone: Tu zona horaria preferida para filtrar por fecha

Ejemplo de solicitud a /times/user_engagement:

{
  "start_date": "2023-10-26 18:24:05",
  "end_date": "2023-11-26 18:24:05",
  "player_id": "65fb3c74ab21c70007b3e0dd",
  "video_duration": 3600,
  "timezone": "America/Sao_Paulo"
}
  1. El endpoint de engagement de usuarios devolverá, para cada segundo del vídeo, cuántos usuarios dejaron de verlo ahí, en el punto más lejano al que llegaron
  2. Después puedes calcular la retención en la marca de tiempo de cada métrica personalizada sumando los usuarios de ese segundo y de todos los segundos siguientes, y comparando la suma con el número total de usuarios

Por ejemplo, si tienes:

  • Total de usuarios: 100
  • Usuarios que se detuvieron a los 30 segundos (First Key Point) o después: 80
  • Usuarios que se detuvieron a los 60 segundos (Second Key Point) o después: 50

Las tasas de retención serían:

  • First Key Point: 80% (80/100)
  • Second Key Point: 50% (50/100)

Esta combinación te permite:

  • Seguir el engagement de los usuarios en puntos específicos y significativos de tu vídeo
  • Calcular tasas de retención para hitos personalizados
  • Analizar cuántos usuarios llegan a los momentos clave de tu vídeo
  • Tomar decisiones basadas en datos sobre el contenido y la duración del vídeo

Versión 1.0.5 (2025-05-28)

Nuevas funcionalidades

  • Se añadió el nuevo endpoint /players/list, que ofrece una lista de todos los reproductores que pertenecen a la empresa del usuario autenticado:
    • Devuelve información básica de los reproductores, incluidos el ID, el nombre y la fecha de creación
    • Filtra automáticamente los reproductores según la empresa del usuario autenticado
    • Admite el formato de respuesta JSON

Ejemplo de respuesta

[
  {
    "id": "player1",
    "name": "My Player",
    "created_at": "2025-05-28T10:00:00Z"
  }
]

Versión 1.0.4 (2025-05-27)

Nuevas funcionalidades

  • Se añadió el nuevo endpoint /events/leaderboard, que ofrece rankings de reproductores basados en métricas de engagement del vídeo:
    • Admite varios rankings con distintos límites de reproductores en una sola solicitud
    • Permite filtrar por tipos de evento (started, finished, viewed, clicked, paused)
    • Incluye métricas de total de reproducciones, reproducciones únicas por sesión y reproducciones únicas por dispositivo
    • Admite el filtrado por rango de fechas con fecha de fin opcional

Ejemplo de solicitud

{
  "company_id": "2b884cba-0b12-42ce-b3a1-7a3182d414df",
  "leaderboards": [
    {
      "leaderboard_limit": 10,
      "start_date": "2023-10-26",
      "end_date": "2023-11-26",
      "event": "finished"
    },
    {
      "leaderboard_limit": 5,
      "start_date": "2023-09-26",
      "event": "started"
    }
  ],
  "timezone": "America/Sao_Paulo"
}

Ejemplo de respuesta

[
  {
    "leaderboard_name": "leaderboard_10",
    "event": "finished",
    "leaderboards": [
      {
        "player_id": "player1",
        "total_plays": 100,
        "uniq_plays": 50,
        "uniq_device_plays": 25
      }
    ]
  }
]

Versión 1.0.3 (2025-05-15)

Mejoras

  • Se mejoró el rendimiento de los siguientes endpoints:
    • /events/total_by_company_day

Explicación detallada

A veces, al hacer una solicitud al endpoint, los usuarios se quedaban sin recursos sin que la solicitud fuera en realidad tan pesada. Esto se debía a la forma en que el endpoint agregaba los datos; ahora las solicitudes deberían quedar normalizadas y usar la cantidad adecuada de recursos.

Versión 1.0.2 (2025-05-15)

Mejoras

  • Se mejoró el manejo de errores para las excepciones que se producen cuando la solicitud usa más recursos de los permitidos según el plan de la empresa:
    • Se añadió un manejo explícito para AUTHENTICATION_FAILED
    • Se añadió un manejo explícito para MEMORY_LIMIT_EXCEEDED

Ejemplos de respuestas de error 401 - No autorizado

Cuando una empresa no tiene acceso a la API:

{
  "error": "This company does not have access to the public analytics API.",
  "code": 516
}

Cuando una consulta supera los límites de recursos del nivel del plan de la empresa:

{
  "error": "Your api key tier is not enough to perform this query. Please contact support at [email protected]",
  "code": 241
}

Versión 1.0.1 (2025-05-15)

Correcciones de errores

  • Se corrigió el manejo de la zona horaria en el endpoint /sessions/stats_by_field_by_day para garantizar que las fechas se informen de forma consistente en distintas zonas horarias. Esto afecta a cómo se calculan las fechas en las siguientes métricas:
    • Estadísticas de sesiones por día
    • Tasas de conversión
    • Marcas de tiempo de los eventos
    • Agregaciones por fecha

Ejemplo de la corrección

Antes de esta corrección, al usar la zona horaria "America/Sao_Paulo" (GMT-3), los eventos que ocurrían el mismo día podían dividirse en dos fechas distintas debido a problemas de conversión de zona horaria. Por ejemplo:

// Before the fix
{
    "grouped_field": "United States",
    "total_viewed": 100,
    "date_key": "2025-05-13"  // Some events from May 14 were incorrectly grouped here
},
{
    "grouped_field": "United States",
    "total_viewed": 200,
    "date_key": "2025-05-14"  // Only some events from May 14 were here
}

Ahora, todos los eventos del mismo día se agrupan correctamente, sin importar la zona horaria especificada en la solicitud:

// After the fix
{
  "grouped_field": "United States",
  "total_viewed": 300, // All events from May 14 are now correctly grouped
  "date_key": "2025-05-14"
}

Nota: Esta versión incluye correcciones y mejoras de funcionalidades existentes sin introducir nuevas funcionalidades ni cambios incompatibles.

Fuentes de tráfico y UTMs

Compara campañas, fuentes y anuncios por visualizaciones, retención, pitch y ventas

Devuelve las plataformas activas de una empresa POST

Devuelve los nombres de las plataformas, como `kiwify`, que registraron conversiones para la empresa desde `start_date`.

En esta página

Versión 1.7.3 (2026-06-23)MejorasVersión 1.7.2 (2026-05-15)MejorasVersión 1.7.1 (2026-05-07)Correcciones de erroresVersión 1.7.0 (2026-04-27)Nuevas funcionalidadesMejorasVersión 1.6.0 (2026-04-27)Nuevas funcionalidadesEjemplo de usoCorrecciones de erroresVersión 1.5.0 (2026-04-20)Nuevas funcionalidadesSolicitudRespuestaEjemplo de usoVersión 1.4.4 (2025-08-05)Mejoras de rendimientoVersión 1.4.3 (2025-08-04)Mejoras de rendimientoVersión 1.4.2 (2025-08-03)Correcciones de erroresVersión 1.4.1 (2025-08-01)Correcciones de erroresVersión 1.4.0 (2025-07-29)Nuevas funcionalidadesEjemplo de usoDetalles de los parámetrosFormato de respuestaComprender el seguimiento de usuarios activosManejo de erroresCasos de usoVersión 1.3.0 (2025-07-18)Nuevas funcionalidadesCaracterísticas principalesEjemplo de usoDetalles de los parámetrosFormato de respuestaCasos de usoVersión 1.2.0 (2025-06-27)Nuevas funcionalidadesCaracterísticas principalesEjemplo de solicitudEjemplo de respuestaComprender las métricas diariasCasos de usoVersión 1.1.0 (2025-06-25)Nuevas funcionalidadesRuta de migraciónEjemplo de solicitud (nuevo método POST)Ejemplo de respuesta (ampliada con datos de engagement)Comprender las nuevas métricasCasos de usoCambios incompatiblesVersión 1.0.9 (2025-06-24)Nuevas funcionalidadesEjemplo de solicitudEjemplo de respuestaComprender las métricasVersión 1.0.8 (2025-06-17)MejorasVersión 1.0.7 (2025-06-05)MejorasEjemplo de respuestaVersión 1.0.6 (2025-05-30)Nuevas funcionalidadesEjemplo de respuestaComprender las métricas personalizadas y el engagement de los usuariosVersión 1.0.5 (2025-05-28)Nuevas funcionalidadesEjemplo de respuestaVersión 1.0.4 (2025-05-27)Nuevas funcionalidadesEjemplo de solicitudEjemplo de respuestaVersión 1.0.3 (2025-05-15)MejorasExplicación detalladaVersión 1.0.2 (2025-05-15)MejorasEjemplos de respuestas de error 401 - No autorizadoVersión 1.0.1 (2025-05-15)Correcciones de erroresEjemplo de la corrección