SocQを使えば、TikTokのアカウント一覧をまとめて確認し、ユーザー名・ライブ配信の状況・確認時刻を1つの表に整理できます。好きなスケジュールで更新し、観測結果を比較して、検出した変化をクリエイターダッシュボードや通知ワークフローにつなげられます。
SocQ TikTok User Live APIは、ユーザー名から配信状況を確認し、取得に成功したアカウントごとにレコードを返します。このガイドでは、バッチリクエスト、ステータス表のエクスポート、変化検知のコードを紹介します。
要点: 空でない
usernames配列をPOST /v1/tiktok/user-liveに送信します。タスクが成功したら、data.results.itemsのis_liveとstatusを読み取ります。オフラインの取得に成功した場合はis_live=false、status=offlineとなります。1つのタスクは実行時点の状況を確認して終了します。
ユーザー名で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 が返された場合は 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")
次の1回実行用のチェッカーを、同じディレクトリに 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
1回の実行で1つのバッチが完了します。コードはアカウントIDと収集時刻を比較します。最初の観測結果が基準になり、同じアカウントのオフラインからライブ配信中への変化は記録され、古い観測結果や重複した観測結果の場合は以前の状態が保持されます。新しいレコードがないアカウントは、以前の状況と確認時刻がそのまま残ります。
CSVには今回の実行で得られた新しい観測結果が保存されます。状態ファイルには、各アカウントについて最後に採用した観測結果が保持されます。画面には、状況とあわせて確認時刻も表示してください。タスクが失敗した場合、プログラムは状態ファイルを書き込む前に停止します。
アプリケーションに変化の通知を追加する
このサンプルでは、オフラインからライブ配信中に変わったユーザー名を went_live_since_previous_check に書き出します。アプリケーション側でこのリストを読み取り、通知ワークフローを実行できます。アカウントIDと観測した遷移時刻を通知キーにすると、配信リトライによる重複を防げます。
2回のチェックによって、状況が変化した期間を特定できます。collected_at は観測した時刻を記録します。更新間隔は、必要な鮮度と繰り返し取得にかかるコストに応じて決めてください。チェックの合間に開始して終了した配信を確認するには、別途過去データが必要です。
callback_url が通知するのは、1つの収集タスクの完了です。以降のチェックでは、アプリケーション側で新しいUser Liveタスクをスケジュールし、保存済みの状況を比較して通知を実行します。
ライブ配信状況とライブルーム詳細の使い分け
ユーザー名を起点にして状況の一覧が欲しい場合は、User Liveを使います。TikTok Live Room Infoは、既知のルームとユーザーを対象にした別のルックアップです。ルーム単位の詳細が必要な場合は、そのドキュメントに記載された入力を使用してください。
このチュートリアルでは、ユーザー名、状況、確認時刻、ソースが提供する視聴者数をエクスポートします。アカウント・動画・コメントのワークフローはTikTokスクレイピングのチュートリアル、コンテンツ探索はTikTokの動画・写真検索をご覧ください。
運用スケジュールに合わせたライブ確認
SocQ User Liveは、ユーザー名のリストを1つのクエリワークフローで受け取り、標準化されたステータスフィールドを返します。状態保存と変化検知のコードを組み合わせれば、チェックのスケジュール管理、クリエイターダッシュボードの更新、通知の送信をアプリケーション側で行えます。更新スケジュールは自由に決められます。
よくある質問(FAQ)
TikTokユーザーがライブ配信中か確認するにはどうすればよいですか?
ハンドルを usernames に入れてTikTok User Liveに送信し、タスクが成功するのを待って is_live を確認します。collected_at を使えば、その状況をいつ観測したかを表示できます。
複数のアカウントを一度に確認できますか?
はい。公開アカウントのハンドルを複数 usernames に入れてください。結果は author.id または author.username で突き合わせます。レコードが返されなかった入力は「今回のチェックでは状況を取得できなかった」として扱います。
オフラインの結果はエラーですか?課金されますか?
オフラインは取得に成功した結果であり、返されたステータスレコードとして課金されます。現在の課金についてはUser Live APIのページをご覧ください。
誰かが配信を始めるまで、APIは監視を続けますか?
各タスクは1回の確認を実行して終了します。継続的にチェックするには、アプリケーション側で新しいタスクをスケジュールし、返された観測結果を比較します。
視聴者数やルームのタイトルが空なのはなぜですか?
オフラインのルームではフィールドが空になることがあります。配信中のルームでも、ソース側で省略された指標は null のままです。報告されたアカウントの状態は is_live と status で確認してください。
完了コールバックで、クリエイターが配信を始めるたびに通知されますか?
完了コールバックは1つのタスクに対応します。配信開始のリマインダーを実現するには、定期的なチェック、保存した状況、そしてオフラインからライブ配信中への変化を観測した後のアプリケーション側の通知が必要です。
2回のチェックから正確な開始時刻はわかりますか?
2回のチェックから得られるのは、状況が変化した期間です。collected_at は観測時刻であり、正確な開始時刻を知るには、該当する配信開始のデータが必要です。