# Douyin Analytics 抖音数据分析 - Audience, Trends & Keywords (`clover_folktale/douyin-analytics-scraper`) Actor

Douyin analytics without login: follower and audience insight for accounts and creators, video performance and comment words, keyword heat index (巨量算数), related words, hot topics, category trends and search suggestions. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/clover_folktale/douyin-analytics-scraper.md
- **Developed by:** [Silkline](https://apify.com/clover_folktale) (community)
- **Categories:** Social media
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

Douyin Analytics 抖音数据分析 turns Douyin's trend and audience tools (热点宝 and 巨量算数) into data you can export. Get follower and audience insight for any tracked account or creator, performance, audience and comment words of a video, the keyword heat index and who searches a keyword, related words, live hot topics, content-category trends, videos by keyword, trend reports and search suggestions. No login or cookies needed. Export to JSON, CSV or Excel.

### What data can you get?

The Actor has eighteen modes. Each record has a `type` field that tells you which kind of record it is. Dates are in China time (UTC+8), as the source reports them.

| Mode | Give it | You get | Record `type` |
|---|---|---|---|
| `accountInsight` | Douyin profile links or sec_uid values | one record per account: daily follower change, last week's post performance against peers, follower profile (gender, age, province), accounts, topics and search words the followers care about | `accountInsight` |
| `videoInsight` | Douyin video links or IDs; optional `days` | one record per video: real play count and engagement, daily performance with benchmarks, viewer profile, index scores, hourly likes, provinces of the viewers who liked it, comment word cloud | `videoInsight` |
| `creatorIndex` | Douyin user IDs, sec_uid values, profile links or names; optional `days` | one record per creator: weekly and monthly averages, follower profile, the creator's best videos of the period | `creatorIndex` |
| `similarCreators` | the same creator references | up to 20 creators the source finds similar | `similarCreator` |
| `keywordTrend` | keywords; optional `days` and `region` | one record per keyword: daily content and search index, averages against the previous period and last year, the videos and searches behind the peaks, interpretation | `keywordTrend` |
| `keywordAudience` | keywords; optional `days` | one record per keyword: who searches it, by age, gender, province and more | `keywordAudience` |
| `relatedWords` | keywords | words related to each keyword through video content and through searches, last full week | `relatedWord` |
| `hotTopics` | a list (`hotList`); keywords for two of the lists | rows of live hot topics, rising topics, popular keywords, trending words, topic search results, or the videos under a hot topic | `hotTopic` |
| `keywordSuggestions` | keywords; `suggestionType` | rows of search-box suggestions, matching trending videos or matching topics | `suggestion` |
| `indexVideos` | keywords; optional filters | up to 1,000 videos per keyword with the source's index and hit flags (low-follower hit, high like rate, high completion rate, high follower growth) | `indexVideo` |
| `categoryInsight` | content categories | one record per category for the last full week: top keywords and topics, publishing, interaction and consumption trends, video length classes | `categoryInsight` |
| `reports` | optional keywords | trend reports of the index service (the recommended ones without a keyword) | `report` |
| `creatorCompare` | Douyin user IDs (numbers only); optional `comparePeriod` (`7days` or `30days`) | one record per creator: what the creator gained in the last 7 or 30 days (likes, comments, shares, new followers, posts), the averages per post, and the growth rates against the period before | `creatorCompare` |
| `reportDetail` | report IDs, as the `reports` mode returns them | one record per report: title, publisher, summary, keywords, visits, downloads, file link and page images | `reportDetail` |
| `reportRecommendations` | report IDs, as the `reports` mode returns them | the reports recommended next to each report (about 4 rows per report) | `reportRecommendation` |
| `creatorActivities` | optional `days` | the creator center's platform activities running in the next days (default 30) | `creatorActivity` |
| `creatorCourses` | optional `courseOrder` | the creator center's hot courses (about 30 in total) | `creatorCourse` |
| `creatorCourseList` | `courseCategoryId`; optional `courseOrder` | the courses of one creator-center category (hundreds), newest, most popular or recommended first | `creatorCourse` |

#### Account insight (`accountInsight`)

| Field | What it is |
|---|---|
| `secUid`, `url` | The account and its Douyin page |
| `followerChangeTrend` | Daily follower change, `{date, change}`, about 90 days |
| `followerChangeAverage` | Average of that daily change |
| `performance` | Last week's per-post averages (`posts`, `comments`, `shares`, `newFollowers`, `likes`), each with `average`, `peerAverage` and the two rates the source reports (`averageRate`, `peerRate`) |
| `fansPortrait` | Follower profile: `gender`, `age`, `province`, each a list of `{name, share, index}`. `share` is 0-1; `index` compares with the average Douyin user (100 = average) |
| `fansAlsoFollow` | Up to 20 accounts the followers also follow |
| `fansTopics` | Up to 20 topics the followers recently engage with |
| `fansSearchWords` | Up to 100 words the followers searched for in the last 3 days, with `heat` |

The source tracks accounts that have been seen in its hot lists, so a small or very new account can return nothing. Nothing is charged for an account that returns nothing.

#### Video insight (`videoInsight`)

| Field | What it is |
|---|---|
| `videoId`, `url`, `title`, `authorId`, `publishedAt`, `durationSeconds`, `cover` | The video |
| `plays`, `likes`, `comments`, `favorites`, `shares`, `interactionRate` | Real play count and engagement as the creator marketplace shows them. Empty for videos it does not track |
| `performance` | `index`, `likes`, `comments`, `shares`, each with `total`, `change`, `daily` (a point per day of the period) and `benchmarks` (`category`, `author`, `duration`, each `max` and `average`) |
| `audience` | Viewer profile by group (age, gender, province and more), each a list of `{name, share, index}` |
| `interpretation` | Index scores of the video and its category for plays, interactions and follower growth, and the video's `rank` (`score`, `percentile`, `level`) |
| `likesTrendHourly` | Cumulative likes by hour |
| `likerProvinces` | Provinces of the viewers who liked the video |
| `commentWords` | Up to 80 comment words with `weight` |

Some parts exist only for videos that are trending; for the others those fields are empty. A video the source knows nothing about (an old one, for example) returns nothing and is not charged.

#### Keyword trend (`keywordTrend`)

| Field | What it is |
|---|---|
| `keyword`, `startDate`, `endDate` | The keyword and the period (ends yesterday; `days` sets its length, default 14) |
| `contentIndex`, `searchIndex` | Daily content index and search index, `{date, index}` |
| `average`, `previousPeriodAverage`, `lastYearAverage` | `{content, search}` averages |
| `contentPeaks` | The videos behind the content-index peaks |
| `searchPeaks` | The searches behind the search-index peaks |
| `interpretation` | Content, consume and search index of the period and the change against the previous period and last year |

Up to five keywords are asked together; each keyword is one record.

#### Hot topics (`hotTopics`)

`hotList` chooses what the rows are. Every row has the same fields; the ones a list does not carry are `null`.

| `hotList` | Rows | Needs keywords |
|---|---|---|
| `realtime` | 30 live hot topics with `index`, `videoCount`, `plays`, `category` | no |
| `rising` | 30 fastest-rising topics | no |
| `hotWords` | 20 popular keywords with `index`, `growth`, `growthRate` | no |
| `recommendedWords` | 5 recommended trending words | no |
| `topicSearch` | up to 100 topics matching each keyword, with `topicId`, `index`, `videoCount`, `likes`, `plays` | yes |
| `topicDetail` | up to 50 best videos under each hot topic name, with `videoId`, `url`, `authorName`, `plays`, `likes`, `comments` | yes |

#### Keyword suggestions (`keywordSuggestions`)

| `suggestionType` | What you get per keyword |
|---|---|
| `topic` (default) | up to 20 matching topics as rows, with `topicId` |
| `video` | up to 20 matching trending videos as rows, with `videoId`, `url`, `authorName`, `likes`, `index`, `category` |
| `searchBox` | one record (`type` `searchBoxSuggestions`) with the phrases Douyin's search box suggests in the list `suggestions`; the source often returns only a few |

Rows (`topic`, `video`) carry `source`, `keyword`, `rank` and `suggestion` (the video title or topic).

#### Creator index (`creatorIndex`)

Give it a Douyin user ID, a sec_uid, a profile link or a name. A name is searched in the source's creator search: the first creator whose nickname is exactly the name is used, and if none matches exactly, the first search result is used. That result can be a different person, so prefer an ID or a profile link.

| Field | What it is |
|---|---|
| `uid`, `secUid`, `nickname`, `url` | The creator (`secUid`, `nickname` and `url` are filled when the input was a link or a name) |
| `averages` | `likes`, `followers`, `shares`, `comments`, each with `weekAverage`, `monthAverage` and the growth rates `weekChange`, `monthChange` as the source reports them |
| `fansProfile` | Follower profile: `gender`, `age`, `province`, `city`, `cityTier`, `deviceBrand`, `devicePrice`, `interest`; each a list of `{name, share, index}` |
| `topVideos` | The best videos of the period (`days`, default 30): `byLikes`, `byComments`, `byShares`, `byNewFollowers`, `byIndex`, `latest`; each with `videoId`, `url`, `title`, `likes`, `comments`, `shares`, `newFollowers`, `date` |

A creator the index does not track returns nothing and is not charged.

#### Similar creators (`similarCreators`)

Up to 20 rows per creator: `similarTo`, `rank`, `nickname`, `secUid`, `url`, `douyinId`, `avatar`, `followers`, `likes`, `posts`, `category`, `subCategory`.

#### Keyword audience (`keywordAudience`)

One record per keyword: `keyword`, `startDate`, `endDate` and `audience`, the profile of the people searching it by age, gender, province and more, each group a list of `{name, share, index}`.

#### Related words (`relatedWords`)

Rows per keyword for the last full week (Monday to Sunday): the words related through video content (`source` = `content`, with `sampleVideos`) followed by those related through searches (`source` = `search`, with `sampleQueries`). Fields: `word`, `score`, `scoreRank`, `scoreChangePercent`, `searchHeat`, `compositeIndex`.

#### Videos for a keyword (`indexVideos`)

Up to 1,000 videos per keyword, ranked by the source's index. Fields: `videoId`, `url`, `title`, `cover`, `likes`, `durationSeconds`, `authorName`, `authorAvatar`, `authorFollowers`, `publishedAt`, `index`, and the flags `lowFollowerHit`, `highLikeRate`, `highCompletionRate`, `highFollowerGrowth`. Filter with `videoCategory`, `publishedWithin`, `videoLabel` and `videoDuration`. The rows carry fewer fields than a search in the Douyin Scraper (no comment or share counts).

#### Category insight (`categoryInsight`)

One record per category and last full week: `hotKeywords` (50), `hotTopics` (50), `publishTrend`, `interactionTrend`, `supplyTrend`, `consumptionTrend` (daily `{date, rate}`) and `durationBreakdown` (content share, interaction rate and completion rate per video length). Categories are slugs such as `food`, `travel`, `tech`; the full list is in the input field.

#### Trend reports (`reports`)

Rows: `reportId`, `title`, `author`, `summary`, `keywords`, `reportType`, `publishedAt`, `visits`, `downloads`, `cover`, `fileUrl`. With keywords the reports are searched; without, the recommended reports (about 70) are listed.

#### Creator comparison (`creatorCompare`)

Give it Douyin user IDs (numbers). sec_uid values, links and names are not accepted by this mode; the `creatorIndex` mode shows the `uid` of a creator. Every ID is looked up on its own, so one unknown ID never spoils the others; an ID the source does not know returns nothing. `comparePeriod` is `7days` (default) or `30days`, ending yesterday.

| Field | What it is |
|---|---|
| `uid`, `secUid`, `nickname`, `url`, `avatar` | The creator |
| `followers`, `totalLikes`, `totalPosts` | Current totals |
| `periodDays` | Length of the compared period |
| `periodTotals` | Gains in the period: `likes`, `comments`, `shares`, `newFollowers` (can be negative), `posts` |
| `periodTotalsChange` | The same five figures as growth rates against the period before, as the source reports them |
| `perPostAverages` | Averages per post in the period: `likes`, `comments`, `shares`, `newFollowers` |
| `perPostAveragesChange` | The same four averages as growth rates against the period before, as the source reports them |

The figures are totals and averages of the period, not a daily series.

#### Report detail and recommendations (`reportDetail`, `reportRecommendations`)

Both modes take `reportIds`: the numbers the `reports` mode returns in `reportId`. `reportDetail` returns one record per report with `reportId`, `title`, `author`, `summary`, `keywords`, `reportType`, `publishedAt`, `visits`, `downloads`, `cover`, `fileUrl`, `fileName`, `pageImages` (links to the page images, in order) and `partnerInstitution`. Older reports are no longer available and return nothing, as does an ID that does not exist. `reportRecommendations` returns about 4 rows per report (`relatedTo` is the report you asked about, plus `rank`, `reportId`, `title`, `author`, `summary`, `keywords`, `reportType`, `publishedAt`, `cover`, `fileUrl`); an unknown ID returns no rows.

#### Creator center (`creatorActivities`, `creatorCourses`, `creatorCourseList`)

`creatorActivity` rows (about a dozen per run, one request, no paging): `rank`, `activityId`, `name`, `startAt`, `endAt` (UTC), `hotScore`, `activityLevel`, `activityType`, `cover`, `link` (an in-app `aweme://` link that opens only in the Douyin app), `topicIds`. The window is the next `days` days from now.

`creatorCourse` rows: `rank` (as the source reports it), `courseId`, `title`, `videoId`, `url`, `description`, `authorId`, `authorName`, `cover`, `durationSeconds`, `publishedAt`, `plays`, `likes`, `comments`, `favorites`, `shares`, `collections` (how many creators saved the course). Courses come 24 per page and further pages are fetched only while `maxResults` is not reached. `creatorCourses` lists the hot courses of all categories; `creatorCourseList` lists one category (`courseCategoryId`, default 180 with a few hundred courses).

### How to use Douyin Analytics

1. Choose a mode.
2. Fill in the field that mode reads: `accounts`, `videos`, `creators`, `keywords`, `categories` or `reportIds`. The hot-topic lists, `recommendedWords` and `reports` need no input.
3. Set `maxResults` and start the run. Download the dataset as JSON, CSV or Excel.

### Input

| Field | Used by | What it is |
|---|---|---|
| `mode` | all | See the table above |
| `accounts` | `accountInsight` | Douyin profile links or sec_uid values (start with `MS4wLjAB`) |
| `videos` | `videoInsight` | Douyin video links or video IDs. Short share links are not supported |
| `keywords` | `keywordTrend`, `keywordAudience`, `relatedWords`, `keywordSuggestions`, `indexVideos`, `reports` (optional), `hotTopics` (two lists) | Keywords in Chinese; a comma splits an entry |
| `creators` | `creatorIndex`, `similarCreators`, `creatorCompare` | Douyin user IDs, sec_uid values, profile links or names (`creatorCompare`: user IDs only) |
| `comparePeriod` | `creatorCompare` | `7days` (default) or `30days` |
| `reportIds` | `reportDetail`, `reportRecommendations` | Report IDs as the `reports` mode returns them (numbers such as 1081) |
| `categories` | `categoryInsight` | Category slugs such as `food` (default), `travel`, `tech` |
| `region` | `keywordTrend` | Show the trend for one province (34 choices in the input form, e.g. 北京, 广东; `all` = nationwide). `keywordAudience` has no region filter at the source | `all` |
| `days` | `videoInsight`, `creatorIndex`, `keywordTrend`, `keywordAudience`, `creatorActivities` | Period length in days (1-30), ending yesterday. Default 7, 30 for `creatorIndex`, 14 for the keyword modes. For `creatorActivities` it is how many days ahead to list (default 30) |
| `courseOrder`, `courseCategoryId` | `creatorCourses`, `creatorCourseList` | `courseOrder`: `recommended` (default), `popular`, `latest`. `courseCategoryId`: the course category to list (`creatorCourseList` only, default 180) |
| `hotList` | `hotTopics` | `realtime` (default), `rising`, `hotWords`, `recommendedWords`, `topicSearch`, `topicDetail` |
| `suggestionType` | `keywordSuggestions` | `topic` (default), `video`, `searchBox` |
| `videoCategory`, `publishedWithin`, `videoLabel`, `videoDuration` | `indexVideos` | Filters for the video rows |
| `maxResults` | all | Total records or rows for the run (default 20) |

Example, one account:

```json
{ "mode": "accountInsight", "accounts": ["https://www.douyin.com/user/MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"] }
```

### Output example

A `hotTopic` row (`hotList: "realtime"`):

```json
{
  "type": "hotTopic",
  "list": "realtime",
  "rank": 1,
  "name": "Example topic",
  "index": 12106513,
  "category": "科技",
  "videoCount": 7,
  "plays": 5944814,
  "query": null,
  "topicId": null
}
```

A `keywordTrend` record (shortened):

```json
{
  "type": "keywordTrend",
  "keyword": "美食",
  "startDate": "2026-10-12",
  "endDate": "2026-10-25",
  "contentIndex": [{ "date": "2026-10-12", "index": 3666303 }],
  "searchIndex": [{ "date": "2026-10-12", "index": 7205382 }],
  "average": { "content": 4050895, "search": 8398212 },
  "interpretation": { "contentIndex": 7549385, "consumeIndex": 13890646, "searchIndex": 35272502 }
}
```

### How much does it cost?

The Actor uses pay-per-event pricing. These are the current prices:

| Event | Price | When it is charged |
|---|---|---|
| Run start | $0.005 | Once per run, when the first request to the data source succeeds, even if that request returns nothing. Not charged when the data source fails from the start or rejects the inputs, or when your spending limit cannot cover it. In `creatorCompare`, `reportDetail` and `reportRecommendations` every input after the first one costs the source a request of its own, so it is charged one more run start before it is looked up |
| Insight | $0.03 | Per record of the modes `accountInsight`, `videoInsight`, `creatorIndex`, `creatorCompare`, `reportDetail`, `keywordTrend`, `keywordAudience` and `categoryInsight`, and per keyword of `keywordSuggestions` with `suggestionType` `searchBox` |
| Row | $0.003 | Per row of the modes `similarCreators`, `relatedWords`, `hotTopics`, `indexVideos`, `reports`, `reportRecommendations`, `creatorActivities`, `creatorCourses`, `creatorCourseList` and `keywordSuggestions` (types `topic` and `video`) |

Worked examples:

- 10 account insights: $0.005 + 10 x $0.03 = $0.305.
- 5 video insights: $0.005 + 5 x $0.03 = $0.155.
- 3 keyword trends: $0.005 + 3 x $0.03 = $0.095.
- The 30 live hot topics: $0.005 + 30 x $0.003 = $0.095.
- Topic suggestions for 5 keywords (up to 100 rows): at most $0.005 + 100 x $0.003 = $0.305.
- Search-box suggestions for 5 keywords (5 records): $0.005 + 5 x $0.03 = $0.155.
- 5 creator indexes: $0.005 + 5 x $0.03 = $0.155.
- 100 related words of one keyword: $0.005 + 100 x $0.003 = $0.305.
- 200 videos for one keyword: $0.005 + 200 x $0.003 = $0.605.
- Insights of 3 categories: $0.005 + 3 x $0.03 = $0.095.
- Comparison of 1 creator: $0.005 + $0.03 = $0.035. Each further creator or report ID is looked up on its own and also pays the $0.005 start: 3 creators = 3 x $0.035 = $0.105.
- Details of 2 reports: 2 x ($0.005 + $0.03) = $0.07.
- Recommendations for 1 report (about 4 rows): $0.005 + 4 x $0.003 = $0.017.

You never pay for more than `maxResults` items, items that were not delivered are never charged, and the run stops by itself if your spending limit is reached. Before each insight record the run checks that your limit still covers its $0.03, and stops without fetching it if not; parts the data source cannot deliver stay empty and do not change the price.

On the free Apify plan, every run returns a sample dataset: a real result of this Actor's prefilled input, captured on the date shown in the run status, so you can see exactly what the output looks like. Your own input is not used and nothing is charged. To run your own queries, use any paid Apify plan.

### Use cases

- Check an influencer's audience (age, gender, province, what the followers search for) before a campaign.
- Judge why a video took off: performance against its category, viewer profile, comment words.
- Find what to make next: keyword heat, related words, search suggestions, category trends, videos that hit from low-follower accounts.
- Track live hot topics and trending words every day.
- Read the source's trend reports in bulk.

### Integrations and API

Start runs through the Apify API, schedule them, or connect the dataset to your tools. Python example:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("clover_folktale/douyin-analytics").call(run_input={"mode": "keywordTrend", "keywords": ["美食", "咖啡"]})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["keyword"], item["average"])
```

### Tips and limits

- `maxResults` is the total across all inputs in the run; a run stops as soon as it is reached.
- Accounts, videos and keywords the source has no figures for are skipped and not charged; if too many inputs return nothing, the run stops to protect your budget.
- The source's account and video analytics cover what is trending; start from a hot list or a keyword to find accounts and videos worth analysing.
- Weekly figures (`relatedWords`, `categoryInsight`) cover the last full Monday-to-Sunday week.
- A creator given by name: the first result whose nickname is exactly the name is used, otherwise the first search result, which may be a different person. Use an ID or a profile link when it matters which creator you mean.
- Index figures (content, search, consume) are the source's own relative heat scores, not view counts.
- Times are in China time (UTC+8). Shares are fractions (0.25 = 25%).
- The Actor retries transient errors on its own and stops cleanly instead of failing half-way.
- **Free plan.** Every run on the free Apify plan returns a stored sample dataset (a real result of the prefilled input); your own input is not used and nothing is charged. Use any paid Apify plan to run your own queries.

### FAQ

#### Do I need a Douyin account?

No. You do not need a Douyin account, API keys, proxies or cookies.

#### Is it legal?

The Actor returns aggregate figures and public lists that Douyin's own trend and audience tools publish: follower and viewer statistics by group, trend curves, hot lists and search suggestions. It returns no private personal data.

#### How fresh is the data?

Every run reads the figures the source shows at that moment. Hot lists change through the day; account and video figures are daily.

#### Why are some fields empty?

Some parts exist only for some accounts or videos (for example the like-audience of a video is published for trending videos only). See the field tables above.

#### Can I schedule runs and export the data?

Yes. You can schedule runs in Apify Console or start them through the API, and export every dataset as JSON, CSV or Excel.

#### A field or mode I need is missing. What can I do?

Open an issue from the Actor page and it will be looked at.

### More tools from the same developer

- [Douyin 抖音 Scraper - Videos, Comments, User IDs & IP Location](https://apify.com/clover_folktale/douyin-scraper)
- [Douyin Xingtu 巨量星图 Scraper - KOL Search & Rankings](https://apify.com/clover_folktale/xingtu-scraper)
- [Douyin Shop 抖音商城 Scraper - Products, Sales, Commission](https://apify.com/clover_folktale/douyin-shop-scraper)
- [TikTok Scraper - Video Search, Hashtags & Author Profiles](https://apify.com/clover_folktale/tiktok-scraper)

# Actor input Schema

## `mode` (type: `string`):

What to fetch: an analysis record per account, video, creator, keyword or content category; or rows of similar creators, related words, suggestions, hot topics, videos and trend reports, and the creator center's activities and courses; a creator's period comparison; the full record of a trend report; the reports recommended next to a report.

## `accounts` (type: `array`):

Douyin profile links (https://www.douyin.com/user/...) or sec_uid values (they start with MS4wLjAB). Each account is one insight record. Works for accounts the source tracks; an unknown account returns nothing. Falls back to a sample account when empty.

## `videos` (type: `array`):

Douyin video links (https://www.douyin.com/video/...) or video IDs (long numbers). Short share links are not supported. Videos from the last weeks that have drawn attention work best; an old or unknown video returns nothing.

## `keywords` (type: `array`):

Keywords or topic names, in Chinese. keywordTrend, keywordAudience: one record per keyword. relatedWords, keywordSuggestions, indexVideos: rows per keyword. reports: optional, searches the reports (empty lists the recommended ones). hotTopics: needed only for the topicSearch and topicDetail lists.

## `days` (type: `integer`):

Length of the period that ends yesterday. Default: 7 days for videoInsight, 14 for keywordTrend and keywordAudience, 30 for creatorIndex. creatorActivities: how many days ahead to list activities for (default 30).

## `region` (type: `string`):

Show the keyword trend for one province instead of the whole country. Default: nationwide. Not available for keywordAudience, whose source has no region filter.

## `hotList` (type: `string`):

realtime: the live hot topics (30). rising: fastest-rising topics (30). hotWords: popular keywords (20). recommendedWords: recommended trending words (5). topicSearch: topics matching each keyword (up to 100). topicDetail: the best videos under each hot topic name (up to 50).

## `suggestionType` (type: `string`):

topic: matching topics (up to 20 rows per keyword). video: matching trending videos (up to 20 rows). searchBox: what Douyin's search box suggests, one record per keyword with the phrases in a list (often only a few).

## `maxResults` (type: `integer`):

Maximum number of records or rows to return in total for this run. You are charged per record or row returned.

## `creators` (type: `array`):

Douyin user IDs (numbers), sec_uid values, Douyin profile links, or creator names (the best match of a name search is used, so prefer an ID or link). Each creator is one record (creatorIndex) or up to 20 rows (similarCreators). Works for creators the source tracks. creatorCompare takes Douyin user IDs (numbers) only; each ID is one record and is looked up on its own.

## `categories` (type: `array`):

Content categories, one record per category for the last full week (Monday to Sunday). Empty means food. One of: drama, celebrity, variety, movies, tv-series, music, anime, games, society, public-welfare, casual-shots, dance, animals, agriculture, tech, finance, mom-baby, parenting, home-life, law, health, science, emotion, culture, workplace, education, photography, food, travel, fashion, art, sports, entertainment, auto, life-records.

## `videoCategory` (type: `string`):

Only videos of this content category.

## `publishedWithin` (type: `string`):

Only videos published in this period.

## `videoLabel` (type: `string`):

Only videos flagged by the source: a hit from a low-follower account, a high completion rate, high follower growth or a high like rate.

## `videoDuration` (type: `string`):

Only videos of this length.

## `courseOrder` (type: `string`):

recommended: the source's own order. popular: most popular first. latest: newest first.

## `courseCategoryId` (type: `integer`):

Number of the creator-center course category to list (180 is a large one). creatorCourses lists the hot courses across all categories and ignores it.

## `comparePeriod` (type: `string`):

Length of the period that ends yesterday: the creator's gains in it are compared with the period before.

## `reportIds` (type: `array`):

Report IDs, as the reports mode returns them in reportId (numbers such as 1081). reportDetail gives each report as one record (older reports are not available and return nothing); reportRecommendations gives the reports recommended next to each (about 4 rows).

## Actor input object example

```json
{
  "mode": "accountInsight",
  "accounts": [
    "MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"
  ],
  "region": "all",
  "hotList": "realtime",
  "suggestionType": "topic",
  "maxResults": 20,
  "creators": [
    "https://www.douyin.com/user/MS4wLjABAAAAInYK7Wk_cCLwFlhAvpgeYFSXDQwUWmemBCsyCYtKOOI"
  ],
  "videoCategory": "any",
  "publishedWithin": "any",
  "videoLabel": "any",
  "videoDuration": "any",
  "courseOrder": "recommended",
  "courseCategoryId": 180,
  "comparePeriod": "7days"
}
```

# Actor output Schema

## `results` (type: `string`):

All scraped items (JSON, CSV, Excel via the dataset API).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "accounts": [
        "MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"
    ],
    "creators": [
        "https://www.douyin.com/user/MS4wLjABAAAAInYK7Wk_cCLwFlhAvpgeYFSXDQwUWmemBCsyCYtKOOI"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("clover_folktale/douyin-analytics-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "accounts": ["MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"],
    "creators": ["https://www.douyin.com/user/MS4wLjABAAAAInYK7Wk_cCLwFlhAvpgeYFSXDQwUWmemBCsyCYtKOOI"],
}

# Run the Actor and wait for it to finish
run = client.actor("clover_folktale/douyin-analytics-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "accounts": [
    "MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"
  ],
  "creators": [
    "https://www.douyin.com/user/MS4wLjABAAAAInYK7Wk_cCLwFlhAvpgeYFSXDQwUWmemBCsyCYtKOOI"
  ]
}' |
apify call clover_folktale/douyin-analytics-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clover_folktale/douyin-analytics-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/89WRBgVlV8MEBrGIh/builds/lmfbYpMUJkkU0hDF1/openapi.json