TikTokTikTok Live Status APITikTok-Nutzer live prüfenTikTok Live Checker APINutzernamen-Abfrage

TikTok Live Status API: Nutzer per Nutzername prüfen

TikTok-Live-Status im Batch mit SocQ prüfen. Erstellen Sie eine Kontoliste mit Zeitstempeln, Python-Exporten und Änderungserkennung für Dashboards und Erinnerungen.

SocQAktualisiert am 16. Oktober 20266 Min. Lesezeit

Prüfen Sie Ihre Liste von TikTok-Konten mit SocQ im Batch und halten Sie Nutzernamen, Live-Status und Prüfzeiten in einer Tabelle fest. Aktualisieren Sie sie nach Ihrem eigenen Zeitplan, vergleichen Sie die Beobachtungen und binden Sie erkannte Änderungen an ein Creator-Dashboard oder einen Erinnerungs-Workflow an.

Die SocQ TikTok User Live API prüft den Status anhand des Nutzernamens und liefert für jede erfolgreiche Abfrage einen Datensatz. Dieser Leitfaden behandelt Batch-Anfragen, den Export einer Statustabelle und Code zur Änderungserkennung.

Kurzantwort: Senden Sie ein nicht leeres Array usernames an POST /v1/tiktok/user-live. Lesen Sie nach erfolgreicher Aufgabe is_live und status aus data.results.items. Ein erfolgreiches Offline-Ergebnis hat is_live=false und status=offline; eine Aufgabe prüft den Status zum Zeitpunkt der Ausführung und ist danach beendet.

Per Nutzername prüfen, ob ein TikTok-Nutzer live ist

Setzen Sie SOCQ_API_KEY und senden Sie ein Konto-Handle:

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

Verwenden Sie Konto-Handles, mit oder ohne @. Für einen Batch tragen Sie mehrere verschiedene Handles in dasselbe Array ein:

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

User Live geht von Nutzernamen aus. Speichern Sie data.task_id als TASK_ID und rufen Sie dann diese Aufgabe ab:

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

queued, running und retrying bedeuten, dass die Erfassungsaufgabe noch aussteht. Lesen Sie nach dem Erfolg is_live, um den Kontostatus zu bestimmen. Prüfen Sie bei einem Fehler data.error_message. Bewahren Sie die Aufgaben-ID auf, um den Abruf nach einer Zeitüberschreitung des Clients fortzusetzen.

Offline-Konten, fehlende Werte und fehlgeschlagene Abfragen unterscheiden

BeobachtungInterpretationVerhalten der Anwendung
is_live=true, status=liveDie erfolgreiche Abfrage meldete einen aktiven StreamLive mit Erfassungszeit anzeigen
is_live=false, status=offlineDie erfolgreiche Abfrage meldete keinen aktiven StreamOffline mit Erfassungszeit anzeigen
Ein Raumtitel oder eine Kennzahl ist nullDieses Detail ist nicht verfügbarLeer lassen
Fehlgeschlagene Aufgabe oder kein verwertbarer Datensatz zu einer EingabeFür dieses Konto liegt kein neuer verwertbarer Status vorEine fehlgeschlagene oder unbekannte Prüfung anzeigen, nicht offline

Datensätze aktiver Streams verwenden title, author, media und metrics.viewers_count für Titel, Creator, Cover und Zuschauerzahl. Von der Quelle ausgelassene Felder bleiben null; eine gelieferte numerische Null bleibt 0.

Dieser Auszug zeigt die Felder eines Offline-Statusdatensatzes:

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

Dieses Beispiel zeigt die Struktur eines Offline-Datensatzes. Wer dieselbe Aufgabe erneut abfragt, ruft diese gespeicherte Beobachtung ab. Erstellen Sie eine neue User-Live-Aufgabe, um den Status eines Kontos zu aktualisieren.

Mit Python eine aktualisierbare Statusliste erstellen

Speichern Sie den folgenden Aufgaben-Helfer als socq_collect.py. Er verwendet die Standardbibliothek und liest nach dem Erfolg der Aufgabe alle Ergebnisseiten:

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

Speichern Sie diese Prüfroutine für einen einzelnen Durchlauf als check_live.py im selben Verzeichnis. Passen Sie die Kontoliste an Ihre Anwendung an:

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

Jeder Durchlauf schließt einen Batch ab. Der Code vergleicht Konto-IDs und Erfassungszeiten: Die erste Beobachtung legt eine Ausgangsbasis fest, ein Wechsel von offline zu live beim selben Konto wird festgehalten, und ältere oder wiederholte Beobachtungen behalten den vorherigen Zustand bei. Konten ohne neuen Datensatz behalten ihren bisherigen Status und ihre bisherige Prüfzeit.

Die CSV-Datei enthält die neuen Beobachtungen dieses Durchlaufs. Die Zustandsdatei hält für jedes Konto die zuletzt akzeptierte Beobachtung fest. Zeigen Sie in Ihrer Oberfläche die Prüfzeit neben dem Status an. Bei einer fehlgeschlagenen Aufgabe bricht das Programm ab, bevor es die Zustandsdatei schreibt.

