# Toutiao Scraper (`automation-lab/toutiao-articles-videos-scraper`) Actor

Extract public Toutiao article and video search results by keyword for recurring Chinese media, brand, and topic monitoring.

- **URL**: https://apify.com/automation-lab/toutiao-articles-videos-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** News, Videos, Social media
- **Stats:** 2 total users, 1 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/platform/actors/running/actors-in-store#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

## Toutiao Scraper

Collect public article and video search results from **Toutiao (今日头条)** by keyword. The Actor turns Toutiao's search pages into structured records for Chinese media monitoring, topic research, brand tracking, and data pipelines.

Use Chinese-language keywords for the strongest coverage. Choose article results, video results, or both, and set a hard output limit that is also the maximum number of charged items.

### What does Toutiao Scraper do?

The Actor searches Toutiao's public search surface and extracts the structured result data embedded in each response. It does not require a Toutiao login, a Chinese phone number, or an unofficial API key.

It supports:

- one to 20 keywords per run;
- article-only, video-only, or combined searches;
- a global result limit from 1 to 200;
- result deduplication by source ID or URL;
- normalized publication times and engagement counts;
- JSON, CSV, Excel, XML, RSS, and HTML exports through Apify datasets;
- scheduled runs for repeat monitoring.

### Who is this Toutiao data for?

**Media intelligence teams** can watch how topics and organizations appear in Chinese news search.

**Brand and communications teams** can schedule recurring queries for company, executive, campaign, or product names.

**Researchers and journalists** can collect result headlines, snippets, publishers, and links for reproducible analysis.

**Data engineers** can send normalized rows to a warehouse, spreadsheet, webhook, or enrichment pipeline.

**AI teams** can use public result metadata as discovery input for translation, classification, clustering, and retrieval workflows.

### Why use this Actor?

- **Keyword workflow:** provide search terms rather than collecting a known profile or URL.
- **Articles and videos:** exercise Toutiao's separate information and video search tabs.
- **Transparent provenance:** every row keeps the query, destination URL, host, and collection time.
- **No false completeness:** unavailable source fields are returned as `null`; they are never invented.
- **Cost control:** the output limit caps the number of saved records.
- **HTTP-first design:** no browser or automatic residential proxy fallback is used.

### What data can you extract?

| Field | Meaning |
| --- | --- |
| `query` | Keyword that produced the result |
| `contentType` | `article` or `video` search tab |
| `rank` | Position among parsed results for that query and tab |
| `contentId` | Stable result/content ID when Toutiao exposes one |
| `title` | Article headline or video title |
| `url` | Destination URL returned by Toutiao search |
| `host` | Destination hostname |
| `source` | Publisher, author, or source site when exposed |
| `summary` | Search-result abstract or snippet |
| `publishedAt` | ISO 8601 publication time when exposed |
| `imageUrl` | Primary image or video thumbnail when exposed |
| `durationSeconds` | Video duration when exposed |
| `commentCount` | Comment count when exposed |
| `readCount` | Article reads or video plays when exposed |
| `likeCount` | Like count when exposed |
| `hasVideo` | Whether the result is or contains video |
| `scrapedAt` | UTC collection timestamp |

All source-dependent fields are nullable because Toutiao does not expose every field for every result.

### How to search Toutiao in 3 steps

1. Open the Actor input page in Apify Console.
2. Add one or more keywords, select a content type, and choose `maxItems`.
3. Start the run and open the Dataset tab to inspect or export results.

A small article search:

```json
{
  "keywords": ["人工智能"],
  "contentType": "articles",
  "maxItems": 10
}
```

A combined monitoring run:

```json
{
  "keywords": ["人工智能", "新能源汽车"],
  "contentType": "both",
  "maxItems": 30
}
```

### Input parameters

| Parameter | Type | Default | Rules | Description |
| --- | --- | --- | --- | --- |
| `keywords` | string array | `['人工智能']` | 1–20 non-empty values | Terms searched independently |
| `contentType` | string | `both` | `articles`, `videos`, or `both` | Toutiao search tabs to collect |
| `maxItems` | integer | `20` | 1–200 | Global unique-result and charge cap |

