Controlla in batch il tuo elenco di account TikTok con SocQ e organizza username, stato della diretta e orari dei controlli in un’unica tabella. Aggiornala con la frequenza che preferisci, confronta le osservazioni e collega le variazioni rilevate a una dashboard dei creator o a un flusso di promemoria.
La TikTok User Live API di SocQ controlla lo stato per username e restituisce un record per ogni consultazione riuscita. Questa guida tratta le richieste in batch, l’esportazione di una tabella di stato e il codice per il rilevamento delle variazioni.
Risposta rapida: invia un array
usernamesnon vuoto aPOST /v1/tiktok/user-live. Quando l’attività riesce, leggiis_liveestatusindata.results.items. Un risultato offline riuscito hais_live=falseestatus=offline; un’attività controlla lo stato nel momento in cui viene eseguita e poi termina.
Verifica se un utente TikTok è in diretta tramite username
Imposta SOCQ_API_KEY e invia l’handle di un account:
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"]}'
Usa gli handle degli account, con o senza @. Per un batch, inserisci più handle distinti nello stesso array:
{"usernames":["thejustalex","@tiktok"]}
User Live parte dagli username. Salva data.task_id come TASK_ID, poi recupera quell’attività:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued, running e retrying indicano che l’attività di raccolta è ancora in sospeso. Dopo il successo, leggi is_live per stabilire lo stato dell’account. In caso di errore, controlla data.error_message. Conserva l’ID attività per riprendere il recupero dopo un timeout del client.
Distingui account offline, valori mancanti e consultazioni fallite
| Osservazione | Interpretazione | Comportamento dell’applicazione |
|---|---|---|
is_live=true, status=live | La consultazione riuscita ha segnalato una diretta attiva | Mostra “in diretta” con l’orario di raccolta |
is_live=false, status=offline | La consultazione riuscita non ha segnalato alcuna diretta attiva | Mostra “offline” con l’orario di raccolta |
| Il titolo di una stanza o una metrica è null | Quel dettaglio non è disponibile | Lascialo vuoto |
| Errore dell’attività o nessun record utilizzabile per un input | Non hai un nuovo stato utilizzabile per quell’account | Mostra un controllo fallito o sconosciuto, non offline |
I record di dirette attive usano title, author, media e metrics.viewers_count per titolo, creator, copertina e numero di spettatori. I campi omessi dalla fonte restano null; uno zero numerico restituito resta 0.
Questo estratto mostra i campi di un record di stato offline:
{
"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"
}
Questo esempio mostra la struttura di un record offline. Interrogare la stessa attività recupera quell’osservazione salvata. Crea una nuova attività User Live per aggiornare lo stato di un account.
Crea un elenco di stato aggiornabile con Python
Salva l’helper per le attività qui sotto come socq_collect.py. Usa la libreria standard e legge tutte le pagine di risultati dopo che l’attività è riuscita:
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")
Salva questo script di controllo a esecuzione singola come check_live.py nella stessa directory. Modifica l’elenco degli account in base alla tua applicazione:
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
Ogni esecuzione completa un batch. Il codice confronta gli ID degli account e gli orari di raccolta: la prima osservazione stabilisce una base di partenza, il passaggio da offline a in diretta per lo stesso account viene registrato, mentre le osservazioni più vecchie o ripetute mantengono lo stato precedente. Gli account senza un nuovo record conservano lo stato e l’orario di controllo precedenti.
Il CSV memorizza le nuove osservazioni di questa esecuzione. Il file di stato conserva l’ultima osservazione accettata per ogni account. Mostra nell’interfaccia l’orario del controllo accanto allo stato. In caso di errore dell’attività, il programma si ferma prima di scrivere il file di stato.
Aggiungi notifiche di variazione nella tua applicazione
L’esempio scrive in went_live_since_previous_check gli username passati da offline a in diretta. La tua applicazione può leggere quell’elenco ed eseguire il proprio flusso di notifica. Usa l’ID dell’account più l’orario della transizione osservata come chiave di notifica per eliminare i duplicati dovuti a nuovi tentativi di consegna.
Due controlli stabiliscono un intervallo in cui lo stato è cambiato, e collected_at registra l’orario dell’osservazione. Imposta l’intervallo di aggiornamento in base ai requisiti di aggiornamento e al costo delle consultazioni ripetute. Per verificare le dirette iniziate e terminate tra un controllo e l’altro servono dati storici separati.
callback_url segnala il completamento di una singola attività di raccolta. La tua applicazione pianifica nuove attività User Live per i controlli successivi e attiva i promemoria confrontando gli stati salvati.
Scegli tra stato della diretta e dettagli della stanza
Usa User Live quando parti dagli username e vuoi un elenco di stato. TikTok Live Room Info è una consultazione separata per una stanza e un utente noti; usa i suoi input documentati per i dettagli a livello di stanza.
Questo tutorial esporta username, stato, orario del controllo e numero di spettatori fornito dalla fonte. Consulta il tutorial sullo scraping di TikTok per i flussi su account, video e commenti, oppure ricerca di video e foto su TikTok per la scoperta dei contenuti.
Adatta i controlli al tuo calendario operativo
SocQ User Live accetta un elenco di username in un unico flusso di interrogazione e restituisce campi di stato standard. Abbinala al codice per il salvataggio dello stato e il rilevamento delle variazioni per pianificare i controlli, aggiornare la dashboard dei creator e inviare promemoria dalla tua applicazione. La frequenza di aggiornamento la scegli tu.
Apri User Live e controlla il tuo elenco di account.
Domande frequenti (FAQ)
Come verifico se un utente TikTok è in diretta?
Invia l’handle in usernames a TikTok User Live, attendi che l’attività riesca e controlla is_live. Usa collected_at per mostrare quando è stato osservato quello stato.
Posso controllare più account contemporaneamente?
Sì. Inserisci più handle di account pubblici in usernames. Abbina i risultati usando author.id o author.username; segna un input senza record restituito come “nessuno stato ottenuto in questo controllo”.
Un risultato offline è un errore e viene fatturato?
Offline è un risultato di consultazione riuscito, fatturato come record di stato restituito. Consulta la pagina della User Live API per la fatturazione attuale.
L’API continua a monitorare finché qualcuno non inizia una diretta?
Ogni attività esegue un solo controllo e termina. La tua applicazione pianifica nuove attività e confronta le osservazioni restituite per i controlli continui.
Perché il numero di spettatori e il titolo della stanza sono vuoti?
I campi della stanza possono essere vuoti quando l’account è offline. Anche le misurazioni omesse dalla fonte per le stanze attive restano null. Usa is_live e status per leggere lo stato dell’account segnalato.
Una callback di completamento mi avvisa ogni volta che un creator va in diretta?
Una callback di completamento corrisponde a una sola attività. I promemoria sull’inizio di una diretta richiedono controlli pianificati, stati salvati e una notifica dell’applicazione dopo un passaggio osservato da offline a in diretta.
L’API può indicarmi l’orario esatto di inizio a partire da due controlli?
Due controlli forniscono un intervallo entro cui lo stato è cambiato. collected_at è l’orario dell’osservazione; per conoscere l’inizio esatto servono i dati corrispondenti sull’avvio della trasmissione.
TIKTOK API
Prova il flusso di lavoro con un URL pubblico di TikTok
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di TikTok