Benachrichtigungen bei Änderungen in Ihrer Anwendung ergänzen

Das Beispiel schreibt die Nutzernamen mit einem Wechsel von offline zu live nach went_live_since_previous_check. Ihre Anwendung kann diese Liste lesen und ihren Benachrichtigungs-Workflow ausführen. Verwenden Sie die Konto-ID plus den Zeitpunkt des beobachteten Übergangs als Benachrichtigungsschlüssel, um wiederholte Zustellversuche zu deduplizieren.

Zwei Prüfungen legen ein Intervall fest, in dem sich ein Status geändert hat, und collected_at hält den Beobachtungszeitpunkt fest. Legen Sie das Aktualisierungsintervall nach Ihren Anforderungen an die Aktualität und den Kosten wiederholter Abfragen fest. Streams, die zwischen zwei Prüfungen begonnen und geendet haben, lassen sich nur mit separaten historischen Daten überprüfen.

callback_url meldet den Abschluss einer einzelnen Erfassungsaufgabe. Ihre Anwendung plant neue User-Live-Aufgaben für weitere Prüfungen und löst Erinnerungen aus, indem sie gespeicherte Status vergleicht.

Live-Status oder Details zum Livestream-Raum wählen

Verwenden Sie User Live, wenn Sie von Nutzernamen ausgehen und eine Statusliste möchten. TikTok Live Room Info ist eine eigene Abfrage für einen bekannten Raum und Nutzer; nutzen Sie die dokumentierten Eingaben für Details auf Raumebene.

Diese Anleitung exportiert Nutzernamen, Status, Prüfzeit und von der Quelle gelieferte Zuschauerzahlen. Konto-, Video- und Kommentar-Workflows finden Sie in der TikTok-Scraping-Anleitung, die Inhalts-Discovery in TikTok-Video- und Fotosuche.

Live-Prüfungen an Ihren Betriebsplan anpassen

SocQ User Live nimmt eine Nutzernamenliste in einem einzigen Abfrage-Workflow entgegen und liefert standardisierte Statusfelder. Kombinieren Sie die API mit dem Code zum Speichern des Zustands und zur Änderungserkennung, um Prüfungen zu planen, Ihr Creator-Dashboard zu aktualisieren und Erinnerungen aus Ihrer Anwendung zu versenden. Den Aktualisierungsplan bestimmen Sie.

User Live öffnen und Ihre Kontoliste prüfen.

Häufig gestellte Fragen (FAQ)

Wie prüfe ich, ob ein TikTok-Nutzer live ist?

Senden Sie das Handle in usernames an TikTok User Live, warten Sie, bis die Aufgabe erfolgreich ist, und prüfen Sie is_live. Verwenden Sie collected_at, um anzuzeigen, wann dieser Status beobachtet wurde.

Kann ich mehrere Konten gleichzeitig prüfen?

Ja. Tragen Sie mehrere öffentliche Konto-Handles in usernames ein. Ordnen Sie die Ergebnisse über author.id oder author.username zu; kennzeichnen Sie eine Eingabe ohne zurückgegebenen Datensatz als „in dieser Prüfung kein Status erhalten“.

Ist ein Offline-Ergebnis ein Fehler, und wird es abgerechnet?

Offline ist ein erfolgreiches Abfrageergebnis und wird als zurückgegebener Statusdatensatz abgerechnet. Die aktuelle Abrechnung finden Sie auf der Seite zur User Live API.

Überwacht die API dauerhaft, bis jemand mit dem Streamen beginnt?

Jede Aufgabe führt eine Prüfung aus und ist danach beendet. Für laufende Prüfungen plant Ihre Anwendung neue Aufgaben und vergleicht die zurückgegebenen Beobachtungen.

Warum sind Zuschauerzahl und Raumtitel leer?

Felder von Offline-Räumen können leer sein. Von der Quelle ausgelassene Messwerte aktiver Räume bleiben ebenfalls null. Verwenden Sie is_live und status, um den gemeldeten Kontozustand zu lesen.

Benachrichtigt mich ein Abschluss-Callback, sobald ein Creator live geht?

Ein Abschluss-Callback gehört zu genau einer Aufgabe. Erinnerungen an den Stream-Start erfordern geplante Prüfungen, gespeicherte Status und eine Benachrichtigung der Anwendung nach einem beobachteten Wechsel von offline zu live.

Kann mir die API anhand von zwei Prüfungen die genaue Startzeit nennen?

Zwei Prüfungen ergeben ein Intervall für die Statusänderung. collected_at ist der Beobachtungszeitpunkt; eine genaue Startzeit erfordert die entsprechenden Daten zum Beginn der Übertragung.

TIKTOK API

Workflow mit einer öffentlichen TikTok-URL testen

Senden Sie öffentliche Eingaben und erhalten Sie normalisierte Datensätze mit nachvollziehbarem Quellkontext.

TikTok-APIs ansehen