TikTokTikTok Live Status APIVérifier si un utilisateur TikTok est en liveTikTok Live Checker APIRecherche par nom d’utilisateur

API TikTok Live Status : vérifier des utilisateurs par nom d’utilisateur

Vérifiez l’état des lives TikTok par lots avec SocQ. Constituez une liste de comptes horodatée, avec exports Python et détection des changements pour vos tableaux de bord et vos rappels.

SocQMis à jour le 16 octobre 20267 min de lecture

Vérifiez votre liste de comptes TikTok en un seul lot avec SocQ et regroupez noms d’utilisateur, statut live et heures de vérification dans un même tableau. Actualisez-le selon votre calendrier, comparez les observations et reliez les changements détectés à un tableau de bord de créateurs ou à un workflow de rappels.

L’API SocQ TikTok User Live vérifie l’état à partir du nom d’utilisateur et renvoie un enregistrement pour chaque consultation réussie. Ce guide présente les requêtes par lots, l’export d’un tableau de statuts et le code de détection des changements.

Réponse rapide : envoyez un tableau usernames non vide à POST /v1/tiktok/user-live. Une fois la tâche réussie, lisez is_live et status dans data.results.items. Un résultat hors ligne réussi a is_live=false et status=offline ; une tâche vérifie l’état au moment où elle s’exécute, puis se termine.

Vérifier si un utilisateur TikTok est en live à partir de son nom d’utilisateur

Définissez SOCQ_API_KEY et envoyez l’identifiant d’un compte :

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"]}'

Utilisez les identifiants de compte, avec ou sans @. Pour un lot, placez plusieurs identifiants distincts dans le même tableau :

{"usernames":["thejustalex","@tiktok"]}

User Live part des noms d’utilisateur. Enregistrez data.task_id sous le nom TASK_ID, puis récupérez cette tâche :

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Les états queued, running et retrying signifient que la tâche de collecte est encore en cours. Une fois la tâche réussie, lisez is_live pour déterminer l’état du compte. En cas d’échec, examinez data.error_message. Conservez l’ID de tâche pour reprendre la récupération après un délai d’expiration côté client.

Distinguer comptes hors ligne, valeurs manquantes et consultations en échec

ObservationInterprétationComportement de l’application
is_live=true, status=liveLa consultation réussie a signalé un live en coursAfficher live avec son heure de collecte
is_live=false, status=offlineLa consultation réussie n’a signalé aucun live en coursAfficher hors ligne avec son heure de collecte
Un titre de salle ou une métrique vaut nullCe détail n’est pas disponibleLe laisser vide
Échec de la tâche ou aucun enregistrement exploitable pour une entréeVous n’avez pas de nouveau statut exploitable pour ce compteAfficher une vérification en échec ou inconnue, pas hors ligne

Les enregistrements d’un live en cours utilisent title, author, media et metrics.viewers_count pour le titre, le créateur, la couverture et le nombre de spectateurs. Les champs omis par la source restent null ; un zéro numérique renvoyé reste 0.

Cet extrait montre les champs d’un enregistrement de statut hors ligne :

{
  "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"
}

Cet exemple montre la structure d’un enregistrement hors ligne. Interroger de nouveau la même tâche récupère cette observation enregistrée. Créez une nouvelle tâche User Live pour actualiser l’état d’un compte.

Créer une liste de statuts actualisable avec Python

Enregistrez l’utilitaire de tâche ci-dessous sous le nom socq_collect.py. Il utilise la bibliothèque standard et lit toutes les pages de résultats une fois la tâche réussie :

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")

Enregistrez ce vérificateur à exécution unique sous le nom check_live.py dans le même répertoire. Modifiez la liste de comptes en fonction de votre application :

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

Chaque exécution traite un lot. Le code compare les ID de compte et les heures de collecte : la première observation établit une référence, un passage de hors ligne à live pour le même compte est enregistré, et les observations plus anciennes ou répétées conservent l’état précédent. Les comptes sans nouvel enregistrement gardent leur statut et leur heure de vérification précédents.

