SocQ로 TikTok 계정 목록을 한 번에 확인하고, 사용자 이름, 라이브 상태, 확인 시각을 하나의 표로 정리하세요. 원하는 주기로 새로 고치고, 관측 결과를 비교해 감지한 변화를 크리에이터 대시보드나 알림 워크플로에 연결할 수 있습니다.
SocQ TikTok User Live API는 사용자 이름으로 상태를 확인하고 조회에 성공한 건마다 레코드 하나를 반환합니다. 이 가이드에서는 배치 요청, 상태 표 내보내기, 변경 감지 코드를 다룹니다.
빠른 답변:
POST /v1/tiktok/user-live에 비어 있지 않은usernames배열을 보내세요. 작업이 성공하면data.results.items에서is_live와status를 읽습니다. 오프라인 조회에 성공하면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이 반환되면 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는 이미 알고 있는 방송과 사용자를 조회하는 별도 API이며, 방송 단위의 상세 정보는 문서에 나온 입력으로 조회합니다.
이 튜토리얼에서는 사용자 이름, 상태, 확인 시각, 소스가 제공하는 시청자 수를 내보냅니다. 계정, 동영상, 댓글 워크플로는 TikTok 스크래핑 튜토리얼을, 콘텐츠 탐색은 TikTok 동영상·사진 검색을 참고하세요.
운영 일정에 맞춰 라이브 확인하기
SocQ User Live는 사용자 이름 목록을 하나의 조회 워크플로로 처리하고 표준 상태 필드를 반환합니다. 상태 저장 및 변경 감지 코드와 함께 사용하면 애플리케이션에서 확인 일정을 예약하고, 크리에이터 대시보드를 갱신하고, 알림을 보낼 수 있습니다. 새로 고침 주기는 직접 정하면 됩니다.
자주 묻는 질문(FAQ)
TikTok 사용자가 라이브 중인지 어떻게 확인하나요?
TikTok User Live에 usernames로 핸들을 보내고, 작업이 성공할 때까지 기다린 뒤 is_live를 확인하세요. 그 상태를 관측한 시각은 collected_at으로 표시할 수 있습니다.
여러 계정을 한 번에 확인할 수 있나요?
가능합니다. 공개 계정 핸들 여러 개를 usernames에 넣으세요. 결과는 author.id 또는 author.username으로 대조하고, 반환된 레코드가 없는 입력은 "이번 확인에서 상태를 얻지 못함"으로 표시하세요.
오프라인 결과는 오류인가요? 과금되나요?
오프라인은 정상적인 조회 결과이며, 반환된 상태 레코드로 과금됩니다. 현재 과금 방식은 User Live API 페이지를 참고하세요.
누군가 방송을 시작할 때까지 API가 계속 모니터링하나요?
작업 하나는 확인을 한 번 실행하고 종료됩니다. 이후 확인은 애플리케이션이 새 작업을 예약하고, 반환된 관측 결과를 비교해 처리합니다.
시청자 수와 방송 제목이 비어 있는 이유는 무엇인가요?
오프라인 방송의 필드는 비어 있을 수 있습니다. 진행 중인 방송이라도 소스에서 누락된 지표는 null로 남습니다. 보고된 계정 상태는 is_live와 status로 읽으세요.
완료 콜백이 크리에이터가 라이브를 시작할 때마다 알려 주나요?
완료 콜백은 작업 하나에 대응합니다. 방송 시작 알림은 예약된 확인, 저장된 상태, 오프라인에서 라이브로의 전환을 관측한 뒤 애플리케이션이 보내는 알림으로 구현해야 합니다.
두 번의 확인으로 정확한 시작 시각을 알 수 있나요?
두 번의 확인으로 알 수 있는 것은 상태가 바뀐 구간입니다. collected_at은 관측 시각이며, 정확한 시작 시각을 알려면 해당 방송의 시작 시각 데이터가 필요합니다.
TIKTOK API
공개 TikTok URL로 워크플로를 테스트하세요
공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.
TikTok API 살펴보기