Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Métricas de video de TikTok por API: vistas, tiempo de visualización y finalización

La API for Business de TikTok devuelve las métricas acumuladas de cada publicación desde GET /business/video/list/, pedidas por nombre en fields: video_views, reach, likes, comments, shares y favorites, total_time_watched y average_time_watched en segundos, full_video_watched_rate, video_view_retention, impression_sources y desgloses de espectadores como audience_countries. La mayoría de los conteos llegan con 24 a 48 horas de retraso y dejan de actualizarse 365 días después de publicar.

easyCoexistence lee las métricas de un video de TikTok con get_social_insights desde Claude, ChatGPT o tu propio código: indica los campos que quieras, como video_views, reach o full_video_watched_rate, y el item_id del video.

video.insights

Permiso necesario para el tiempo de visualización, la finalización, la retención, las fuentes de tráfico y los desgloses de espectadores; los conteos básicos necesitan video.list.

7 days

Inactividad tras la cual el alcance, el tiempo de visualización, las fuentes de tráfico y audience_countries pueden faltar en un video.

10

Mayoría de las entradas de las listas audience_countries y audience_cities de un video.

24 to 48 h

Retraso habitual de video_views, likes, alcance, tiempo de visualización y fuentes de tráfico, en UTC.

¿Qué métricas tiene un video?

GET /business/video/list/ devuelve estas para cada publicación indicada en fields, agregadas a lo largo de toda la vida de la publicación y no en la ventana de 60 días de las métricas de cuenta. Los conteos, como vistas y likes, necesitan el scope video.list en el token, mientras que las cifras de visualización, finalización y retención necesitan video.insights:

video_viewsViews, counted on the first playback in an impression session
reachPeople who watched the post at least once
likes, comments, sharesLifetime totals; shares include sends to friends inside TikTok
favoritesTimes the post was added to favorites
total_time_watchedSeconds viewers spent watching, in total
average_time_watchedAverage seconds viewers spent watching
full_video_watched_rateShare of viewers who finished the video
video_view_retentionShare of viewers still watching at each second
impression_sourcesWhere viewers found the post, by share
new_followersViewers who started following the account
engagement_likesShare of viewers who liked at each second
video_durationLength of the video in seconds

¿Cómo se piden?

Indícalas en fields, un array JSON que debe incluir item_id siempre que liste más de un campo, y elige las publicaciones con filters.video_ids. Sin el filtro, el endpoint recorre las publicaciones de la cuenta, de 20 en 20:

Metrics for one video
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
  -H 'Access-Token: <ACCESS_TOKEN>' \
  --data-urlencode 'business_id=<OPEN_ID>' \
  --data-urlencode 'fields=["item_id","video_views","reach","video_duration","total_time_watched","average_time_watched","full_video_watched_rate","impression_sources","audience_countries"]' \
  --data-urlencode 'filters={"video_ids":["<ITEM_ID>"]}'

¿Cómo es la respuesta?

Un array videos con un objeto por publicación y los campos pedidos, más cursor y has_more para la paginación. El ejemplo de TikTok, recortado, muestra las unidades: tiempos de visualización en segundos con hasta tres decimales, y full_video_watched_rate como decimal, 0.0237 en este caso:

A video's metrics, from TikTok's example
{
  "code": 0,
  "message": "OK",
  "request_id": "2021080307532501024502410704A7306F",
  "data": {
    "videos": [
      {
        "item_id": "6990565363377392901",
        "video_views": 1231,
        "reach": 154,
        "likes": 10,
        "comments": 2,
        "shares": 0,
        "video_duration": 20.0,
        "total_time_watched": 695.942,
        "average_time_watched": 4.118,
        "full_video_watched_rate": 0.0237,
        "impression_sources": [
          { "impression_source": "For You", "percentage": 0.8983 },
          { "impression_source": "Personal Profile", "percentage": 0.0904 },
          { "impression_source": "Follow", "percentage": 0.0113 }
        ],
        "audience_countries": [
          { "country": "US", "percentage": 0.7574 },
          { "country": "GB", "percentage": 0.1775 }
        ]
      }
    ],
    "cursor": 0,
    "has_more": false
  }
}

¿Qué significan las fuentes de tráfico?

impression_sources ordena desde la mayor hasta la menor proporción el lugar donde los espectadores descubrieron la publicación; cada entrada es un impression_source con su porcentaje. TikTok documenta estos valores:

  • For You: el feed For You.
  • Follow: el feed Follow.
  • Sound: páginas de sonidos.
  • Personal Profile: páginas de perfil.
  • Search: páginas de búsqueda.
  • Direct Message: mensajes directos, cuando TikTok Studio muestra esos datos para la cuenta.
  • Others: todo lo demás.

