# Youku Videos Scraper (`automation-lab/youku-video-records-scraper`) Actor

Search public Youku videos and series by keyword or search URL. Export ranked IDs, titles, URLs, creators, durations, publish timing, episodes, ratings, and availability metadata.

- **URL**: https://apify.com/automation-lab/youku-video-records-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.40 / 1,000 item extracteds

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

## Youku Videos Scraper

Search public **Youku videos** and series by keyword, then export clean records for Chinese-video research, content discovery, and recurring monitoring.

The Actor accepts search keywords or saved Youku search URLs. It returns ranked video and series records with stable IDs, titles, URLs, creators, durations, publish timing, episode counts, ratings, availability labels, and other metadata when Youku exposes it.

### What can Youku Videos Scraper do?

- Search Youku with one or several Chinese-language keywords.
- Process public `so.youku.com` and `search.youku.com` search URLs.
- Export video IDs, titles, URLs, creators, durations, and relative publish timing.
- Export series IDs, year, category, country, episode count, rating, cast, director, and availability when visible.
- Preserve each source query and result rank for comparisons between runs.
- Paginate with a strict per-query limit and deduplicate records by stable Youku ID.
- Produce JSON, CSV, Excel, XML, RSS, or another format supported by Apify datasets.

This Actor extracts metadata only. It does not download or stream copyrighted video files.

### Who is this Youku scraper for?

**Media researchers** can compare which dramas, movies, or creator videos appear for recurring topics.

**Brand and social-listening teams** can schedule keyword searches and track new IDs or ranking changes in downstream tools.

**Content strategists** can study visible titles, creators, durations, release timing, and series availability.

**Data engineers** can feed normalized Youku search records into a warehouse, spreadsheet, dashboard, or monitoring pipeline.

### Why use this Actor?

Youku's normal search pages can present browser challenges to automated cloud traffic. This Actor uses Youku's anonymous structured search response instead of downloading pages, scripts, images, or video media.

That approach keeps runs lightweight while retaining useful public search metadata. It also validates upstream response shape instead of silently returning an empty dataset when Youku changes or blocks the route.

No Youku login, cookies, account, or external API key are required for the supported search workflow.

### What Youku data can I extract?

| Field | Meaning |
| --- | --- |
| `recordType` | `video` or `series` |
| `recordId` | Stable source ID used for deduplication |
| `videoId` | Youku video ID when the row is a video |
| `showId` | Youku show/series ID when available |
| `title` | Public video or series title |
| `url` | Canonical/playable Youku URL when available |
| `creatorName` | Visible video creator/uploader name |
| `duration` | Visible video duration such as `03:20` |
| `durationSeconds` | Parsed duration in seconds |
| `publishTiming` | Relative public timing such as `3年前` |
| `thumbnailUrl` | Public thumbnail URL |
| `year`, `category`, `country` | Series metadata parsed from the visible feature label |
| `episodeCount` | Public total episode count |
| `updateStatus` | Visible release/update label |
| `rating` | Visible series reputation/rating value |
| `director`, `cast` | Public series credits when present |
| `availability` | Public playback or availability label |
| `query`, `rank` | Search term and position within the exported result set |
| `searchUrl` | Reproducible public search URL |
| `scrapedAt` | ISO timestamp for monitoring and comparisons |

Not every source row contains every optional field. Videos and series expose different metadata, and Youku can omit fields that are not visible for a particular result.

### How to scrape Youku videos

1. Open the Actor on Apify Console.
2. Add one or more keywords under **Search keywords**, or paste Youku search URLs.
3. Set **Maximum records per query**. Start with 10–25 for a quick test.
4. Keep the default retry setting unless you are diagnosing a temporary upstream issue.
5. Click **Start**.
6. Open the Dataset tab and export the records in your preferred format.

A useful first input is:

```json
{
  "queries": ["琅琊榜"],
  "maxResultsPerQuery": 20,
  "maxRetries": 2
}
```

### Input parameters

#### `queries`

An array of search terms. Chinese-language terms generally produce the most relevant Youku results.

```json
["国产电影", "悬疑剧", "纪录片"]
```

#### `searchUrls`

A list of public Youku search URLs. Both request-list objects and plain URL strings are accepted through the API.

```json
[
  { "url": "https://so.youku.com/search_video/q_%E7%94%B5%E5%BD%B1" }
]
```

The URL must use `so.youku.com` or `search.youku.com` and contain a keyword in its `q_...` path or `keyword` query parameter.

#### `maxResultsPerQuery`

Maximum unique video and series records saved for each query. Allowed range: 1–200. The default is 20.

