# Douyin 抖音 Video Scraper - Metadata (`insights_data/douyin-video-scraper-metadata`) Actor

Scrape Douyin (抖音) videos and image posts from links, share links or IDs. Get caption, author, music, likes, comments, shares, hashtags, video quality links and post date as clean JSON. Optional MP4, cover and image downloads. Bulk input, no account or cookies needed.

- **URL**: https://apify.com/insights_data/douyin-video-scraper-metadata.md
- **Developed by:** [Insights Data](https://apify.com/insights_data) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.50 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

### What is the Douyin video scraper?

**Douyin 抖音 Video Scraper - Metadata** is a Douyin video scraper for marketers, researchers and developers. Paste Douyin links, share links or video IDs, and you get the text, author, music, likes, comments, shares, saves, hashtags, media links and posting date of every public video or image post. On the Apify Free plan you can save up to **10 videos per run**, and paid Apify plans have no per-run cap. Just paste your links and click **Start**. You don't need to write code, a Douyin account or cookies.

Douyin (抖音) is often called the **Chinese TikTok**: it is the short-video app used in mainland China. This Actor works as a **TikTok China scraper** for the videos and posts you list. In Chinese, this kind of tool is called a 抖音爬虫 (Douyin crawler).

- **Douyin marketing research:** see which posts, sounds and hashtags get the most likes, shares and saves in your niche.
- **Douyin influencer vetting:** check a creator's verification, total likes received and post count, plus the numbers on the videos you list. Turn on **🧪 Add extra details** to also get the creator's follower and following counts.
- **Spot Douyin trends:** collect hashtags, topic tags and music from the videos you track and see which ones keep coming back.
- **Build a Douyin dataset:** turn a list of links into one tidy table for BI tools, spreadsheets or LLM pipelines.
- **Archive media:** save MP4 files, covers and slideshow images of posts you are allowed to keep.
- **Audit link lists:** find out which links are deleted, private or unavailable.

#### What can Douyin 抖音 Video Scraper - Metadata do?

- 🔗 **Reads many link formats:** video links, image post (note) links, page links with `modal_id`, `v.douyin.com` share links, the whole share text copied from the app, and bare numeric IDs, all mixed together.
- 📝 **Works as a Douyin extractor for videos and image posts:** each one comes back as one row with more than 50 fields and nested blocks.
- 📸 **Optional downloads:** it also works as a Douyin video downloader. Save the MP4, the cover image and every slide of an image post next to the data.
- ⚡ **Live results:** each row is saved the moment its video is finished, and duplicates are read only once.
- 📦 **Export Douyin data** to JSON, CSV, Excel, XML or HTML. You can also call the Actor via the API, schedule runs, monitor them and connect them to Make, Zapier, Google Sheets and more.
- 🛡️ **Handles blocking for you:** if Douyin refuses the connection, the Actor retries and switches to Apify Proxy automatically when your account can use it. See [what happens without Apify Proxy](#advanced-settings).

***

### Douyin video scraper: what data can it extract?

The Actor collects the public **Douyin metadata** of each video or image post, grouped so it's easy to read. In short, it is a Douyin video extractor: one row of Douyin video metadata per link. Field names below are the exact names in the dataset.

| | |
|---|---|
| 🔗 `id`, `url`, `shareUrl`, `inputUrl` | 📝 `text`, `caption`, `itemTitle`, `previewTitle`, `descLanguage` |
| 📅 `createTime`, `createDate` (Beijing time) | 📍 `region`, `city`, `cityCode`, `location` (tagged place) |
| 👤 `authorMeta`: name, IDs, handles, verified, bio, total likes received, post count, avatar | ⭐ `statistics`: `diggCount` (likes), `commentCount`, `shareCount`, `collectCount` (saves), `playCount`, `downloadCount`, `forwardCount`, `admireCount` |
| 🎵 `musicMeta`: sound ID, title, artist, original or not, length, audio link, owner | 🎥 `videoMeta`: width, height, quality, format, HDR, watermark flag, link expiry, play/download links, bit rates, covers |
| 🔗 `videoUrl`, `audioUrl`, `coverUrl`, `durationSeconds` | 🏷️ `hashtags`, `videoTags`, `mentions`, `chapters`, `series` |
| 📸 `type` (video or image), `images` (slides of an image post) | ✅ `permissions`, `interaction`: duet, stitch, download, share and comment switches, private / deleted state |
| 💲 `commerce`, `anchors`, `risk`, `share`, `xiguaCrossPost`, `aiMetadata` | 🚩 15 yes/no flags such as `isPinned`, `isAd`, `isStory`, `isShared` |

With **🧪 Add extra details** switched on, each row also gets an `extras` block: author follower and following counts, recommend and danmaku counts, secure item ID, AI-generated flag, download restriction note and suggested searches.

> **Note:** The Actor fills a field only when Douyin includes it in the public data for that video. Otherwise most fields are `null` and lists are empty. This also applies to the counts in `statistics`: `playCount` (views), `downloadCount`, `forwardCount` and `admireCount` are not guaranteed for every video, so run a quick test to see which counts you get. `musicMeta`, `series`, `location` and `risk` are `null` when the post has no sound, series, place or risk notice. For a **Douyin image post**, `type` is `"image"`, `url` uses `/note/`, `videoUrl` is `null` and the slides are listed in `images`.

#### What data can't it extract?

- Comments and replies
- All videos of a creator's profile, keyword or hashtag search results, or trending lists
- Transcripts or subtitles
- Audio files (you get the `audioUrl` link, but no MP3 is saved)
- Private, deleted or otherwise unavailable videos

***

### How to scrape Douyin video data

The Actor is built for an easy start, even if you've never extracted data from the web before.

1. [Create a free Apify account](https://console.apify.com/sign-up) using your email.
2. Open the [Apify Douyin scraper](https://apify.com/insights_data/douyin-video-scraper-metadata) page.
3. The **🔗 Douyin video links or IDs** field comes prefilled with one example link, so you can click **Start** right away. Or replace it with your own video links, a Douyin share link (in the app, tap **Share** and copy the link or the whole share text) or a Douyin video ID.
4. Click **Start** and wait for the run to finish. Rows appear in the **Output** tab while the run is still working.
5. Click **Export** in the **Output** tab and download your data in JSON, CSV, Excel, XML or HTML.

> ⚠️ Two defaults can make a first run look small. On the Free plan, a run saves at most 10 videos, and any extra links are skipped (and not charged). The cap counts saved videos only, so links that fail don't use it up. Videos are read roughly in list order, several at a time, so the saved ones come from the start of your list, but they are not always exactly the first 10. All download options start switched **off**, so you get data rows but no saved files until you turn them on.

***

### How much does it cost to scrape Douyin?

The Actor uses **pay-per-event** pricing. Your bill has three parts:

| Part | Price | When it is charged |
|---|---|---|
| 💲 Results | **$5.00 per 1,000 results** ($0.005 per video or image post) on the Free plan (lower on paid plans, see below) | For each video or image post row saved to the dataset |
| 🚀 Actor start | **$0.0002 per run** with the default settings\* | Once per run |
| ⚙️ Platform usage | Apify's normal usage rates for your plan | On top of the two event prices. See below |

| Apify plan | Price per result | Price per 1,000 results |
|---|---|---|
| Free | $0.005 | $5.00 |
| Starter | $0.0045 | $4.50 |
| Scale | $0.004 | $4.00 |
| Business and higher | $0.0035 | $3.50 |

Paid Apify plans get a lower result price. The plan discount applies to that price only. The start fee is the same on every plan, and platform usage is billed at your Apify plan's own rates.

\* The start fee is $0.00005 per GB of memory. The default memory is 4 GB, because the Actor opens Douyin in a browser, so the fee is 4 × $0.00005 = $0.0002. You don't need to change the memory setting.

- **Not charged as results:** failed-item rows (from **🚧 Keep failed items in the results**), links skipped because a cap or limit was reached, and saved files. Saved files still use storage, which counts as platform usage.
- **Lower result price on paid plans:** see the plan table above. The start fee is the same on every plan.

Rounded examples for the result and start charges at the Free plan price, before platform usage. On the Free plan, only the first row is a single run. See [Is scraping Douyin free?](#is-scraping-douyin-free)

| Videos saved | Results | Start fee | Event total |
|---|---|---|---|
| 10 | $0.05 | $0.0002 | ≈ $0.05 |
| 100 | $0.50 | $0.0002 | ≈ $0.50 |
| 1,000 | $5.00 | $0.0002 | ≈ $5.00 |

**What platform usage is made of:**

- **Compute:** the run's memory (4 GB by default) multiplied by how long the run takes.
- **Storage and data transfer:** these grow when you save MP4s, covers or slides, because the files are downloaded and stored. Data-only runs store just the rows.
- **Apify Proxy traffic:** this only applies when the Actor has to switch to Apify Proxy.

**How to estimate platform usage:** we have no measured figures to quote, so use your own test runs:

1. Run the Actor on 10 of your links with the download options off. Open the finished run and note the usage cost and how long the run took.
2. Run the same 10 links again with **📥 Save MP4 video files** on, and note the same two numbers.
3. Divide each usage cost by the number of videos saved to get the usage per video, with and without MP4s. Multiply by the number of videos you plan to scrape, and add the result charges and the start fee.

The difference between the two runs shows how much the MP4 downloads add. Long videos are big files, so they add more.

**Keep costs under control:** set a **maximum charge limit** when you start a run. When the limit is reached, the Actor stops cleanly and keeps everything saved so far. See the [pricing tab](https://apify.com/insights_data/douyin-video-scraper-metadata/pricing) for the current event list.

#### Is scraping Douyin free?

You can try it for free. The [Apify Free plan](https://apify.com/pricing) gives you $5 of credit every month, and that one credit covers the result charges and the platform usage together. Free plan runs are limited to **10 videos per run**. At $5.00 per 1,000 results, 1,000 videos would use up the whole $5 on result charges alone, before any platform usage, so the Free plan suits tests and small jobs. For larger jobs, and for more than 10 videos in one run, use a paid Apify plan.

***

### Douyin video scraper input

The only required field is **🔗 Douyin video links or IDs** (`urls`). Everything else is optional. Set the input in the Actor's form, or send it as JSON via the API.

#### Settings most people change

| Form field | JSON name | Default | What it does |
|---|---|---|---|
| 🔗 Douyin video links or IDs | `urls` | none (required) | One link or ID per line. Mixed formats are fine, and duplicates are skipped |
| 📥 Save MP4 video files | `shouldDownloadVideos` | off | Saves each video's Douyin MP4 file to storage and fills `videoFile`. Image posts have no MP4 |
| 🌄 Save cover images | `shouldDownloadCovers` | off | Saves the cover of every video and image post. Fills `coverFile` |
| 📸 Save slideshow images | `shouldDownloadSlideshowImages` | off | Saves every slide of a Douyin slideshow (image post). Fills `slideshowFiles`. Has no effect on normal videos |
| 🧪 Add extra details | `includeExtras` | off | Adds the `extras` block to every row |
| 🚧 Keep failed items in the results | `includeFailedItems` | off | Adds a short, free row for every link that could not be read |

Here's an example that reads one video and returns its data only, with no files saved:

```json
{
  "urls": [
    "https://www.douyin.com/video/7577614489533680959"
  ]
}
```

See the [input tab](https://apify.com/insights_data/douyin-video-scraper-metadata/input-schema) for the full description of every field.

#### Which Douyin links work?

You can paste any of these forms, one per line:

- ✅ `https://www.douyin.com/video/7577614489533680959` (video link)
- ✅ `https://www.douyin.com/note/<id>` (image post link)
- ✅ Any Douyin page link that contains `modal_id=<id>`
- ✅ A `v.douyin.com` share link, or the whole share text copied from the app
- ✅ An `iesdouyin.com/share/video/<id>/` link
- ✅ `7577614489533680959` (a bare numeric video ID)
- ❌ A creator profile link without `modal_id`. The Actor reads single videos and posts, not whole profiles.

> ⚠️ A link that contains no video is skipped and the log says so. Turn on **🚧 Keep failed items in the results** to see it in the dataset as well.

#### Advanced settings

| Form field | JSON name | Default | What it does |
|---|---|---|---|
| 📂 Storage name for saved files | `videoKvStoreName` | empty | Name of a key-value store for saved files (lowercase letters, digits and dashes). Empty means the run's default key-value store |
| 🚀 Parallel videos | `maxConcurrency` | 4 | How many videos are read at the same time (1 to 10). Lower it if you see many slow-downs |
| 🔁 Retries per request | `maxRetries` | 3 | How often a failed or blocked request is retried before the Actor gives up on that video (0 to 10) |
| 🌐 Proxy | `proxyConfiguration` | no proxy | The Actor starts without a proxy. When Douyin blocks it, it switches to Apify Proxy automatically and stays on it for the rest of the run. Proxy traffic counts as platform usage. If your account can't use Apify Proxy, the Actor stays on the direct connection. Videos it still can't read after the retries are marked as failed. In that case, if Douyin blocks the very first connection, every video in that run is marked as failed, so add your own proxy here |

***

### Douyin video scraper output

Results are stored in a dataset. You can browse it in the **Output** tab through 9 ready-made views: Overview, Content and flags, Author, Engagement, Video quality, Music, Tags, mentions and chapters, Permissions and commerce, and Saved files and images. The Engagement view is a quick table of **Douyin video statistics**. To download the data, click **Export** in the **Output** tab (the same export is in **Storage → Datasets**), pick the fields you need, and choose JSON, CSV, Excel, XML or HTML.

#### JSON example

This is an abridged sample row for the input example above, so it shows the Douyin video info for that link. It combines values from a real run of this video with the example values in the Actor's dataset schema (same video), so numbers such as likes will differ when you run it today. Long text is shortened with `…`, and most nested fields are left out to keep it readable. The full row has every field listed in the data table.

```json
{
  "id": "7577614489533680959",
  "url": "https://www.douyin.com/video/7577614489533680959",
  "durationSeconds": 1082.5,
  "type": "video",
  "text": "这个贵州五线小城，凭什么是中国“吃商”最高的城市？ 糟了，捅了贵州老吃家的窝了！ #抖音美食班当季新菜单 …",
  "itemTitle": "这个贵州五线小城，凭什么是中国“吃商”最高的城市？",
  "createTime": 1764320400,
  "createDate": "2025-11-28",
  "region": "CN",
  "authorMeta": { "id": "75736792009", "name": "盗月社食遇记", "customUsername": "daoyueshe", "verified": true },
  "videoMeta": { "width": 3840, "height": 2160, "ratio": "2160p", "format": "dash", "hasWatermark": true },
  "musicMeta": { "id": "7577614774507424547", "author": "盗月社食遇记", "isOriginal": true },
  "statistics": { "diggCount": 4064473, "commentCount": 163237, "shareCount": 5189298, "collectCount": 855171 },
  "hashtags": [{ "id": "7572059655971538944", "name": "抖音美食班当季新菜单" }],
  "videoTags": [{ "name": "美食", "level": 1 }],
  "videoFile": null,
  "coverFile": null,
  "slideshowFiles": null,
  "inputUrl": "https://www.douyin.com/video/7577614489533680959"
}
```

How to read it:

- `durationSeconds` is the length in seconds (about 18 minutes here).
- `createTime` is the posting time in Unix seconds, and `createDate` is the same moment as a Beijing-time date.
- `diggCount` is the like count and `collectCount` is the number of saves. The other counts, including `playCount`, are left out of this sample to keep it short.
- `isOriginal` is `true`, so Douyin marks this sound as original.
- `ratio` is the quality label of the video (2160p here).
- `videoFile`, `coverFile` and `slideshowFiles` are `null` because the download options were off in this input.

#### When optional fields are filled

- `videoFile`, `coverFile` and `slideshowFiles` are filled only when the matching download option is on and the file was saved. Each entry holds `kvStoreKey`, `kvStoreId`, `kvUrl`, `sizeBytes`, `mimeType` and `sourceUrl`. Otherwise these fields are `null`.
- `extras` appears only when **🧪 Add extra details** is on. When it is off, the field is missing from the row.
- Failed-item rows (only with **🚧 Keep failed items in the results**) contain just `id`, `inputUrl` and `error`. The `error` value starts with `unavailable:` (deleted, private or not found), `failed:` (could not be read) or `unresolved:` (no video found in the input). For `unresolved:` rows, `id` is `null`.

> ⚠️ Media links inside a row (`videoUrl`, `audioUrl`, `coverUrl` and the links in `videoMeta`) stop working after a few hours, and `videoMeta.cdnUrlExpiresAt` tells you when. Saved files don't expire this way.

#### Saved files and run summary

Saved files go to a key-value store with keys like `video-<id>.mp4`, `cover-<id>.jpg` and `slide-<id>-01.jpg`. The extension follows the file type.

**To get the files onto your computer:** open **Storage → Key-value stores** in Apify Console and click the store (the run's default store, or the one named in **📂 Storage name for saved files**). Then download a record, such as `video-<id>.mp4`, from the record list. Apify Console can also [download all records at once](https://docs.apify.com/platform/storage/key-value-store). You can also open the `kvUrl` link in a row's `videoFile`, `coverFile` or `slideshowFiles` entry.

> ⚠️ Per the [Apify storage docs](https://docs.apify.com/platform/storage/key-value-store), unnamed key-value stores (the run's default) expire after 7 days unless otherwise specified, and named stores are kept indefinitely. To keep your files, set **📂 Storage name for saved files**. The run's default key-value store also gets a `SUMMARY` record with the run counts: videos saved, videos billed, failed or unavailable, skipped, files saved, files failed, and duration.

***

### Tips and advanced usage

#### How many results can you scrape?

You get one row per unique video or image post you list. Paid plans have no per-run cap from the Actor, while the Free plan saves up to 10 videos per run. What you actually get depends on how many of your links are still public and on your maximum charge limit. Start with a quick test run of a few links.

#### How to get faster or cheaper results

- Leave the download options off unless you need the files. Data-only rows are faster and cheaper to collect.
- Paste many links into one run instead of starting one run per link. You pay the start fee once, and videos are read in parallel.
- If the log shows many slow-downs, lower **🚀 Parallel videos**.
- We don't quote run times. They depend on how many videos you list, the download options and how fast Douyin answers. Time a small test run and scale up from there.
- For **Douyin data analysis**, use the Engagement, Author and Music views and export only the columns you need.

#### Using it as a Douyin downloader

Turn on **📥 Save MP4 video files** and the Actor saves each video's MP4 to storage. The row's `videoFile` then holds the file's name in storage (`kvStoreKey`) and a link to the file (`kvUrl`). See [Saved files and run summary](#saved-files-and-run-summary) for how to download them. Image posts have no MP4, so use **📸 Save slideshow images** for those.

#### Known issues

- Very large files may be skipped when saving. The log names any file that was skipped.
- Rows are saved in the order the videos finish, which may differ from your input order. Use `inputUrl` to match them.
- Fields that Douyin doesn't send for a video stay `null`.

***

### Integrations and API

#### Can I use it as a Douyin video scraper API?

Yes. The [Apify API](https://docs.apify.com/api/v2) lets you start runs, schedule them and fetch results programmatically, so the Actor works as a ready-made Douyin scraper API. This is the Apify API, not an official Douyin API. Use the `apify-client` [NPM package](https://apify.com/insights_data/douyin-video-scraper-metadata/api/javascript) for Node.js or the `apify-client` [PyPI package](https://apify.com/insights_data/douyin-video-scraper-metadata/api/python) for Python. The [API tab](https://apify.com/insights_data/douyin-video-scraper-metadata/api) has ready-to-use code for this Douyin video API.

#### Douyin API Python example

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("insights_data/douyin-video-scraper-metadata").call(run_input={
    "urls": ["https://www.douyin.com/video/7577614489533680959"]
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["id"], item["statistics"]["diggCount"])
```

#### Can I integrate it with other apps?

Yes. Connect the Actor with almost any cloud service through [Apify integrations](https://apify.com/integrations): **Make, Zapier, Slack, Google Sheets, Google Drive, Airbyte, GitHub, LangChain** and more. For example, schedule a daily run on the links your team tracks and send the **Douyin engagement** numbers to a Google Sheet, so your team always has fresh Douyin data. Use [webhooks](https://docs.apify.com/integrations/webhooks) to trigger an action whenever a run finishes.

#### Can I use it with AI agents (MCP)?

Yes. Connect the Actor to Claude and other AI assistants through the Apify MCP server. Your agent can then call it whenever it needs Douyin video data. Open the [MCP tab](https://apify.com/insights_data/douyin-video-scraper-metadata/api/mcp) for setup steps.

***

### Other scrapers for Chinese and short-video platforms

These Actors from the same author cover data that this one doesn't: TikTok profiles and comments, and other Chinese platforms.

| | |
|---|---|
| 🎥 [TikTok Profile Scraper](https://apify.com/insights_data/tiktok-profile-scraper): videos, reposts, stories and playlists of any TikTok profile, with views, likes, comments, shares, music, hashtags and author stats | 💬 [TikTok Comments & Replies Scraper](https://apify.com/insights_data/tiktok-comments-replies-scraper): TikTok comments and replies with text, likes, reply counts, dates and commenter details |
| 📺 [Bilibili Scraper — Videos, Comments, Danmaku & Creator Uploads](https://apify.com/insights_data/bilibili-scraper-videos-comments-danmaku-creator-uploads): Bilibili videos, comments, danmaku, creator uploads and rankings | 📰 [Weibo Scraper — Posts, Comments, Profiles & Hot Search](https://apify.com/insights_data/weibo-scraper): Sina Weibo posts, comments, profiles, topics and hot search boards |

***

### FAQ

#### Is it legal to scrape Douyin?

Scraping publicly available data is generally legal, but you are responsible for how you use it. This Actor reads only public video pages, without logging in. Respect personal data rules (such as GDPR, or PIPL in China), copyright in any video you save, and Douyin's terms of service, and only collect personal data when you have a legitimate reason. This is not legal advice. If you are unsure, ask a lawyer.

#### How does the Douyin scraper work?

It works like a person opening each video in a browser, only faster. First it turns every input into a video ID, following share links where needed, and drops duplicates. Then it opens Douyin as a normal visitor would, reads the public details of several videos in parallel and saves each one as a row right away. If you turned on downloads, it also saves the files. It doesn't wander through profiles or search pages. It reads exactly the videos you list.

#### How to download Douyin video files?

You can download Douyin video files in bulk: paste the links, switch on **📥 Save MP4 video files** and start the run. Each MP4 lands in storage, and the row's `videoFile` entry gives its name and link. To download the files, open **Storage → Key-value stores**, click the store and download the records you need, or download them all at once. Image posts have no MP4. For those, switch on **📸 Save slideshow images**. For a Douyin cover download, switch on **🌄 Save cover images**.

#### How is it different from copying data by hand?

| Feature | Douyin 抖音 Video Scraper - Metadata | Copying from the app by hand |
|---|---|---|
| Many links in one go | ✅ Bulk input, any mix of formats | ❌ One video at a time |
| Structured fields (likes, saves, author, music, hashtags) | ✅ More than 50 fields per row | ❌ Only what you type out |
| Export to CSV / Excel / JSON | ✅ | ❌ |
| Saved MP4, covers and slides | ✅ Optional | ❌ Manual, one by one |
| Schedule and API access | ✅ | ❌ |

#### Why scrape Douyin video data?

- **Compare content:** see Douyin statistics such as likes, comments, shares and saves side by side for any set of posts.
- **Learn from sounds and tags:** collect Douyin hashtags, topic tags and Douyin music to see what works in a category.
- **Measure campaigns:** track the posts behind a campaign on a schedule.
- **Feed AI and BI:** structured text and numbers drop straight into dashboards or LLM workflows.

#### Why am I getting fewer results than expected?

1. **Free plan cap:** Free plan runs save at most 10 videos, and the log says when links were skipped.
2. **Blocking without Apify Proxy:** if Douyin blocks the connection and your account can't use Apify Proxy, videos that still can't be read after the retries are marked as failed. Add your own proxy in **🌐 Proxy**, or use an account with Apify Proxy access.
3. **Duplicates:** the same video entered twice is read once.
4. **Unavailable links:** deleted, private or unreadable videos are left out. Turn on **🚧 Keep failed items in the results** to see each one with its `error`.
5. **Profile links:** links to a profile without `modal_id` are skipped.
6. **Maximum charge limit:** the run stops cleanly when your limit is reached.

#### Do I need a Douyin account or cookies?

No. The Actor reads public data that any visitor can see, so you don't need a login, cookies or an API key from Douyin.

***

### Support and feedback

Found a bug or have a feature request? Please create an issue on the [Issues tab](https://apify.com/insights_data/douyin-video-scraper-metadata/issues/open).

Need a **custom solution**, more fields or a different Douyin dataset? Contact us at hello.insights.data@gmail.com.

Built and maintained by [insights_data](https://apify.com/insights_data).

# Actor input Schema

## `urls` (type: `array`):

One entry per line. Accepted: www.douyin.com/video/<id> or /note/<id> links, any Douyin page link with modal_id, v.douyin.com share links (or the whole share text copied from the app), www.iesdouyin.com/share/video/<id>/ links and bare numeric video IDs. Mixed formats are fine and duplicates are skipped. Free plan: up to 10 videos per run, with no monthly limit; paid plans have no limit.

## `shouldDownloadVideos` (type: `boolean`):

Download each video and store the MP4 in the key-value store. The row then has a videoFile entry with its storage key and link. Image posts have no MP4.

## `shouldDownloadCovers` (type: `boolean`):

Download each video's cover image and store it in the key-value store (coverFile).

## `shouldDownloadSlideshowImages` (type: `boolean`):

For image posts, download every slide and store it in the key-value store (slideshowFiles). Has no effect on normal videos.

## `videoKvStoreName` (type: `string`):

Optional name of a key-value store for the saved files (lowercase letters, digits and dashes). Leave empty to use this run's default key-value store.

## `includeExtras` (type: `boolean`):

Adds an extras block to every row: author follower and following counts, recommend and danmaku counts, secure item ID, AI-generated flag, download restriction note and suggested searches.

## `includeFailedItems` (type: `boolean`):

Also save a short row (id, inputUrl, error) for every link that was unavailable, deleted, private or could not be read. These rows are not billed.

## `maxConcurrency` (type: `integer`):

How many videos are read at the same time (1 to 10). Lower it if you see many slow-downs.

## `maxRetries` (type: `integer`):

How often a failed or blocked request is retried before giving up on that video (0 to 10). Also the number of fresh-IP tries on the last proxy step.

## `proxyConfiguration` (type: `object`):

Optional. By default the actor connects without a proxy. If Douyin refuses the connection it switches to datacenter proxies, then residential proxies, and stays on that step for the rest of the run.

## Actor input object example

```json
{
  "urls": [
    "https://www.douyin.com/video/7577614489533680959"
  ],
  "shouldDownloadVideos": false,
  "shouldDownloadCovers": false,
  "shouldDownloadSlideshowImages": false,
  "includeExtras": false,
  "includeFailedItems": false,
  "maxConcurrency": 4,
  "maxRetries": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

One line per video: cover, text, author and headline numbers.

## `content` (type: `string`):

Text, titles, timing, place and yes/no flags.

## `author` (type: `string`):

Name, handles, verification, totals and avatar of the poster.

## `engagement` (type: `string`):

Likes, comments, shares, saves and plays.

## `video` (type: `string`):

Media links, size, format and encoding details.

## `music` (type: `string`):

The sound used in each video.

## `tags` (type: `string`):

Hashtags, topic tags, mentions, chapters, series and place.

## `access` (type: `string`):

What viewers may do, plus ad, shopping and review flags.

## `files` (type: `string`):

Saved file entries and slideshow images; failed items when they are kept.

## `videoFiles` (type: `string`):

Videos saved to the key-value store (when MP4 saving is on).

## `coverFiles` (type: `string`):

Cover images saved to the key-value store (when cover saving is on).

## `slideshowFiles` (type: `string`):

Slide images saved to the key-value store (when slideshow saving is on).

## `summaryFile` (type: `string`):

SUMMARY file with the counts of this run.

# 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 = {
    "urls": [
        "https://www.douyin.com/video/7577614489533680959"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("insights_data/douyin-video-scraper-metadata").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 = {
    "urls": ["https://www.douyin.com/video/7577614489533680959"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("insights_data/douyin-video-scraper-metadata").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 '{
  "urls": [
    "https://www.douyin.com/video/7577614489533680959"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call insights_data/douyin-video-scraper-metadata --silent --output-dataset

```

## MCP server setup

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

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/vI8FC0lIBlSXPld32/builds/p7xCbfPLvaVtsq9wc/openapi.json