¿Qué desgloses de espectadores hay?

Cuatro, todos describen a las personas que vieron esa publicación y no a los seguidores de la cuenta, y todos necesitan video.insights:

  • audience_genders: proporción de espectadores por género, Female, Male u Other.
  • audience_countries: hasta 10 países o regiones, en códigos ISO 3166-1 alpha-2.
  • audience_cities: hasta 10 ciudades, con nombres como US Cincinnati.
  • audience_types: NEW_VIEWER y RETURN_VIEWER, y FOLLOWER_PERCENT frente a NON_FOLLOWER_PERCENT.

¿Qué métricas dependen del tipo de cuenta?

Algunos clics y visitas al perfil provienen de Business Analytics de TikTok y necesitan algo más que una cuenta personal. profile_views, las visitas al perfil que generó una publicación, necesita una cuenta con Advanced Access o una Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks y address_clicks necesitan una Verified Business Account.

¿Por qué puede faltar o llegar tarde una métrica?

Porque TikTok calcula la mayoría fuera de línea y solo a partir de TikTok Analytics. Los conteos y las métricas de visualización suelen retrasarse de 24 a 48 horas, mientras que item_id, caption y links son en tiempo real. El alcance, el tiempo de visualización, las fuentes de tráfico y audience_countries pueden faltar en un video que nadie ha visto, con like, comentado o compartido durante 7 días; el consejo de TikTok es interactuar con él y reintentar tras 24 a 48 horas. Los datos dejan de actualizarse 365 días después de publicar, y las publicaciones filtradas por infracciones, como derechos de autor musicales, no se devuelven.

¿Cómo lee easyCoexistence las métricas de un video?

Con get_social_insights: indica el item_id del video como object_id y los nombres de los campos como metrics, y devuelve los campos de esa publicación, buscando entre las 20 publicaciones más recientes de la cuenta. Para una publicación más antigua, tu propio código llama a business/video/list/ con fields y filters.video_ids como parámetros, usando el token de get_social_credentials.

One video's metrics through MCP
get_social_insights {
  "account_id": "<ACCOUNT_ID>",
  "object_id": "<ITEM_ID>",
  "metrics": ["video_views", "reach", "average_time_watched", "full_video_watched_rate", "impression_sources"]
}

Errores comunes

  • Suponer una sola escala para todos los porcentajes. Los ejemplos de TikTok dan impression_sources como fracciones que suman 1, mientras que su ejemplo de audience_cities muestra valores como 17.4921.
  • Pedir varios campos sin item_id. La referencia de TikTok advierte que una petición así puede fallar.
  • Esperar alcance en un video antiguo y tranquilo. TikTok puede dejar vacíos el alcance, el tiempo de visualización y las fuentes de tráfico tras 7 días sin vistas, likes, comentarios o compartidos.
  • Comparar métricas de publicación con métricas diarias de cuenta. Las cifras de una publicación cubren toda su vida, mientras que las métricas de cuenta llegan por día durante hasta 60 días.
Hacerlo con EasyCoexistence

Para las publicaciones antiguas, get_social_credentials entrega a tu propio código el token de la cuenta. De US$ 9 a US$ 0.75 por conexión al mes, según agregas más conexiones, con los primeros 3 días gratis.

Preguntas frecuentes

¿La API de TikTok devuelve el tiempo de visualización por video?

Sí. total_time_watched y average_time_watched llegan en segundos desde /business/video/list/, con tokens que tienen el scope video.insights.

¿Cómo obtengo la tasa de finalización de un video de TikTok por API?

Pide full_video_watched_rate en fields en /business/video/list/. TikTok la define como el porcentaje de espectadores que terminan de ver el video.

¿Por qué aparecen vacíos el alcance y el tiempo de visualización de mi video de TikTok?

TikTok puede omitirlos en un video sin vistas, likes, comentarios ni compartidos en los últimos 7 días, y los datos recientes se retrasan de 24 a 48 horas.

¿La API puede devolver métricas de un video de TikTok concreto?

Sí. Pasa su ID en filters.video_ids, con item_id y las métricas que quieras en fields.

Sigue leyendo

Conecta tu primer canal en dos minutos.

Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.

  • 3 días gratis
  • Cancela cuando quieras
  • Solo APIs oficiales
  • Monitorizado 24/7

Verificado el