Duplicate keywords are removed. An empty keyword list, unsupported content type, or out-of-range limit fails the run with a clear error.

### Example output

This shortened record reflects the current article-search output shape:

```json
{
  "query": "人工智能",
  "contentType": "article",
  "rank": 1,
  "contentId": "7672133299032097320",
  "title": "坚定不移探索通用人工智能发展的中国道路",
  "url": "https://www.toutiao.com/group/7672133299032097320/",
  "host": "www.toutiao.com",
  "source": "光明网",
  "summary": "2023年4月28日，习近平总书记主持中共中央政治局会议…",
  "publishedAt": "2026-08-09T20:35:50.000Z",
  "imageUrl": null,
  "durationSeconds": null,
  "commentCount": 0,
  "readCount": 52,
  "likeCount": 2,
  "hasVideo": false,
  "scrapedAt": "2026-08-12T06:58:32.540Z"
}
```

Counts and ranking are snapshots of what the public search response exposed at collection time.

### How much does it cost to search Toutiao articles and videos?

This is a pay-per-event Actor. Each run has one `start` event, and each successfully saved dataset row has one `item` event. Failed, malformed, duplicate, or rejected rows are not charged as items.

Current BRONZE pricing:

- start fee: **$0.005 per run**;
- result fee: **$0.0124 per saved item**.

At BRONZE rates, a 10-result run costs about **$0.129**, a 50-result run about **$0.625**, and a 100-result run about **$1.245**. Apify plan tiers may apply lower per-item rates. Compute or platform usage can appear separately according to your Apify plan.

The Actor stops as soon as `maxItems` records have been saved, so the input is also a simple spending control.

### Monitoring and integration workflows

#### Scheduled media monitoring

Create an Apify Schedule with a stable keyword list. Store each run's dataset ID and compare `contentId`, `url`, or title across runs to identify newly surfaced results.

#### Spreadsheet export

Open a completed dataset, select CSV or Excel, and export the overview fields. Use `query` and `contentType` as grouping columns.

#### Webhooks and data warehouses

Attach a run-succeeded webhook, fetch dataset items from the API, then load them into BigQuery, Snowflake, PostgreSQL, Supabase, or another system.

#### Translation and classification

Send `title` and `summary` to your approved translation or NLP service. Keep `url`, `source`, and `scrapedAt` alongside derived labels for traceability.

### Run the Actor with the Apify API

Replace `YOUR_TOKEN` with an Apify API token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~toutiao-articles-videos-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["人工智能"],"contentType":"articles","maxItems":10}'
```

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/toutiao-articles-videos-scraper').call({
  keywords: ['人工智能'],
  contentType: 'both',
  maxItems: 20,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_TOKEN')
run = client.actor('automation-lab/toutiao-articles-videos-scraper').call(run_input={
    'keywords': ['新能源汽车'],
    'contentType': 'videos',
    'maxItems': 10,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use Toutiao Scraper through MCP

Add the Apify MCP server in Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/toutiao-articles-videos-scraper"
```

#### Claude Desktop, Cursor, and VS Code

