Verifique su lista de cuentas de TikTok por lotes con SocQ y organice los nombres de usuario, el estado en vivo y la hora de cada verificación en una sola tabla. Actualícela según su programación, compare las observaciones y conecte los cambios detectados con un panel de creadores o un flujo de recordatorios.
La TikTok User Live API de SocQ verifica el estado por nombre de usuario y devuelve un registro por cada consulta exitosa. Esta guía cubre las solicitudes por lotes, la exportación de una tabla de estados y el código de detección de cambios.
Respuesta rápida: Envíe un arreglo
usernamesno vacío aPOST /v1/tiktok/user-live. Cuando la tarea termine con éxito, leais_liveystatusendata.results.items. Un resultado exitoso sin transmisión tieneis_live=falseystatus=offline; una tarea verifica el estado en el momento en que se ejecuta y luego termina.
Verificar si un usuario de TikTok está en vivo por nombre de usuario
Defina SOCQ_API_KEY y envíe el identificador de una cuenta:
curl -X POST "https://api.socq.ai/v1/tiktok/user-live" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["thejustalex"]}'
Use identificadores de cuenta, con o sin @. Para un lote, coloque varios identificadores distintos en el mismo arreglo:
{"usernames":["thejustalex","@tiktok"]}
User Live parte de nombres de usuario. Guarde data.task_id como TASK_ID y luego consulte esa tarea:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued, running y retrying indican que la tarea de recopilación sigue pendiente. Después del éxito, lea is_live para determinar el estado de la cuenta. Si falla, revise data.error_message. Conserve el ID de la tarea para reanudar la obtención de resultados tras un tiempo de espera agotado del cliente.
Distinguir cuentas sin transmisión, valores ausentes y consultas fallidas
| Observación | Interpretación | Comportamiento de la aplicación |
|---|---|---|
is_live=true, status=live | La consulta exitosa informó una transmisión activa | Mostrar en vivo con su hora de recopilación |
is_live=false, status=offline | La consulta exitosa informó que no hay una transmisión activa | Mostrar sin transmisión con su hora de recopilación |
| El título de una sala o una métrica es null | Ese detalle no está disponible | Dejarlo vacío |
| Falla de la tarea o ningún registro utilizable para una entrada | No hay un estado nuevo utilizable para esa cuenta | Mostrar una verificación fallida o desconocida, no sin transmisión |
Los registros de transmisiones activas usan title, author, media y metrics.viewers_count para el título, el creador, la portada y el número de espectadores. Los campos que omite la fuente siguen siendo null; un cero numérico devuelto sigue siendo 0.
Este fragmento muestra los campos de un registro de estado sin transmisión:
{
"id": "6742945285876515845",
"type": "live_status",
"is_live": false,
"status": "offline",
"title": null,
"author": {"id": "6742945285876515845", "username": "thejustalex"},
"metrics": null,
"media": [],
"collected_at": "2026-10-15T08:12:57.773115Z"
}
Esta muestra presenta la estructura del registro sin transmisión. Al consultar la misma tarea se recupera esa observación guardada. Cree una nueva tarea de User Live para actualizar el estado de una cuenta.
Crear una lista de estados actualizable con Python
Guarde el siguiente asistente de tareas como socq_collect.py. Usa la biblioteca estándar y lee todas las páginas de resultados cuando la tarea termina con éxito:
import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen
BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}
def api(method, path, payload=None):
body = json.dumps(payload).encode("utf-8") if payload is not None else None
request = Request(
BASE + path, data=body, method=method,
headers={
"Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=60) as response:
result = json.load(response)
if result.get("code") != 200:
raise RuntimeError(result)
return result["data"]
def collect(endpoint, payload):
task_id = api("POST", "/" + endpoint, payload)["task_id"]
print("Task:", task_id, flush=True)
path = "/tasks/" + task_id
deadline = time.monotonic() + 600
data = api("GET", path + "?limit=100")
while data["status"] in PENDING:
if time.monotonic() >= deadline:
raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
time.sleep(2)
data = api("GET", path + "?limit=100")
if data["status"] != "succeeded":
raise RuntimeError(data.get("error_message") or data["status"])
items, seen_cursors = [], set()
while True:
if time.monotonic() >= deadline:
raise TimeoutError("Resume pagination for " + task_id)
page = data["results"]
items.extend(page["items"])
if not page["has_more"]:
return task_id, items
cursor = page.get("next_cursor")
if not cursor or cursor in seen_cursors:
raise RuntimeError("Missing or repeated result cursor")
seen_cursors.add(cursor)
data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
if data["status"] != "succeeded":
raise RuntimeError("Task is not ready for result pagination")
Guarde este verificador de una sola ejecución como check_live.py en el mismo directorio. Cambie la lista de cuentas según su aplicación:
import csv
import json
from datetime import datetime
from pathlib import Path
from socq_collect import collect
usernames = ["thejustalex", "@tiktok"]
requested = {u.strip().lstrip("@").casefold() for u in usernames}
state_path = Path("live-status-state.json")
previous = json.loads(state_path.read_text()) if state_path.exists() else {}
state = dict(previous)
task_id, items = collect("tiktok/user-live", {"usernames": usernames})
with open("live-status-results.json", "w", encoding="utf-8") as f:
json.dump({"task_id": task_id, "input": {"usernames": usernames}, "items": items},
f, ensure_ascii=False, indent=2)
def timestamp(value):
try:
parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
return parsed if parsed.tzinfo else None
except (AttributeError, TypeError, ValueError):
return None
def csv_cell(value):
if value is None:
return ""
if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
return "'" + value
return value
rows, observed, went_live = [], set(), []
for item in items:
author = item.get("author") or {}
username = (author.get("username") or "").lstrip("@").casefold()
live = item.get("is_live")
checked = timestamp(item.get("collected_at"))
if username not in requested or type(live) is not bool or checked is None:
continue
old = state.get(username) or {}
old_checked = timestamp(old.get("collected_at"))
if old_checked is not None and checked <= old_checked:
continue
same_account = bool(author.get("id")) and old.get("author_id") == author["id"]
if same_account and old.get("is_live") is False and live is True:
went_live.append(username)
state[username] = {"author_id": author.get("id"), "is_live": live,
"collected_at": item["collected_at"]}
observed.add(username)
rows.append({"username": username, "status": "live" if live else "offline",
"viewers_count": (item.get("metrics") or {}).get("viewers_count"),
"collected_at": item["collected_at"]})
state_path.write_text(json.dumps(state, ensure_ascii=False, indent=2), encoding="utf-8")
with open("live-status.csv", "w", encoding="utf-8-sig", newline="") as f:
fields = ["username", "status", "viewers_count", "collected_at"]
writer = csv.DictWriter(f, fieldnames=fields)
writer.writeheader()
writer.writerows({k: csv_cell(v) for k, v in row.items()} for row in rows)
print(json.dumps({"went_live_since_previous_check": went_live,
"without_new_usable_status": sorted(requested - observed)}))
python3 check_live.py
Cada ejecución completa un lote. El código compara los ID de cuenta y las horas de recopilación: la primera observación establece una línea base, se registra un cambio de sin transmisión a en vivo para la misma cuenta, y las observaciones más antiguas o repetidas conservan el estado anterior. Las cuentas sin un registro nuevo conservan su estado y hora de verificación anteriores.
El CSV almacena las observaciones nuevas de esta ejecución. El archivo de estado conserva la última observación aceptada de cada cuenta. Muestre en su interfaz la hora de verificación junto con el estado. Si la tarea falla, el programa se detiene antes de escribir el archivo de estado.
Agregar notificaciones de cambios en su aplicación
El ejemplo escribe en went_live_since_previous_check los nombres de usuario que pasaron de sin transmisión a en vivo. Su aplicación puede leer esa lista y ejecutar su flujo de notificaciones. Use el ID de la cuenta más la hora de la transición observada como clave de notificación para deduplicar los reintentos de entrega.
Dos verificaciones establecen un intervalo en el que cambió un estado, y collected_at registra la hora de la observación. Defina el intervalo de actualización según sus requisitos de actualidad y el costo de las consultas repetidas. Para comprobar transmisiones que comenzaron y terminaron entre dos verificaciones se necesitan datos históricos aparte.
callback_url informa la finalización de una tarea de recopilación. Su aplicación programa nuevas tareas de User Live para las verificaciones posteriores y activa los recordatorios comparando los estados guardados.
Elegir entre estado en vivo y detalles de la sala en vivo
Use User Live cuando parta de nombres de usuario y quiera una lista de estados. TikTok Live Room Info es una consulta independiente para una sala y un usuario conocidos; use sus entradas documentadas para obtener detalles a nivel de sala.
Este tutorial exporta nombres de usuario, estado, hora de verificación y el número de espectadores proporcionado por la fuente. Consulte el tutorial de scraping de TikTok para flujos de cuentas, videos y comentarios, o la búsqueda de videos y fotos de TikTok para el descubrimiento de contenido.
Adaptar las verificaciones en vivo a su programación operativa
SocQ User Live toma una lista de nombres de usuario mediante un único flujo de consulta y devuelve campos de estado estándar. Combínelo con el código de guardado de estado y detección de cambios para programar verificaciones, actualizar su panel de creadores y enviar recordatorios desde su aplicación. Usted define la programación de actualización.
Abra User Live y verifique su lista de cuentas.
Preguntas frecuentes (FAQ)
¿Cómo verifico si un usuario de TikTok está en vivo?
Envíe el identificador en usernames a TikTok User Live, espere a que la tarea termine con éxito e inspeccione is_live. Use collected_at para mostrar cuándo se observó ese estado.
¿Puedo verificar varias cuentas a la vez?
Sí. Coloque varios identificadores de cuentas públicas en usernames. Haga coincidir los resultados con author.id o author.username; marque una entrada sin registro devuelto como “no se obtuvo estado en esta verificación”.
¿Un resultado sin transmisión es un error y se factura?
Que no haya transmisión es un resultado exitoso de la consulta y se factura como un registro de estado devuelto. Consulte la página de la User Live API para ver la facturación vigente.
¿La API sigue monitoreando hasta que alguien inicia una transmisión?
Cada tarea ejecuta una verificación y termina. Su aplicación programa nuevas tareas y compara las observaciones devueltas para las verificaciones continuas.
¿Por qué el número de espectadores y el título de la sala están vacíos?
Los campos de una sala sin transmisión pueden estar vacíos. Las mediciones que la fuente omite en salas activas también siguen siendo null. Use is_live y status para leer el estado informado de la cuenta.
¿Un callback de finalización me avisa cada vez que un creador inicia una transmisión?
Un callback de finalización corresponde a una sola tarea. Los recordatorios de inicio de transmisión requieren verificaciones programadas, estados almacenados y una notificación de la aplicación después de observar un cambio de sin transmisión a en vivo.
¿La API puede decirme la hora exacta de inicio a partir de dos verificaciones?
Dos verificaciones dan un intervalo para el cambio de estado. collected_at es la hora de la observación; para conocer el inicio exacto se necesitan los datos correspondientes del inicio de la transmisión.
TIKTOK API
Probar el flujo de trabajo con una URL pública de TikTok
Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.
Ver las API de TikTok