# Douyin Search Scraper (`happy_b/douyin-search-scraper`) Actor

Search public Douyin videos by keyword and export posts, engagement metrics, media, music, hashtags, and creator profiles across up to 55 typed fields. Filter by relevance, recency, and duration for research, monitoring, and content analysis.

- **URL**: https://apify.com/happy\_b/douyin-search-scraper.md
- **Developed by:** [Happy B](https://apify.com/happy_b) (community)
- **Categories:** Social media, Videos
- **Stats:** 1 total users, 0 monthly users, 94.4% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.49 / 1,000 search results

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What is Douyin Search Scraper?

Douyin Search Scraper is a **keyword video-search Actor for Douyin (抖音 / Chinese TikTok)**. Enter topics, products, brands, or phrases and receive structured public videos with engagement, media, music, hashtags, and creator details.

It is built for brands, agencies, researchers, publishers, and data teams that need automation-ready Douyin content discovery without supplying a login, cookies, a browser, or a proxy.

### Why use this Douyin search scraper?

- **Search up to 50 terms per run.** Every row keeps its matching keyword in `sourceQuery`.
- **Choose how results are ranked.** Search by relevance, most liked, or newest.
- **Filter by freshness and duration.** Focus on recent posts or videos within a useful length range.
- **Export up to 55 typed fields.** Collect exact engagement counts, media links, music, hashtags, stable post IDs, and embedded creator context.
- **Remove repeated results.** Each query returns unique post rows and preserves its one-based `resultPosition`.
- **Automate the output.** Export JSON, CSV, Excel, XML, HTML, or JSONL and connect schedules, webhooks, Make, Zapier, or the Apify API.
- **Control every run's spend.** The Actor respects the maximum charge selected for the run.

### How to search Douyin videos

1. Add one or more keywords such as `机器人`, `户外露营`, or a brand name.
2. Choose the maximum videos per keyword.
3. Select the result order, publication window, and video duration.
4. Run the Actor and open the **Search results** dataset.

#### Input example

```json
{
  "searchQueries": ["机器人", "户外露营"],
  "maxPostsPerQuery": 100,
  "sortType": "most_liked",
  "publishTime": "last_week",
  "duration": "under_1m"
}
```

Duplicate keywords are removed before searching. Chinese and Latin text are supported.

### What data can I extract?

Each dataset item is one unique public video matched by one search keyword.

| Field group | Included data |
|---|---|
| Search context | `sourceQuery`, `resultPosition`, `scrapeTimestamp` |
| Post identity | `awemeId`, `postUrl`, `description`, `createTimeIso`, `mediaTypeName` |
| Engagement | `playCount`, `likeCount`, `commentCount`, `shareCount`, `collectCount`, `downloadCount` |
| Media | `videoUrl`, `coverUrl`, `imageUrls`, `durationMs`, `width`, `height` |
| Music and topics | `musicId`, `musicTitle`, `musicAuthor`, `musicUrl`, `hashtags` |
| Creator identity | `profileUid`, `profileSecUid`, `profileShortId`, `profileUniqueId`, `profileNickname`, `profileUrl` |
| Creator audience | `profileFollowerCount`, `profileFollowingCount`, `profileAwemeCount`, `profileTotalFavorited`, `profileFavoritingCount` |
| Creator profile | Bio, avatar variants, verification, account flags, gender, region, location, language, live status, and published linked-account IDs |

Fields that Douyin does not publish for a result are omitted. Large IDs are stored as strings so spreadsheets and JavaScript do not round them. Counts are returned as reported integers rather than abbreviated labels such as `42.8K`.

Media links can be temporary. Download media you are entitled to retain soon after the run. Douyin may report zero when a counter is unavailable; the Actor preserves that value and does not estimate a replacement.

The example below is illustrative and does not represent a specific person or captured live row.

#### Output example

```json
{
  "sourceQuery": "机器人",
  "resultPosition": 1,
  "awemeId": "7530000000000000001",
  "description": "机器人应用演示",
  "createTimeIso": "2026-08-20T08:30:00.000Z",
  "postUrl": "https://www.douyin.com/video/7530000000000000001",
  "playCount": 128400,
  "likeCount": 9600,
  "commentCount": 318,
  "shareCount": 504,
  "collectCount": 1200,
  "mediaTypeName": "video",
  "videoUrl": "https://example.com/video.mp4",
  "coverUrl": "https://example.com/cover.jpg",
  "hashtags": ["机器人", "科技"],
  "profileUniqueId": "example_creator",
  "profileNickname": "示例创作者",
  "profileFollowerCount": 428000,
  "profileVerified": true,
  "profileUrl": "https://www.douyin.com/user/MS4wLjABAAAA...",
  "scrapeTimestamp": "2026-08-27T10:30:00.000Z"
}
```

### Input reference

| Parameter | Type | Default | Limits | Description |
|---|---|---:|---:|---|
| `searchQueries` | string\[] | required | 1–50 | Video-search keywords |
| `maxPostsPerQuery` | integer | `50` | 1–5,000 | Maximum unique rows for each keyword |
| `sortType` | string | `relevance` | — | `relevance`, `most_liked`, or `latest` |
| `publishTime` | string | `any` | — | Any time, last day, last week, or last six months |
| `duration` | string | `any` | — | Any length, under one minute, one to five minutes, or over five minutes |

### Reliable results and billing

Interrupted runs can continue without duplicating rows already delivered. Repeated matches are removed, charges track unique rows visible in the dataset, and incomplete work is reported with a clear sanitized error instead of questionable data.

### How much does Douyin search data cost?

You pay for each unique video row returned. You are not charged a result event for missing or repeated rows.

| Apify tier | Per result | Per 1,000 results |
|---|---:|---:|
| Free | $0.00549 | $5.49 |
| Bronze | $0.00549 | $5.49 |
| Silver | $0.00549 | $5.49 |
| Gold | $0.00549 | $5.49 |

An additional $0.001 run-start charge applies. Platinum and Diamond users receive the listed Gold price.

| Example on the Free tier | Estimated cost |
|---|---:|
| 50 results | $0.276 |
| 2 keywords × 100 results | $1.099 |
| 30 daily runs × 50 results | $8.265 |

Examples include the run-start charge. Actual output can be lower than the requested maximum when fewer matching public videos are available. The Actor respects the maximum total charge configured for the run.

### Common use cases

- Brand and competitor content research
- Product, category, and campaign monitoring
- High-engagement video discovery
- Editorial research and content ideation
- Creator discovery from successful posts
- Scheduled keyword snapshots
- Hashtag and music analysis
- Building public content datasets for compliant analysis

### Integrations

Use the Actor with Apify Schedules, Webhooks, API clients, Make, Zapier, Google Sheets, Slack, a warehouse, or any system that accepts JSON, CSV, Excel, XML, HTML, or JSONL exports.

### FAQ

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

No. The Actor does not ask you for login credentials or cookies.

#### Can I search in Chinese and English?

Yes. Chinese and Latin text are supported. Results depend on the public videos Douyin makes available for each keyword.

#### Why did I receive fewer rows than requested?

The requested maximum is a ceiling, not a guarantee. A narrow keyword, strict freshness or duration filter, repeated matches, removed posts, or current public availability can reduce the result count.

#### Can I schedule recurring searches?

Yes. Save the input as an Apify task, attach a schedule, and use a webhook or integration to send each completed dataset downstream.

### Related Douyin Actors

| Actor | Best for |
|---|---|
| [Douyin Creator Scraper](https://apify.com/happy_b/douyin-creator-scraper) | Discover public accounts by keyword and audience filters |
| [Douyin Profile Scraper](https://apify.com/happy_b/douyin-profile-scraper) | Resolve known profiles and optionally collect their public posts |
| [Douyin Trend Scraper](https://apify.com/happy_b/douyin-trend-scraper) | Export current hot/rising topics or keyword interest over time |

### Legal and responsible use

This Actor extracts publicly available data. You are responsible for your lawful basis, retention, profiling, and other downstream processing. Review Douyin's [User Service Agreement](https://www.douyin.com/agreements/?id=6773906068725565448), [Privacy Policy](https://www.douyin.com/privacy/), and all laws that apply to your use case, including personal-data and platform-access rules.

### Support

For a bug or feature request, [open an Apify issue](https://apify.com/happy_b/douyin-search-scraper/issues/open). Include the run ID, affected keyword, expected behavior, and input with sensitive values removed.

# Actor input Schema

## `searchQueries` (type: `array`):

Keywords, topics, brands, products, or phrases to search. Chinese and Latin text are supported.

## `maxPostsPerQuery` (type: `integer`):

Maximum number of separately charged video rows returned for each unique query.

## `sortType` (type: `string`):

Choose relevance, highest like count, or newest publication time.

## `publishTime` (type: `string`):

Limit results by publication time.

## `duration` (type: `string`):

Limit results by video length.

## Actor input object example

```json
{
  "searchQueries": [
    "机器人",
    "美食"
  ],
  "maxPostsPerQuery": 50,
  "sortType": "relevance",
  "publishTime": "any",
  "duration": "any"
}
```

# Actor output Schema

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

One dataset item per unique public video matched by a search query.

## `metadata` (type: `string`):

Completion state, result counts, applied filters, and sanitized errors.

# 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 = {
    "searchQueries": [
        "机器人",
        "美食"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("happy_b/douyin-search-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 = { "searchQueries": [
        "机器人",
        "美食",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("happy_b/douyin-search-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 '{
  "searchQueries": [
    "机器人",
    "美食"
  ]
}' |
apify call happy_b/douyin-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,happy_b/douyin-search-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/7sDrz1Y9PV4LQzMyd/builds/Ic0uLx2ZE0T8ZeugX/openapi.json