Douyin Trending history API

Look up how trending phrases did over a past period: first_seen_at, last_seen_at, best_rank, peak_hot_value and is_on_board. hours sets how far back to look, for $0.79 per 1,000 calls.

  • board takes the hotspot, entertainment, social or challenge board.
  • hours looks back 1 to 168 hours, and the default is 24.
  • 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": "trending_history",
      "params": {}
    }
  2. 2JSON response

    {
      "results": [
        {
          "keyword": string,
          "board": string,
          "first_seen_at": …,
          "last_seen_at": …
        },
        …
      ]
    }
  3. 3Rows

    keywordboardfirst_seen_atlast_seen_at
    stringstring……
  4. 4CSV

    douyin-trending_history-sample.csv keyword,board,first_seen_at,last_seen_at,snapshot_count,best_rank,peak_hot_value,is_on_board,platform

A request, optionally with board and hours, goes in, and the phrases that were on the board in that period come back; each row in results is one phrase, listed as a field table and a CSV file.

What data you get

This endpoint has no public real sample yet. The table lists the fields, types and meanings that each row returns, with no values.

FieldTypeMeaning
keywordstringKeyword: the trending phrase on trending and trending_history, the search term on billboard_search_hot, the suggested search on search_suggest.
boardstringBoard the entry belongs to: hotspot, entertainment, social, challenge or seeding.
first_seen_at—When the term was first recorded on the board within the window (trending_history, ISO 8601, UTC).
last_seen_at—When the term was last recorded on the board within the window (trending_history, ISO 8601, UTC).
snapshot_count—How many times the term was recorded on the board in the window (trending_history); the board is recorded about every ten minutes.
best_rank—Best position the term reached in the window (trending_history); 1 is highest. Absent for pinned terms that have no rank.
peak_hot_value—Highest heat value the term reached in the window (trending_history), on the same scale as hot_value in trending.
is_on_board—Whether the term was still on the board at the latest snapshot (trending_history).
platformstringSource platform identifier, the same as platform in the request (for example xiaohongshu, tiktok).

Use cases

  • Find phrases that were on the board yesterday

    Set hours to 24 and read first_seen_at and last_seen_at to see which phrases stayed on the board only briefly.

  • Separate topics that dropped off

    A phrase with is_on_board set to false was off the board at the last recording. Compare it with the ones still there.

  • Rank topics by peak

    Sort by peak_hot_value from high to low, then check best_rank, to find the hottest phrases of the period.

  • Estimate how long a topic stayed

    snapshot_count is how many times the phrase was recorded on the board. Records come roughly every 10 minutes, so multiply to get a rough time on the board.

Limits and gotchas

  • board takes hotspot (default), entertainment, social or challenge. It does not take seeding.
  • hours takes 1 to 168, and the default is 24.
  • snapshot_count counts how many times the phrase was recorded on the board in the period, roughly one record every 10 minutes.
  • In best_rank, 1 is the highest. A pinned phrase with no rank has no such key.
  • first_seen_at and last_seen_at are ISO 8601 times in UTC.

Pricing

You pay $0.000792 per call, not per phrase. Failed calls and empty results are not charged.

CallsCost
10,000$7.92
100,000$79.17
1,000,000$791.67

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": "trending_history",
  "params": {}
}'

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 trending_history, 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 Trending history endpoint (douyin/trending_history).

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 trending_history, and put the parameters inside params.
- No required parameters.
- Optional parameters:
  - board: Board to read: hotspot (default), entertainment, social or challenge. (allowed: challenge / entertainment / hotspot / social)
  - hours: For trending_history: how many hours to look back, from 1 to 168 (default 24).
  - 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: keyword (Keyword: the trending phrase on trendin…), board (Board the entry belongs to: hotspot, en…), first_seen_at (When the term was first recorded on the…), last_seen_at (When the term was last recorded on the…), snapshot_count (How many times the term was recorded on…), best_rank (Best position the term reached in the w…), peak_hot_value (Highest heat value the term reached in…), is_on_board (Whether the term was still on the board…).
- Example request body:
{
  "platform": "douyin",
  "action": "trending_history",
  "params": {}
}
- Price: $0.79 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.
actionbodystringYestrending_historyCapability identifier, fixed value.
boardbody.paramsstring (enum)No-Board to read: hotspot (default), entertainment, social or challenge.Allowed valueschallengeentertainmenthotspotsocial
hoursbody.paramsintegerNo-For trending_history: how many hours to look back, from 1 to 168 (default 24).
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

#
No sample response is available for these parameters yet. This preview shows the response shape and fields from the API definition, with … as placeholders; it is not the result of a live call.
json
{  "id": "req_…",  "platform": "douyin",  "action": "trending_history",  "results": [    {      "keyword": …,      "board": …,      "first_seen_at": …,      "last_seen_at": …,      "snapshot_count": …,      "best_rank": …,      "peak_hot_value": …,      "is_on_board": …,      "platform": …    }  ],  "count": …,  "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
keywordKeyword: the trending phrase on trending and trending_history, the search term on billboard_search_hot, the suggested search on search_suggest.
boardBoard the entry belongs to: hotspot, entertainment, social, challenge or seeding.
first_seen_atWhen the term was first recorded on the board within the window (trending_history, ISO 8601, UTC).
last_seen_atWhen the term was last recorded on the board within the window (trending_history, ISO 8601, UTC).
snapshot_countHow many times the term was recorded on the board in the window (trending_history); the board is recorded about every ten minutes.
best_rankBest position the term reached in the window (trending_history); 1 is highest. Absent for pinned terms that have no rank.
peak_hot_valueHighest heat value the term reached in the window (trending_history), on the same scale as hot_value in trending.
is_on_boardWhether the term was still on the board at the latest snapshot (trending_history).
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 trending history API return?

One row per phrase: keyword, board, first_seen_at, last_seen_at, snapshot_count, best_rank, peak_hot_value and is_on_board.

How is it different from trending?

trending reads the board at the moment of the call, and each row is the current position of a phrase. trending_history reads the phrases that were on a board in a period, and each row sums up one phrase: first time on the board, last time, best rank and peak heat.

How much does one call cost?

It costs $0.000792 per call, or $0.79 per 1,000 calls, billed per call and not per phrase. 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