Le CSV stocke les nouvelles observations de cette exécution. Le fichier d’état conserve la dernière observation acceptée pour chaque compte. Affichez l’heure de vérification à côté du statut dans votre interface. En cas d’échec de la tâche, le programme s’arrête avant d’écrire le fichier d’état.

Ajouter des notifications de changement dans votre application

L’exemple écrit dans went_live_since_previous_check les noms d’utilisateur passés de hors ligne à live. Votre application peut lire cette liste et lancer son workflow de notification. Utilisez l’ID du compte associé à l’heure de la transition observée comme clé de notification pour dédupliquer les envois en cas de nouvelles tentatives.

Deux vérifications délimitent un intervalle pendant lequel un statut a changé, et collected_at enregistre l’heure d’observation. Définissez l’intervalle d’actualisation selon vos besoins de mise à jour et le coût des consultations répétées. Pour vérifier les lives qui ont démarré et se sont terminés entre deux vérifications, il faut des données historiques distinctes.

callback_url signale la fin d’une tâche de collecte. Votre application planifie de nouvelles tâches User Live pour les vérifications suivantes et déclenche les rappels en comparant les statuts enregistrés.

Choisir entre l’état du live et les détails de la salle de live

Utilisez User Live lorsque vous partez de noms d’utilisateur et que vous voulez une liste de statuts. TikTok Live Room Info est une consultation distincte pour une salle et un utilisateur connus ; utilisez ses entrées documentées pour obtenir les détails au niveau de la salle.

Ce tutoriel exporte les noms d’utilisateur, le statut, l’heure de vérification et le nombre de spectateurs fourni par la source. Consultez le tutoriel de scraping TikTok pour les workflows de comptes, de vidéos et de commentaires, ou la recherche de vidéos et de photos TikTok pour la découverte de contenu.

Adapter les vérifications à votre planning d’exploitation

SocQ User Live prend une liste de noms d’utilisateur dans un seul flux de requêtes et renvoie des champs de statut standard. Associez-le au code de sauvegarde d’état et de détection des changements pour planifier les vérifications, mettre à jour votre tableau de bord de créateurs et envoyer des rappels depuis votre application. Vous choisissez la fréquence d’actualisation.

Ouvrir User Live et vérifier votre liste de comptes.

FAQ

Comment vérifier si un utilisateur TikTok est en live ?

Envoyez l’identifiant dans usernames à TikTok User Live, attendez que la tâche réussisse et examinez is_live. Utilisez collected_at pour afficher le moment où ce statut a été observé.

Puis-je vérifier plusieurs comptes à la fois ?

Oui. Placez plusieurs identifiants de comptes publics dans usernames. Associez les résultats avec author.id ou author.username ; marquez une entrée sans enregistrement renvoyé comme « aucun statut obtenu lors de cette vérification ».

Un résultat hors ligne est-il une erreur, et est-il facturé ?

Hors ligne est un résultat de consultation réussie, facturé comme un enregistrement de statut renvoyé. Consultez la page de l’API User Live pour la facturation actuelle.

L’API continue-t-elle de surveiller jusqu’à ce que quelqu’un démarre un live ?

Chaque tâche exécute une vérification puis se termine. Votre application planifie de nouvelles tâches et compare les observations renvoyées pour les vérifications continues.

Pourquoi le nombre de spectateurs et le titre de la salle sont-ils vides ?

Les champs d’une salle hors ligne peuvent être vides. Les mesures omises par la source pour des salles en direct restent aussi null. Utilisez is_live et status pour lire l’état du compte tel qu’il est signalé.

Un callback de fin m’avertit-il chaque fois qu’un créateur passe en live ?

Un callback de fin correspond à une seule tâche. Les rappels de début de live exigent des vérifications planifiées, des statuts enregistrés et une notification de l’application après un passage observé de hors ligne à live.

L’API peut-elle m’indiquer l’heure de début exacte à partir de deux vérifications ?

Deux vérifications donnent un intervalle pour le changement de statut. collected_at est l’heure d’observation ; connaître l’heure de début exacte exige les données de début de diffusion correspondantes.

TIKTOK API

Tester le workflow avec une URL publique TikTok

Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.

Découvrir les API TikTok