Listar los videos de una cuenta de TikTok a través de la API
La API de TikTok for Business lista las publicaciones públicas de una cuenta con GET /business/video/list/, desde las más recientes, hasta 20 por página. Indica los campos que quieres recibir, como item_id, caption, share_url y video_views, y avanza con cursor mientras has_more sea true. filters.video_ids selecciona publicaciones concretas, y cada item_id es el ID que usan las llamadas de comentarios.
easyCoexistence lista las publicaciones recientes de una cuenta de TikTok con list_social_posts desde Claude, ChatGPT o tu propio código, con el item_id, la descripción, el enlace y los contadores de cada publicación, y get_social_credentials entrega a tu propio código el token para las páginas siguientes y otros campos.
Máximo de publicaciones que devuelve /business/video/list/ por página; max_count tiene 10 por defecto.
Unidad del cursor: una marca de tiempo Unix en UTC; el endpoint devuelve las publicaciones publicadas antes de ella.
El campo predeterminado, que una petición con varios campos debe incluir o puede producir un error.
Llamadas permitidas por cuenta autorizada en este endpoint, igual que en cada endpoint de la Accounts API.
¿Qué devuelve el endpoint?
Las publicaciones públicas de la cuenta: videos que se muestran en su perfil, publicaciones de foto y texto, y videos Only show in ads, que se emiten como anuncios sin aparecer en el perfil. media_type distingue VIDEO de PHOTO, que cubre las publicaciones de foto y texto. Las publicaciones que TikTok filtró por infracciones, como derechos de autor musicales, no aparecen en la lista.
¿Cómo se llama?
Con un GET y parámetros en la URL: business_id, fields como arreglo JSON y, opcionalmente, filters, cursor y max_count, que por defecto es 10. El token va en el encabezado Access-Token, y la app de desarrollador necesita el permiso Get Account Media en TikTok Accounts:
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","create_time","media_type","caption","share_url","thumbnail_url","video_views","likes","comments","shares"]' \
--data-urlencode 'max_count=20'¿Qué campos describen una publicación?
Además de las métricas, que van desde video_views hasta impression_sources, la lista incluye estos campos, todos bajo el scope video.list:
item_id: el ID de la publicación, que usan las llamadas de comentarios y filters.video_ids.media_type: VIDEO, o PHOTO para una publicación de foto o texto.is_ad: indica si la publicación se usa en un anuncio.create_time: cuándo se publicó, en segundos Unix en UTC.- caption: la descripción de la publicación, con sus hashtags.
share_url: un enlace para compartir, que se comporta de forma distinta en móvil y en escritorio.embed_url: un enlace de reproductor para otros sitios, que no reproduce las publicaciones configuradas como Friends o Only you.thumbnail_url: una imagen de vista previa temporal cuyo vencimiento está en su parámetro x-expires.video_duration: la duración en segundos, con tres decimales.
¿Cómo es una página de resultados?
Un arreglo videos en el orden que devuelve TikTok, más cursor, el valor que se envía para la siguiente página, y has_more, que indica si hay una. create_time llega como cadena de segundos Unix. Este es el ejemplo de TikTok, recortado a los campos descriptivos y a los contadores:
{
"code": 0,
"message": "OK",
"request_id": "2021080307532501024502410704A7306F",
"data": {
"videos": [
{
"item_id": "6990565363377392901",
"create_time": "1627617835",
"caption": "little coco",
"share_url": "https://www.tiktok.com/@feather_in_the_w1nd/video/6990565363377392901?utm_campaign=tt4d_open_api&utm_source=6979330045630218242",
"likes": 10,
"comments": 2,
"shares": 0,
"video_views": 1231
}
],
"cursor": 0,
"has_more": false
}
}¿Cómo funciona la paginación?
Por tiempo. cursor toma por defecto el momento actual en milisegundos, así que la primera página contiene las publicaciones más recientes, y cada respuesta devuelve el cursor para la siguiente petición. Envíalo mientras has_more sea true. Una marca de tiempo personalizada lista las publicaciones publicadas antes de ese momento, y las reglas de confianza y seguridad de TikTok pueden hacer que una página tenga menos de max_count aunque queden más publicaciones.
import json, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
def all_posts(token: str, business_id: str, fields: list[str]):
params = {"business_id": business_id, "fields": json.dumps(fields), "max_count": 20}
while True:
r = requests.get(f"{API}/business/video/list/", headers={"Access-Token": token},
params=params, timeout=30).json()
if r["code"] != 0:
raise RuntimeError(f"{r['code']}: {r['message']}")
yield from r["data"].get("videos", [])
if not r["data"].get("has_more"):
return
params["cursor"] = r["data"]["cursor"]¿Cómo se obtienen publicaciones concretas?
Con filters, un objeto JSON: video_ids enumera los IDs de las publicaciones a devolver, como los post_ids de un estado de publicación. ad_post_only, válido solo junto a video_ids, conserva únicamente las publicaciones autorizadas para anunciantes en Spark Ads. Una petición filtrada recibe los mismos campos que cualquier otra, así que una sola llamada puede devolver las cifras más recientes de unas pocas publicaciones conocidas.
filters={"video_ids":["6995316737801538821","8015388216995316737"]}¿Qué límites aplican?
La Accounts API permite 40 llamadas por minuto para cada cuenta autorizada en este endpoint, y las llamadas a la Accounts API de una app suman 600 por minuto en el nivel Basic y 1,000 por encima de ese nivel. Los campos descriptivos son en tiempo real, los contadores suelen retrasarse de 24 a 48 horas, y los datos de una publicación dejan de actualizarse 365 días después de publicada.
¿Cómo lista easyCoexistence los videos?
Con list_social_posts, que recibe account_id y un limit opcional, de 1 a 20 para TikTok. Devuelve la primera página de TikTok: las publicaciones más recientes con item_id, create_time, caption, share_url, thumbnail_url, video_views, likes, comments y shares, más cursor y has_more. Las páginas siguientes y otros campos salen de tu propio código, con el token y el business_id de get_social_credentials:
GET https://business-api.tiktok.com/open_api/v1.3/business/video/list/
?business_id=<BUSINESS_ID>
&fields=["item_id","media_type","caption","embed_url"]
&cursor=1793404800000
&max_count=20
Access-Token: <ACCESS_TOKEN>Errores comunes
- Pedir campos sin item_id. La referencia de TikTok advierte que una petición con varios campos sin él puede fallar.
- Detenerse cuando una página llega corta. TikTok puede devolver menos de max_count publicaciones aunque has_more siga en true, así que sigue has_more en su lugar.
- Guardar thumbnail_url para después. Es un enlace temporal que vence en el momento indicado en su parámetro x-expires, así que pide uno nuevo cuando lo necesites.
- Buscar publicaciones privadas en la lista. El endpoint devuelve solo publicaciones públicas.
De US$ 9 a US$ 0.75 por conexión al mes, que baja a medida que añades conexiones, con los primeros 3 días gratis.
Preguntas frecuentes
¿Cuántos videos de TikTok puede listar la API a la vez?
Hasta 20 por página desde /business/video/list/. max_count define el tamaño de página y por defecto es 10; sigue cursor para obtener más.
¿La API de TikTok también lista publicaciones de foto?
Sí. /business/video/list/ devuelve publicaciones públicas de video, foto y texto, y media_type distingue VIDEO de PHOTO.
¿La lista de videos de TikTok incluye publicaciones solo para anuncios?
Sí. /business/video/list/ también devuelve los videos Only show in ads, que se emiten como anuncios sin aparecer en el perfil, e is_ad indica si una publicación se usa en un anuncio.
¿Por qué falta una publicación de TikTok en la lista de la API?
El endpoint lista publicaciones públicas, y TikTok deja fuera las publicaciones filtradas por infracciones, como derechos de autor musicales.
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