Claude Desktop, Cursor, and VS Code clients can use this MCP server configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/toutiao-articles-videos-scraper"
    }
  }
}
```

Example prompts:

- “Search Toutiao articles for 人工智能 and return the first 10 results.”
- “Collect article and video results for 新能源汽车 and summarize the publishers.”
- “Run my two Chinese brand keywords and save no more than 30 records.”

### Tips for useful results

- Prefer specific Chinese terms over broad English terms.
- Put close variants in separate keyword entries rather than combining them into one long query.
- Start with 10–20 items while refining a monitoring query.
- Use `articles` when publisher and publication metadata matter most.
- Use `videos` to inspect Toutiao's federated video-search result set.
- Preserve the returned host: a video result may point to a third-party destination surfaced by Toutiao.

### Limits and failure behavior

Toutiao controls search ranking, available result count, and exposed metadata. One current server-rendered result page is collected for each keyword and selected tab; requesting a larger `maxItems` does not manufacture more results.

The video tab is federated. It can return destinations on Bilibili or other sites in addition to Toutiao properties. `host` makes this explicit.

The Actor retries transient network, HTTP 429, and server failures with bounded backoff. If Toutiao returns a challenge or an unrecognized page instead of structured search cards, the run fails rather than reporting a misleading empty success.

No automatic proxy fallback is enabled. This keeps costs predictable, but access can vary if Toutiao changes geography or delivery rules.

### Responsible use and legality

This Actor extracts publicly returned search-result metadata. You are responsible for ensuring that your use complies with Toutiao's terms, applicable copyright rules, privacy laws, database rights, and your organization's policies.

Do not use the Actor to collect sensitive personal data, bypass access controls, republish protected article bodies, or make automated decisions about individuals. Minimize retained data, honor deletion obligations, and preserve source attribution where required.

### Troubleshooting

#### Why did I receive fewer rows than `maxItems`?

`maxItems` is a ceiling, not a promise. Toutiao may expose fewer valid cards for a keyword, and duplicates are removed. Try another specific Chinese keyword or add related keyword variants.

#### Why do video URLs point outside toutiao.com?

Toutiao's video search is federated and can surface third-party video destinations. Use `host` to filter destinations downstream.

#### Why did the run fail with “no search result data”?

Toutiao returned an unexpected or challenged page. Check Apify's status page, wait before retrying, and review the run log. Repeating the same request rapidly is unlikely to help.

#### Can I download article bodies or video files?

No. This Actor returns search-result metadata and destination links. It does not download media or extract full article bodies.

#### Can I search more than 20 keywords?

Split larger lists into multiple runs or Tasks. The per-run cap keeps requests bounded and makes schedules easier to audit.

### FAQ

#### Does this require a Toutiao account?

No. It uses a public server-rendered search surface.

#### Does it support English keywords?

Yes, but Toutiao is a Chinese-language product and Chinese terms generally produce more relevant results.

#### Are article and video records charged differently?

No. Both are saved under the same `item` event and have no separate content-type charge.

#### Does the Actor use residential proxies?

No. The implementation is direct HTTP and has no hidden proxy fallback.

#### Are results deterministic?

The extraction is deterministic for a given response, but Toutiao ranking and inventory change over time.

### Related Automation Lab Actors

- [Google News Scraper](https://apify.com/automation-lab/google-news-scraper) for broader international news discovery.
- [WeChat Official Account Articles Scraper](https://apify.com/automation-lab/wechat-official-account-articles-scraper) for another Chinese publishing workflow.
- [Youku Video Search Scraper](https://apify.com/automation-lab/youku-video-search-scraper) for video-specific discovery on Youku.

Choose this Actor when the required source is Toutiao's keyword search and the desired output is public result metadata.

# Actor input Schema

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

One to 20 search terms. Each term is searched independently; Chinese-language terms usually return the strongest results.

## `contentType` (type: `string`):

Return article results, video results, or both search tabs.

## `maxItems` (type: `integer`):

Maximum number of unique records returned and charged across all keywords and content types.

## Actor input object example

```json
{
  "keywords": [
    "人工智能"
  ],
  "contentType": "both",
  "maxItems": 20
}
```

# Actor output Schema

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

Default dataset containing normalized article and video search records.

# 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 = {
    "keywords": [
        "人工智能"
    ],
    "contentType": "both",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/toutiao-articles-videos-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 = {
    "keywords": ["人工智能"],
    "contentType": "both",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/toutiao-articles-videos-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 '{
  "keywords": [
    "人工智能"
  ],
  "contentType": "both",
  "maxItems": 20
}' |
apify call automation-lab/toutiao-articles-videos-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/toutiao-articles-videos-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/3mGrfeTFauscizQVf/builds/CceiEeg7rzubM9rIo/openapi.json