TikTok Live Room Info
TikTok Live Room Info represents a point-in-time view of one active public room, including its title, status, owner identity, cover image, and visible viewer and like counts. These fields support live-status checks, audience snapshots, room enrichment, and time-stamped reporting for rooms that are already known.
Features
- Paired room and owner lookupResolve one known live room from its room_id and matching owner user_id, returning at most one normalized live_room record.
- Room and owner contextReturn the current room title and status together with the owner's public ID, username, and display name.
- Audience and cover snapshotCapture the visible viewer count, like count, public cover image, and collection timestamp for point-in-time interpretation.
Parameters
| Parameters | Required | Description |
|---|---|---|
room_id | Required | Required non-empty live room identifier. Supply the numeric identifier as a string from a source that exposes the current TikTok live session. |
user_id | Required | Required non-empty numeric TikTok user identifier for the room owner, supplied as a string and paired with the same room. |
How to Use
Pair the identifiers for one known active room, submit an asynchronous lookup, then read the normalized snapshot from the task results.
- Obtain room_id from a source that exposes the current TikTok live session, and obtain the matching owner user_id from the same context or a TikTok Profiles result.
- POST both non-empty string identifiers to /v1/tiktok/live-room-info.
- Poll /v1/tasks/{task_id} until the status is succeeded or failed.
- Read data.results.items from /v1/tasks/{task_id}?limit=50; a resolved room produces at most one record, and the standard next_cursor applies only if results.has_more is true.
curl -X POST "https://api.socq.ai/v1/tiktok/live-room-info" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"room_id":"7523685855395842871","user_id":"6742945285876515845"}'
# Poll GET /v1/tasks/{task_id}, then read data.results.items from /v1/tasks/{task_id}?limit=50.Best Use Cases
- Point-in-time live-status checks: Use the returned status, title, room ID, and collected_at value to confirm the snapshot available for a known room.
- Audience snapshot reporting: Record viewers_count and likes_count with collected_at to compare observations made at different times during a known broadcast.
- Live room enrichment: Attach the owner ID, username, display name, room title, status, and cover image to an existing live-room record.
Pro Tips
- Keep room_id paired with the owner user_id from the same active session; a room and user mismatch can return no record or an input-specific source error.
- Preserve both identifiers as strings so large numeric TikTok IDs are not rounded by a client or database.
- Run the lookup while the room is expected to be live, and treat an empty result as ended, unavailable, invalid, or mismatched rather than as a discovered offline-room record.
- Use collected_at as the observation time for status and metrics; created_at is null and url is empty in the normalized record.
Related APIs
Use these APIs when you need a different type of public TikTok data.
- TikTok Profiles API — Retrieve public profile identity, biographies, account flags, and audience counts by username.
- TikTok Hashtags API — Collect public videos, creators, media, sound, and engagement for specified hashtags.
- TikTok Comments API — Collect public top-level comments, authors, engagement, mentions, and creator interaction flags.
- TikTok Videos API — Retrieve creator, caption, media, music, tags, mentions, and engagement from video URLs.
- TikTok Search API — Search public videos by keyword with supported sorting and publication filters.
- TikTok Comment Replies API — Collect public replies for a known comment using its TikTok video URL and comment ID, with authors, engagement, timestamps, and parent context.
- TikTok Followers List API — Collect normalized profiles visible in public follower lists, with retained source context and supported metrics.
- TikTok Following List API — Collect public profiles followed by TikTok accounts with normalized identity, biographies, visible metrics, and source-account context.
- TikTok User Videos API — Collect public profile-feed videos by username with captions, creators, media, timestamps, engagement, and source-account context.
- TikTok Trending Feed API — Collect the current public video feed for a region with creator, caption, cover, timestamp, and visible engagement fields.
- TikTok Video Transcript API — Extract available transcript text, language, format, and source context from public video URLs.