TikTok User Live
A TikTok account’s live status describes whether it is streaming at a particular moment, while an active stream can have a room title, cover and viewer count. Keeping the creator’s identity and the time with that status helps readers see which account was streaming and how recent the information is.
Features
- Know whether a lookup found a live or offline accountEvery successful lookup returns is_live as true for live or false for offline, so an account that is not streaming still has a status record instead of simply disappearing from the results.
- See the room details for an active streamA live record can include the room title, creator name, cover image and viewer count, giving you information about the stream rather than only a yes-or-no status.
- Start with account handles rather than room identifiersLook up several public usernames in one request without first finding room_id and user_id, which are needed by the separate live-room-detail lookup.
Parameters
| Parameters | Required | Description |
|---|---|---|
usernames | Required | Required list of at least one public account handle, with or without @; in the Playground, place one username on each line, and in JSON use an array such as ["thejustalex", "@tiktok"] rather than profile URLs. |
How to Use
The request starts a background collection task, so its first response gives you a task ID rather than the finished data; use that ID to check progress and retrieve the results.
- Prepare one or more public usernames rather than profile or live-room links; you can copy the handle after @ from an account’s profile.
- Before running the example, replace $SOCQ_API_KEY with your own API key or set that environment variable. Send the JSON input to POST /v1/tiktok/user-live with the Authorization header shown below, then save the task_id from the response.
- Use GET /v1/tasks/{task_id} with the saved ID to check progress. queued means waiting, running means collection is in progress, and retrying means another attempt is underway. Wait for succeeded before reading the results; if the task is failed, read error_message for the reason.
- When the task succeeds, read data.results.items: each item in this list describes the status of one successfully checked account. An empty list means the task completed without returning any records.
- If data.results.has_more is true, the next_cursor value is the marker for another page of saved results. Copy it unchanged into the cursor parameter of GET /v1/tasks/{task_id}?cursor=... and continue until has_more is false.
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"]}'Best Use Cases
- Prepare an account live-status board: Build a table containing each creator, live or offline status and collection time, allowing someone to check which of the supplied accounts were streaming at the latest observation.
- Make a review list of active streams: Select the records with is_live=true and combine their room links, titles and viewer counts into a list of active rooms to open and review.
Pro Tips
- Before submitting a repeated list of handles, remove leading @ characters and deduplicate without case so tiktok and @TikTok do not inflate your input-count estimate.
- When a record says is_live=false, display it as offline and leave the missing room fields empty instead of reporting that the account lookup failed.
- For a status board that you refresh yourself, show collected_at next to the status so an earlier result is not mistaken for an observation made just now.
- If you already have a matching room_id and user_id and want a separate room lookup, use TikTok Live Room Info rather than submitting those IDs in the usernames field.
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 Live Room Info API — Look up one known live room by paired room and owner IDs, returning status, owner context, cover media, and audience counts.
- 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.
- TikTok Search Users API — Search public TikTok accounts by keyword.
- TikTok Song API — Retrieve public sound metadata by clip ID or music URL.
- TikTok Song Videos API — Collect public videos using specified sound IDs.
- TikTok Popular Songs API — Get the TikTok App Top 50 or Viral 50 songs chart, with track names, artists, sound IDs and available video counts.
- TikTok Top Search API — Search by keyword for videos and image posts, with captions, creators and interaction counts.