A source can naturally expose fewer records than the requested limit. The limit is a ceiling, not a promise of volume.

#### `maxRetries`

Number of bounded retries for transient network or upstream errors. Allowed range: 0–4. The default is 2.

Malformed inputs and recognizable permanent response errors are not retried indefinitely.

### Output example

A real video row has this shape:

```json
{
  "recordType": "video",
  "recordId": "XMzYwNTk1NTkwMA==",
  "videoId": "XMzYwNTk1NTkwMA==",
  "title": "刘涛曝演《琅琊榜》中的霓凰是为了胡歌, 谈起胡歌给出超高评价",
  "url": "https://v.youku.com/v_show/id_XMzYwNTk1NTkwMA==.html",
  "query": "琅琊榜",
  "rank": 1,
  "creatorName": "墨上之殇",
  "duration": "03:20",
  "durationSeconds": 200,
  "publishTiming": "8年前",
  "thumbnailUrl": "https://vthumb.ykimg.com/054101015AF99A818B3C46A34565754A",
  "isAvailableOnYouku": true,
  "searchUrl": "https://so.youku.com/search_video/q_%E7%90%85%E7%90%8A%E6%A6%9C",
  "scrapedAt": "2026-08-16T20:08:15.559Z"
}
```

The default dataset contains both `video` and `series` records. Filter on `recordType` when a downstream workflow needs only one entity type.

### How much does it cost to scrape Youku videos?

The Actor uses pay-per-event pricing:

- one `start` event per run;
- one `item` event for each valid dataset record produced;
- no item charge for rejected, duplicate, empty, or failed rows.

Current example rates are a **$0.005 start fee** and **$0.004 per item on the BRONZE tier**. Tier prices decrease for higher Apify plans.

At BRONZE rates, calculate the Actor charge as the $0.005 start fee plus the number of useful records multiplied by the $0.004 item rate. For example, a 10-record run uses one start event and 10 item events; a 100-record run uses one start event and 100 item events.

These examples describe Actor event charges. Your Apify plan can also apply normal platform usage rules. Check the pricing panel for the active tier applicable to your account.

### Search quality and ranking

The Actor preserves Youku's returned ordering after excluding cross-platform-only series. The `rank` field is the rank among records saved for that query, not a claim about universal popularity.

Youku search can contain:

- individual creator videos;
- full series or programs;
- episode references attached to a series;
- cross-platform catalog entries.

The Actor emits individual Youku videos and series available on Youku. It does not present third-party-only catalog entries as Youku records.

### Pagination, limits, and deduplication

Pagination uses Youku's public `pg` parameter. Results are deduplicated independently for each query using `recordType` plus source ID.

The Actor stops when it reaches the requested limit, the upstream response reports the end, or no further pages are available.

Duplicate queries are processed once. Up to 20 unique combined keywords and search URLs can be used in a run.

### Monitoring new or changed Youku records

For recurring research:

1. Save a Task with the same keywords and limits.
2. Add an Apify schedule, such as daily or weekly.
3. Export each run's dataset to your warehouse or webhook.
4. Compare `recordType` + `recordId` to detect new records.
5. Compare `rank`, `episodeCount`, `updateStatus`, `availability`, and `scrapedAt` to detect visible changes.

The Actor does not store historical snapshots across runs itself. Apify datasets and your downstream system provide the history.

### Export Youku data to spreadsheets and pipelines

Dataset records can be downloaded directly as CSV or Excel. For automation, connect the completed run to:

- Google Sheets;
- Make;
- Zapier;
- webhooks;
- a database or data warehouse;
- Python, JavaScript, or another Apify API client.

Use `query`, `recordId`, and `scrapedAt` as practical keys for recurring snapshots.

### Run 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~youku-video-records-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["纪录片"],"maxResultsPerQuery":25}'
```

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/youku-video-records-scraper').call({
  queries: ['纪录片'],
  maxResultsPerQuery: 25,
});
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/youku-video-records-scraper").call(
    run_input={"queries": ["纪录片"], "maxResultsPerQuery": 25}
)
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use Youku Videos Scraper with MCP

Add the Actor to Claude Code through Apify MCP:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/youku-video-records-scraper"
```

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

