Douyin Broadcast viewer ranking API

Read the viewer list of one Douyin live session by live_id. Each row is one viewer, with rank, nickname, douyin_id, user_id and is_verified, for $0.56 per 1,000 calls.

  • One call gives the whole list, with no paging.
  • rank starts at 1 and follows the order of the list.
  • Failed calls and empty results are not charged.

API health

24h health
Normal
  • Healthy / normal
  • Available
  • Limited
  • Mostly down
Normal

Last 24 hours

Last 30 days

  1. 1Request

    POST /api/v1/social
    {
      "platform": "douyin",
      "action": "live_viewers",
      "params": {
        "live_id": "7710380709042457398"
      }
    }
  2. 2JSON response

    {
      "results": [
        {
          "user_id": "",
          "rank": 1,
          "is_verified": false
        },
        …
      ],
      "count": 106
    }
  3. 3Rows

    user_idrankis_verified
    1false
    2false
  4. 4CSV

    douyin-live_viewers-sample.csv rank,user_id,douyin_id,nickname,avatar_url,is_verified,url,platform

A request with live_id goes in, and the viewer list of that session comes back; each row in results is one viewer, listed as a field table and a CSV file.

What data you get

The table shows a real call for 7710380709042457398, captured November 21, 2026 at 07:29 (UTC), that returned 106 rows; gray bars mark removed personal information (••• in the CSV). Your own calls return these fields as listed in the field reference.

rankuser_iddouyin_idnicknameavatar_urlis_verifiedurlplatform
1五•••伟falsedouyin.com/douyin
2努•••falsedouyin.com/douyin

Use cases

  • See the main viewers of a stream

    Read the list by rank to see which accounts rank first.

  • Identify viewer accounts

    user_id, douyin_id and url point to the viewer's account, and nickname is the display name.

  • Pick out verified accounts

    Read is_verified to find the verified viewers on the list.

  • Pair it with the session details

    Pass the same live_id to live_session and read the title, host and like count of the session together.

Limits and gotchas

  • live_id is required. It is the all-digit session number from the live_id on rows returned by live_room or user_live. It changes each time the room goes live and is not the number in the live room link.
  • The list comes in one call, with no paging.
  • After the session ends, only a few viewers remain on the list.
  • rank starts at 1 and is the viewer's place on the list.
  • user_id, douyin_id and nickname are account details of the viewer, and the sample hides them.
  • One call reads the list of one session.

Pricing

You pay $0.000556 per call, not per row, and one call reads the whole list of a session. Failed calls and empty results are not charged.

CallsCost
10,000$5.56
100,000$55.56
1,000,000$555.56

Totals use the list price per call.

Code samples

#
bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "douyin",
  "action": "live_viewers",
  "params": {
    "live_id": "7710380709042457398"
  }
}'

OpenAPI definition (JSON)Samples read the key from the EVERYINFRA_API_KEY environment variable; copied code never contains your key.

API reference

See the parameters, response fields, errors and billing for live_viewers, and copy the page or open it as Markdown for an AI assistant.

POST

AI prompt

#
Please help me write a data collection script with the EveryInfra Douyin Broadcast viewer ranking endpoint (douyin/live_viewers).

How the endpoint works:
- Request: POST https://api.everyinfra.com/api/v1/social with the header Authorization: Bearer <API key>. Read the key from the EVERYINFRA_API_KEY environment variable and never hard-code it.
- In the request body, set platform to douyin and action to live_viewers, and put the parameters inside params.
- Required parameters:
  - live_id: The numeric ID of one broadcast, from the live_id of live_room or user_live rows. It changes each time the host goes live and is not the number in the live-room link.
- Optional parameters:
  - limit: The most rows to return in this call, an integer of 1 or more. The default applies when you leave it out, and a call can return fewer rows.
