Проверяйте список аккаунтов TikTok пакетом через SocQ и сводите имена пользователей, статус прямого эфира и время проверки в одну таблицу. Обновляйте ее по своему расписанию, сравнивайте наблюдения и передавайте обнаруженные изменения в панель авторов или в сценарий напоминаний.
SocQ TikTok User Live API проверяет статус по имени пользователя и возвращает запись для каждого успешного запроса. В этом руководстве разобраны пакетные запросы, экспорт таблицы статусов и код для отслеживания изменений.
Коротко: отправьте непустой массив
usernamesвPOST /v1/tiktok/user-live. После успешного завершения задачи читайтеis_liveиstatusизdata.results.items. У успешного результата для аккаунта не в эфиреis_live=falseиstatus=offline; одна задача проверяет статус в момент запуска и затем завершается.
Как проверить по имени пользователя, ведет ли он эфир в TikTok
Задайте SOCQ_API_KEY и отправьте имя аккаунта:
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"]}'
Используйте имена аккаунтов с @ или без него. Для пакета поместите несколько разных имен в один массив:
{"usernames":["thejustalex","@tiktok"]}
User Live работает от имен пользователей. Сохраните data.task_id как TASK_ID, затем получите эту задачу:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Статусы queued, running и retrying означают, что задача сбора еще выполняется. После успешного завершения определите статус аккаунта по is_live. При сбое изучите data.error_message. Сохраняйте ID задачи, чтобы возобновить получение результатов после тайм-аута клиента.
Отличайте аккаунты не в эфире, отсутствующие значения и неудачные запросы
| Наблюдение | Интерпретация | Поведение приложения |
|---|---|---|
is_live=true, status=live | Успешный запрос показал активную трансляцию | Показать «в эфире» со временем сбора |
is_live=false, status=offline | Успешный запрос показал, что активной трансляции нет | Показать «не в эфире» со временем сбора |
| Название эфира или метрика равны null | Эти сведения недоступны | Оставить поле пустым |
| Сбой задачи или нет пригодной записи для входного значения | Нового пригодного статуса для этого аккаунта нет | Показать неудачную или неизвестную проверку, а не «не в эфире» |
В записях активных трансляций поля title, author, media и metrics.viewers_count содержат название, автора, обложку и число зрителей. Поля, которые источник не передал, остаются null; возвращенный числовой ноль остается 0.
Этот фрагмент показывает поля записи статуса для аккаунта не в эфире:
{
"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"
}
Пример показывает структуру записи для аккаунта не в эфире. Повторный запрос той же задачи возвращает сохраненное наблюдение. Чтобы обновить статус аккаунта, создайте новую задачу User Live.
Обновляемый список статусов на Python
Сохраните вспомогательный модуль для задач ниже как socq_collect.py. Он использует только стандартную библиотеку и после успешного завершения задачи читает все страницы результатов:
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")
Сохраните этот скрипт разовой проверки как check_live.py в том же каталоге. Замените список аккаунтов на нужный вашему приложению:
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
Каждый запуск обрабатывает один пакет. Код сравнивает ID аккаунтов и время сбора: первое наблюдение задает исходную точку, переход того же аккаунта из состояния «не в эфире» в «в эфире» фиксируется, а более старые или повторные наблюдения сохраняют прежнее состояние. Аккаунты без новой записи сохраняют прежний статус и время проверки.
CSV хранит новые наблюдения этого запуска. Файл состояния хранит последнее принятое наблюдение для каждого аккаунта. Показывайте в интерфейсе время проверки рядом со статусом. При сбое задачи программа останавливается до записи файла состояния.
Уведомления об изменениях в вашем приложении
Пример записывает имена пользователей, перешедших из состояния «не в эфире» в «в эфире», в went_live_since_previous_check. Приложение может прочитать этот список и запустить свой сценарий уведомлений. Используйте ID аккаунта вместе со временем наблюдаемого перехода как ключ уведомления, чтобы исключить дубли при повторных попытках доставки.
Две проверки задают интервал, в котором изменился статус, а collected_at фиксирует время наблюдения. Выбирайте интервал обновления исходя из требований к актуальности и стоимости повторных запросов. Чтобы подтвердить трансляции, которые начались и закончились между проверками, нужны отдельные исторические данные.
callback_url сообщает о завершении одной задачи сбора. Для последующих проверок приложение само планирует новые задачи User Live и запускает напоминания, сравнивая сохраненные статусы.
Статус эфира или детали эфира
Используйте User Live, когда у вас на входе имена пользователей и нужен список статусов. TikTok Live Room Info — отдельный запрос для известного эфира и пользователя; для деталей на уровне эфира используйте его документированные входные данные.
Это руководство экспортирует имена пользователей, статус, время проверки и число зрителей, переданное источником. Сценарии для аккаунтов, видео и комментариев описаны в руководстве по парсингу TikTok, а поиск контента — в статье Поиск видео и фото в TikTok.
Встройте проверки эфиров в свое расписание
SocQ User Live принимает список имен пользователей в рамках одного сценария запроса и возвращает стандартные поля статуса. Сочетайте его с кодом сохранения состояния и отслеживания изменений, чтобы планировать проверки, обновлять панель авторов и отправлять напоминания из своего приложения. Расписание обновлений выбираете вы.
Открыть User Live и проверить свой список аккаунтов.
Часто задаваемые вопросы
Как проверить, ведет ли пользователь TikTok прямой эфир?
Отправьте имя пользователя в usernames в TikTok User Live, дождитесь успешного завершения задачи и проверьте is_live. Используйте collected_at, чтобы показать, когда был зафиксирован этот статус.
Можно ли проверить несколько аккаунтов сразу?
Да. Поместите несколько имен публичных аккаунтов в usernames. Сопоставляйте результаты по author.id или author.username; входное значение без возвращенной записи помечайте как «статус в этой проверке не получен».
Результат «не в эфире» — это ошибка? Он тарифицируется?
«Не в эфире» — успешный результат запроса, он тарифицируется как возвращенная запись статуса. Актуальную тарификацию смотрите на странице User Live API.
Продолжает ли API следить за аккаунтом, пока не начнется эфир?
Каждая задача выполняет одну проверку и завершается. Для постоянных проверок приложение планирует новые задачи и сравнивает возвращенные наблюдения.
Почему число зрителей и название эфира пустые?
У аккаунта не в эфире поля эфира могут быть пустыми. Показатели активных эфиров, которые источник не передал, тоже остаются null. Для определения состояния аккаунта используйте is_live и status.
Уведомляет ли обратный вызов о завершении каждый раз, когда автор выходит в эфир?
Обратный вызов о завершении соответствует одной задаче. Для напоминаний о начале трансляции нужны проверки по расписанию, сохраненные статусы и уведомление из приложения после наблюдаемого перехода из состояния «не в эфире» в «в эфире».
Можно ли по двум проверкам узнать точное время начала эфира?
Две проверки дают интервал, в котором изменился статус. collected_at — время наблюдения; для точного времени начала нужны соответствующие данные о начале трансляции.
TIKTOK API
Проверить сценарий на публичном URL TikTok
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для TikTok