Douyin Live Room Detail API

Douyin Live Room Detail

Features

• Known-room detail lookupResolve one known numeric room_id into at most one normalized live_room record through a single source request without source pagination.
• Room and host contextKeep the available room title, status, host identity, source URL, and collection time together in one consistent shape.
• Visible session snapshotCapture available viewer and like counts alongside public media for a time-stamped view of the room.

Parameters

How to Use

Start with a known numeric room ID, submit the asynchronous detail task, then read its normalized stored result.

1. Obtain room_id from a live-room context that exposes the numeric identifier; this endpoint does not discover room IDs.
2. POST the identifier as a non-empty digit-only string to /v1/douyin/live-room-detail.
3. Poll /v1/tasks/{task_id} until status becomes succeeded or failed.
4. Read data.results.items from /v1/tasks/{task_id}?limit=50; a resolved room produces at most one item, while next_cursor belongs only to SocQ stored-result pagination.

# Set DOUYIN_ROOM_ID to a known numeric room_id before sending.
curl -X POST "https://api.socq.ai/v1/douyin/live-room-detail" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"room_id\":\"${DOUYIN_ROOM_ID}\"}"

# Poll GET /v1/tasks/{task_id}, then read data.results.items from /v1/tasks/{task_id}?limit=50.

Best Use Cases

• Live-room catalog enrichment: Add available title, status, host, media, visible metrics, and collection time to a catalog that already stores the room ID.
• Session-state snapshot tracking: Retain separately collected records with collected_at to distinguish point-in-time room status and audience observations.
• Host-room context review: Review the available host identity beside the room title, status, media, and visible session counts in one normalized record.

Pro Tips

• Submit room_id as a quoted digit-only string, not a JavaScript number, so a long identifier keeps every digit.
• Obtain a known room_id before calling the endpoint because the request performs detail retrieval rather than live-room discovery.
• Retain the submitted room_id in your own record; the canonical live-room result does not guarantee that the source echoes it as id.
• Treat title, status, author, metrics, media, URL, and timestamps as nullable because the source may omit individual public fields.
• Do not send results_limit or a source cursor; next_cursor, when present, paginates stored SocQ result items rather than the provider request.

Related APIs