Use this equivalent MCP configuration in Claude Desktop, Cursor, or VS Code:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/youku-video-records-scraper"
    }
  }
}
```

Example prompts:

- “Search Youku for 悬疑剧 and return 25 video and series records.”
- “Run my Youku movie search URL and summarize titles, years, and episode counts.”
- “Compare stable IDs and ranks from the latest scheduled Youku dataset with yesterday's dataset.”

### Reliability and failure behavior

The Actor validates HTTP status, JSON content type, and recognizable response fields. If Youku returns a challenge page or unknown payload instead of structured search data, the run fails rather than reporting a misleading valid empty result.

Transient failures use bounded exponential backoff. A recognized successful search with no matching records completes with an empty dataset.

If a run fails:

- verify that each search URL contains a real keyword;
- try one query with a limit of 10;
- inspect logs for an upstream response-shape or network message;
- retry later if Youku is temporarily unavailable.

No proxy setting is exposed because the supported direct structured route works anonymously and avoids unmeasured proxy cost.

### Limitations

- Search metadata is limited to fields publicly returned by Youku at run time.
- Relative publish timing such as `3年前` is preserved as shown; it is not converted to an invented exact date.
- Some series have no playable URL in the search result, although their public show ID remains available.
- Ratings, cast, director, creator, or availability can be absent on individual records.
- The Actor does not log in, bypass access controls, download media, scrape comments, or promise complete historical coverage.
- Youku can change its anonymous response and result ordering.

### Legality and responsible use

Use this Actor only for public information that you are entitled to collect. Follow applicable laws, Youku's terms, copyright rules, privacy requirements, and your organization's data-retention policies.

Do not use public creator metadata for harassment, unlawful profiling, or attempts to identify private individuals. Avoid republishing copyrighted media or personal information without a valid legal basis.

### FAQ

#### Does this Actor require a Youku account?

No. The supported keyword-search workflow uses public anonymous search metadata.

#### Can it download Youku videos?

No. It exports metadata and source URLs only.

#### Can I search Youku dramas and movies?

Yes. Use real terms such as `悬疑剧`, `国产电影`, or a specific title. Result composition depends on Youku's current search response.

#### Why did I receive fewer records than my limit?

The limit is a maximum. Youku may expose fewer unique, Youku-available records for a query, and the Actor excludes duplicate or cross-platform-only series.

#### Why are some fields missing?

Video and series rows expose different fields. Optional metadata is emitted only when it is visible in Youku's response.

#### What happens when a query has no results?

A recognized successful response with no useful Youku records completes normally with an empty dataset for that query.

### Related Automation Lab Actors

- [Toutiao Articles and Videos Scraper](https://apify.com/automation-lab/toutiao-articles-videos-scraper) for public Chinese news and video search records.
- [TikTok Video Records Scraper](https://apify.com/automation-lab/tiktok-video-records-scraper) for public TikTok video URL metadata.
- [VK Video Search Scraper](https://apify.com/automation-lab/vk-video-search-scraper) for public VKVideo keyword discovery.

Choose this Actor when Youku search and series availability are the required source-specific workflow.

# Actor input Schema

## `queries` (type: `array`):

Keywords to search on Youku. Chinese-language queries usually produce the most relevant results.

## `searchUrls` (type: `array`):

Public so.youku.com or search.youku.com search URLs containing a q path or keyword parameter.

## `maxResultsPerQuery` (type: `integer`):

Stops each query after this many unique Youku video and series records.

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

Retries transient network or upstream failures with bounded backoff.

## Actor input object example

```json
{
  "queries": [
    "琅琊榜"
  ],
  "searchUrls": [
    {
      "url": "https://so.youku.com/search_video/q_%E7%94%B5%E5%BD%B1"
    }
  ],
  "maxResultsPerQuery": 20,
  "maxRetries": 2
}
```

# Actor output Schema

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

Open the default dataset in the overview table view.

# 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 = {
    "queries": [
        "琅琊榜"
    ],
    "searchUrls": [
        {
            "url": "https://so.youku.com/search_video/q_%E7%94%B5%E5%BD%B1"
        }
    ],
    "maxResultsPerQuery": 20,
    "maxRetries": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/youku-video-records-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 = {
    "queries": ["琅琊榜"],
    "searchUrls": [{ "url": "https://so.youku.com/search_video/q_%E7%94%B5%E5%BD%B1" }],
    "maxResultsPerQuery": 20,
    "maxRetries": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/youku-video-records-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 '{
  "queries": [
    "琅琊榜"
  ],
  "searchUrls": [
    {
      "url": "https://so.youku.com/search_video/q_%E7%94%B5%E5%BD%B1"
    }
  ],
  "maxResultsPerQuery": 20,
  "maxRetries": 2
}' |
apify call automation-lab/youku-video-records-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/youku-video-records-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/jEdsDosD29Nwko1hO/builds/HVsqo7MVYLZprr0zo/openapi.json