- Returns a list of records. Main fields of each record: rank (Position from 1: the trending rank on t…), user_id, douyin_id (Douyin ID: the searchable ID the accoun…), nickname (Display name of the account), avatar_url, is_verified, url.
- Example request body:
{
  "platform": "douyin",
  "action": "live_viewers",
  "params": {
    "live_id": "7710380709042457398"
  }
}
- Price: $0.56 per 1,000 requests; failed and empty results are not charged.
- For dozens or hundreds of targets, add "mode": "async" to the body: you get a job_id at once and poll GET https://api.everyinfra.com/api/v1/jobs/{job_id} for the result.
- On 422, fix the request using the suggested parameter names and allowed values in the error; on 429 or 503, wait for Retry-After and try again.

Before writing code, ask me which targets I need, how many, which fields, and what output format I want; then confirm the plan and the rough cost with me.

Request parameters

#
NameInTypeRequiredDefaultDescription
AuthorizationheaderstringYes-Bearer followed by your API key. Create it in the console; never put it in a URL or a code repository.
platformbodystringYesdouyinPlatform identifier, fixed value.
actionbodystringYeslive_viewersCapability identifier, fixed value.
live_idbody.paramsstringYes-The numeric ID of one broadcast, from the live_id of live_room or user_live rows. It changes each time the host goes live and is not the number in the live-room link. After the broadcast ends only a few viewers remain on the list.
limitbody.paramsinteger (1–)No-The most rows to return in this call, an integer of 1 or more. The default applies when you leave it out, and a call can return fewer rows.

Response example

#
Captured November 21, 2026 at 07:29 (UTC) by calling this API with the parameters in the code sample above. results and count are that call's real response with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2. id, billing and quota differ on every call, so only their shape is shown.
json
{  "id": "req_…",  "platform": "douyin",  "action": "live_viewers",  "results": [    {      "rank": 1,      "user_id": "•••",      "douyin_id": "•••",      "nickname": "五•••伟",      "avatar_url": "https://p11.douyinpic.com/•••",      "is_verified": false,      "url": "https://www.douyin.com/•••",      "platform": "douyin"    },    {      "rank": 2,      "user_id": "•••",      "douyin_id": "•••",      "nickname": "努•••",      "avatar_url": "https://p11.douyinpic.com/•••",      "is_verified": false,      "url": "https://www.douyin.com/•••",      "platform": "douyin"    }  ],  "count": 106,  "billing": {    "charged": …,    "charged_usd": …,    "balance_after_usd": …,    …  },  "quota": { … }}

Response fields

#

Business data is in results. The table lists the fields a record can contain; values the platform does not show are never made up.

FieldMeaning
rankPosition from 1: the trending rank on trending, the position on the Xingtu board on xingtu_creator_rankings, the position on the search board on billboard_search_hot, and the suggestion's place in Douyin's search box on search_suggest.
user_idUser's unique ID on the platform.
douyin_idDouyin ID: the searchable ID the account holder chooses.
nicknameDisplay name of the account.
avatar_urlAvatar image link. Some platforms return sized CDN links that can expire.
is_verifiedWhether the platform verified the account. null means it cannot be determined.
urlLink to the record on the platform.
platformSource platform identifier, the same as platform in the request (for example xiaohongshu, tiktok).

Errors and billing

#
401
Missing or invalid key.
402
Insufficient balance. Top up first.
422
Invalid parameter name or value. Fix it using the suggestions in the error. No charge.
429
Per-minute request limit reached. Wait for Retry-After, then try again.
503
Could not complete. The held charge is returned to your balance. If the outcome is unknown, verify it before you retry.
200 empty
No data. No charge.

Errors

FAQ

What does the Douyin live viewers API return?

One viewer per row: rank, user_id, douyin_id, nickname, avatar_url, is_verified and url.

Why is the list short after the stream ends?

After the session ends, only a few viewers remain on the list.

Where does live_id come from?

Take it from a row returned by live_room or user_live. It is the session number and changes each time the room goes live; it is not the number in the live room link.

How much does it cost to read a viewer list?

$0.000556 per call, or $0.56 per 1,000 calls, counted by calls and not by rows. Failed calls and empty results are not charged.

You can call the other Douyin endpoints with the same EveryInfra API key.

Google Analytics needs consent. Privacy