# WeChat Channels Video Search Scraper (`opspilot.cc/wechat-channels-video-search-scraper`) Actor

EN — Search WeChat 视频号 Channels videos by keyword with duration / sort / time filters. ZH — 视频号视频搜索,按时长/排序/时间筛选。Cursor auto-pagination, video-normalized output with exportId + duration + likeNum. 5 free runs/day.

- **URL**: https://apify.com/opspilot.cc/wechat-channels-video-search-scraper.md
- **Developed by:** [wang wei](https://apify.com/opspilot.cc) (community)
- **Categories:** Social media
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.10 / actor start

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## WeChat Channels Video Search Scraper

**EN — Find trending 视频号 Channels videos by keyword in 30 seconds.** Drop one keyword, filter by duration (short / medium / long), sort by latest or hottest, and pull up to 50 ranked videos with engagement metrics (10万+ like counts), publisher profile, shareable export IDs, and cover images. No login, no captcha, no headless browser.

**ZH — 视频号视频搜索 — 一键按关键词 + 时长筛选抓取。** 一个关键词,按时长(短视频/中视频/长视频)、排序(最新/最热)筛选,最多 50 条视频(5 页 × ~10),含点赞数(10万+)、发布者资料、可下载的 exportId、封面图。无登录、无验证码、无 headless 浏览器。

Built for **influencer discovery**, **trend monitoring**, and **competitor intelligence** on 视频号 (WeChat Channels) — China's fastest-growing short-video platform inside WeChat. Output exports as JSON / CSV / Excel — pipe directly into your CRM, BI tool, or another Apify Actor.

**5 free runs / day — no API key required.** Open on Apify Console, drop a keyword, get results in 30 seconds.

### What you can search

| Filter | Values | EN | 中文 |
|---|---|---|---|
| `duration` | `all` (default) / `short` / `medium` / `long` | all videos / <5 min / 5-20 min / 20+ min | 不限 / 短视频 / 中视频 / 长视频 |
| `sort` | `default` / `latest` / `hot` | relevance / publish time desc / like count desc | 相关性 / 最新 / 最热 |
| `publishTime` | `all` / `day` / `week` / `half_year` | all time / 24 h / 7 d / 6 mo | 不限 / 24小时内 / 7天内 / 半年内 |

Other inputs:

- `keyword` (1-100 chars, e.g. `美食`, `健身`, `跨境电商`)
- `maxPages`: 1-5 pages, default 3 (cost control)
- `cursor`: opaque token from a previous run's `SUMMARY.nextCursor` for resumable pagination
- `raw`: include the unprocessed upstream `data` envelope on each pushed item (off by default)

### Input

```json
{
  "keyword": "美食",
  "duration": "short",
  "sort": "latest",
  "publishTime": "all",
  "maxPages": 3,
  "cursor": "",
  "raw": "false"
}
```

### Output

Each pushed item is a normalized Channels video row keyed by `docId` (string — base64 may exceed JS Number safe range):

```json
{
  "keyword": "美食",
  "page": 1,
  "rank": 1,
  "businessType": "video",
  "businessTypeRaw": 7,
  "docId": "finderobjv0iGrW2Ju7cmIl5Q2m0E",
  "exportId": "export/UzFfAEDovIKb9q9zJ4...",
  "hashDocId": "17711004180000001",
  "feedNonceId": "1717...",
  "title": "家常菜快手菜...",
  "titleRaw": "...<em class=\"highlight\">美食</em>...",
  "coverUrl": "https://wx.qlogo.cn/...",
  "duration": "03:42",
  "pubTime": 1757365200,
  "dateLabel": "2小时前",
  "likeNum": "10万+",
  "source": {
    "name": "刘小妹正餐",
    "iconUrl": "https://wx.qlogo.cn/...",
    "verified": true
  },
  "collectedAt": "2026-09-09T00:00:00Z"
}
```

`exportId` outlives a search page — pass it to the upstream `fetch_video_detail` endpoint to download the actual video media. `likeNum` is kept as a string to preserve Chinese unit formatting like `10万+`.

The run also writes a `SUMMARY` to the Key-Value Store with `pushed / pagesFetched / nextCursor / hasMoreInSource / tier / runsToday / dailyLimit / startedAt / finishedAt` — use `nextCursor` on the next run for resumable pagination.

### Use cases

- **Influencer discovery (视频号) / KOL 调研**: filter by `duration=short` + `publishTime=week` to surface emerging Channels creators before they saturate.
- **Trend monitoring / 热点追踪**: run daily with the same keyword, diff `docId` sets between runs to spot new entrants.
- **Competitor intelligence / 竞品监控**: track competitor 视频号 accounts' video cadence and engagement metrics.
- **Short-video sourcing for cross-border e-commerce / 跨境电商短视频素材**: collect `exportId` for top-performing videos in your category, then download and repurpose.
- **Long-form content (视频号 > 5 min) market mapping / 长视频赛道调研**: filter by `duration=medium|long` to find Channels' longer creators, an under-mapped segment.

### Pagination

The Actor auto-paginates via the upstream `cursor` + `continue_flag` envelope. Set `maxPages` (1-5) to cap requests per run (5 pages ≈ 50 videos). To resume a previous run, copy `SUMMARY.nextCursor` from the previous run into `cursor` on the next run.

| `maxPages` | Items per run (avg) | Cost control / 成本控制 |
|---:|---|---|
| 1 | ~10 | smoke test / 冒烟测试 |
| 3 (default) | ~30 | sweet spot / 推荐值 |
| 5 | ~50 | hard cap (cost & quota safety) |

### Quick start

Open the [Actor on Apify Console](https://console.apify.com/), fill in `keyword` (e.g. `美食`), click **Start**. Results land in the Dataset tab in ~30 seconds.

Want to run from the CLI?

```bash
apify call wechat-channels-video-search-scraper -i '{"keyword": "美食", "duration": "short", "sort": "latest"}'
```

The upstream API key is wired into the Actor — no Secrets tab setup, no env vars to set. Apify free users get 5 runs / day.

### Sister Actor — WeChat universal search

For full WeChat ecosystem search (公众号 / 视频号 / 文章 / 账号) across 18 business\_type filters, see the sister Actor:

→ [WeChat Universal Search Scraper](https://console.apify.com/search?q=wechat-universal-search-scraper) — same keyword, broader vertical coverage without the duration filter.

### Tests

```bash
npm test
```

Runs 17 unit assertions (input validation, request body shape, video normalization) plus 6 integration scenarios (mock fetch drives the full `run()` flow against captured upstream fixtures).

```
✅ unit.js: 17 assertions passed.
✅ integration.js: 6 scenarios passed.
```

### Notes on upstream behavior

- **Channels video items always have the same shape / 视频号视频 shape 固定**: `docID` / `exportId` / `hashDocID` / `duration` / `image` / `jumpInfo` / `likeNum` / `pubTime` / `source` / `title`.
- **30-second hard timeout / 30 秒硬超时**: TikHub documents that the upstream takes up to 30 s. The Actor enforces this with `AbortController` + exponential backoff (3 retries: 500 ms / 1 s / 2 s).
- **Large integer IDs preserved as string / 大整数 ID 保 string**: `docID` is base64, `hashDocID` is a 19-digit number, `likeNum` includes Chinese units like `10万+`. All kept as strings to avoid JS Number precision loss.
- **`exportId` is the durable handle / exportId 是稳定句柄**: it outlives any single search page and can be passed to the upstream `fetch_video_detail` endpoint for actual media download.

### Changelog

See [CHANGELOG.md](./CHANGELOG.md).

### License

Apache-2.0

# Actor input Schema

## `keyword` (type: `string`):

WeChat Channels video keyword, 1-100 characters. Examples: 美食, 健身, 跨境电商.

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

Filter videos by length. Default `all` = no filter.

## `sort` (type: `string`):

Result ordering. Default = relevance.

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

Filter by publish time. Default = all time.

## `maxPages` (type: `integer`):

Cap on pages fetched per run (1-5). Each page = ~10 videos.

## `cursor` (type: `string`):

Opaque token from a previous run's SUMMARY.nextCursor (resumable pagination). Leave empty to start fresh.

## `raw` (type: `string`):

Add the unprocessed upstream data object as rawData on every pushed item. Default false keeps datasets small.

## Actor input object example

```json
{
  "keyword": "美食",
  "duration": "all",
  "sort": "default",
  "publishTime": "all",
  "maxPages": 3,
  "cursor": "",
  "raw": "false"
}
```

# Actor output Schema

## `dataset` (type: `string`):

One normalized dataset item per unique Channels video. Fields: docId, exportId, hashDocId, feedNonceId, title, coverUrl, duration (mm:ss), pubTime (unix), dateLabel, likeNum, source.name, source.iconUrl. exportId outlives a search page — pass to fetch\_video\_detail for media download.

## `summary` (type: `string`):

Run-level summary: keyword, duration, sort, publishTime, pagesFetched, requests, pushed, receivedFromSource, hasMoreInSource, nextCursor, startedAt, finishedAt, tier, runsToday, dailyLimit.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("opspilot.cc/wechat-channels-video-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("opspilot.cc/wechat-channels-video-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 '{}' |
apify call opspilot.cc/wechat-channels-video-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,opspilot.cc/wechat-channels-video-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/VAtqWhR0gxKlezuPU/builds/tGk4tDxrDIqeU0cYa/openapi.json