TikTok Live Status API: Check Users by Username

Check your TikTok account list in a batch with SocQ and organize usernames, live status and check times in one table. Refresh it on your schedule, compare observations and connect detected changes to a creator dashboard or reminder workflow.

The SocQ TikTok User Live API checks status by username and returns a record for each successful lookup. This guide covers batch requests, a status-table export and change-detection code.

Quick answer: Submit a nonempty usernames array to POST /v1/tiktok/user-live. After the task succeeds, read is_live and status from data.results.items. A successful offline result has is_live=false and status=offline; one task checks status when it runs and then finishes.

Check Whether a TikTok User Is Live by Username

Set SOCQ_API_KEY and submit an account 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"]}'

Use account handles, with or without @. For a batch, put several distinct handles in the same array:

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

User Live starts from usernames. Save data.task_id as TASK_ID, then retrieve that task:

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

queued, running and retrying mean the collection task is still pending. After success, read is_live to determine the account status. On failure, inspect data.error_message. Keep the task ID to resume retrieval after a client timeout.

Distinguish Offline Accounts, Missing Values and Failed Lookups

Active-stream records use title, author, media and metrics.viewers_count for the title, creator, cover and viewer count. Fields omitted by the source remain null; a returned numeric zero remains 0.

This excerpt shows the fields in an offline status record:

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

This sample shows the offline record structure. Querying the same task retrieves that saved observation. Create a new User Live task to refresh an account's status.

Build a Refreshable Status List with Python

Save the task helper below as socq_collect.py. It uses the standard library and reads all result pages after the task succeeds:

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

Save this one-run checker as check_live.py in the same directory. Change the account list for your 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

Each run completes one batch. The code compares account IDs and collection times: the first observation establishes a baseline, an offline-to-live change for the same account is recorded, and older or repeated observations retain the previous state. Accounts without a new record keep their previous status and check time.

The CSV stores new observations from this run. The state file retains the latest accepted observation for each account. Show the check time alongside the status in your interface. On task failure, the program stops before writing the state file.

Add Change Notifications in Your Application

The example writes offline-to-live usernames to went_live_since_previous_check. Your application can read that list and run its notification workflow. Use account ID plus observed transition time as a notification key to deduplicate delivery retries.

Two checks establish an interval in which a status changed, and collected_at records the observation time. Set the refresh interval according to your update requirements and repeated-lookup cost. Verifying streams that started and ended between checks requires separate historical data.

callback_url reports completion of one collection task. Your application schedules new User Live tasks for further checks and triggers reminders by comparing saved statuses.

Choose Live Status or Live Room Details

Use User Live when you start from usernames and want a status list. TikTok Live Room Info is a separate lookup for a known room and user; use its documented inputs for room-level details.

This tutorial exports usernames, status, check time and source-provided viewer counts. See the TikTok scraping tutorial for account, video and comment workflows, or TikTok video and photo search for content discovery.

Fit Live Checks to Your Operating Schedule

SocQ User Live takes a username list through one query workflow and returns standard status fields. Pair it with the state-saving and change-detection code to schedule checks, update your creator dashboard and send reminders from your application. You choose the refresh schedule.

Open User Live and check your account list.

FAQ

How do I check if a TikTok user is live?

Send the handle in usernames to TikTok User Live, wait for the task to succeed and inspect is_live. Use collected_at to show when that status was observed.

Can I check multiple accounts at once?

Yes. Put several public account handles in usernames. Match results using author.id or author.username; mark an input without a returned record as "no status obtained in this check."

Is an offline result an error, and is it billed?

Offline is a successful lookup result, billed as a returned status record. See the User Live API page for current billing.

Does the API keep monitoring until someone starts streaming?

Each task runs one check and finishes. Your application schedules new tasks and compares the returned observations for ongoing checks.

Why are the viewer count and room title empty?

Offline room fields can be empty. Source-omitted measurements for active rooms also remain null. Use is_live and status to read the reported account state.

Does a completion callback notify me whenever a creator goes live?

A completion callback corresponds to one task. Stream-start reminders require scheduled checks, stored statuses and an application notification after an observed offline-to-live change.

Can the API tell me the exact start time from two checks?

Two checks give an interval for the status change. collected_at is the observation time; an exact start requires the corresponding broadcast-start data.