# YouTube Viral Video & Competitor Analyzer (`scravion/youtube-data-scraper-pro`) Actor

Find breakout YouTube videos, compare them against each channel’s normal performance, and export competitor insights, Shorts, views, trends, and public analytics.

- **URL**: https://apify.com/scravion/youtube-data-scraper-pro.md
- **Developed by:** [scravion](https://apify.com/scravion) (community)
- **Stats:** 2 total users, 1 monthly users, 84.6% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## 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

## YouTube Viral Video & Competitor Analyzer

### Find breakout videos before everyone else notices them

Stop judging YouTube videos by views alone.

**YouTube Viral Video & Competitor Analyzer** compares videos and Shorts with each channel's own recent performance, helping you discover content that is significantly outperforming that creator's normal results.

Enter a YouTube channel, handle, Shorts page, video, playlist, or search query and get structured competitor insights in seconds.

***

### 🔥 Find true breakout content

A video with 100,000 views can be average for a large channel but extraordinary for a smaller one.

#### Channel View Multiplier

`Video views ÷ recent channel median views`

Example:

**31.75x**

means the video received about **31.75 times the channel's recent median views**.

This helps you spot real outliers instead of simply sorting by total views.

***

### 🚀 What you get

- Breakout videos and Shorts
- Channel View Multiplier
- Channel Average View Multiplier
- Viral Score
- Views per day
- Recent channel benchmarks
- Publish dates
- Likes and public engagement data
- Channel information
- Shorts detection
- Search and trending results
- Structured public YouTube metadata

***

### 🎯 Built for

**YouTube creators** — Find video ideas already outperforming competitors.

**Agencies** — Research niches and identify winning content formats.

**Marketers** — Track competitors and discover fast-growing topics.

**Researchers** — Export structured YouTube data for deeper analysis.

**Automation builders** — Connect results to spreadsheets, databases, APIs, n8n, Make, and dashboards.

***

### ⚡ Quick start

1. Enter a competitor channel:

`https://www.youtube.com/@YourCompetitor`

2. Choose your maximum results.
3. Run the Actor.
4. Open **Viral / breakout finder**.

For the strongest outliers use:

**Rank results by → Channel outlier multiplier: high to low**

***

### 📊 Example

Recent channel median:

**31,500 views**

Breakout Short:

**1,000,000 views**

Result:

**Channel View Multiplier: 31.75x**

You instantly know the video massively outperformed the channel's normal performance.

***

### 🔍 Supported sources

- YouTube channels
- @handles
- Shorts pages
- Individual videos
- YouTube Shorts
- Playlists
- Search keywords
- Search URLs
- Public trending content

***

### 📈 Viral / Breakout Finder

| Metric | Meaning |
|---|---|
| Channel View Multiplier | Performance vs recent channel median |
| Channel Average View Multiplier | Performance vs recent channel average |
| Viral Score | Derived breakout indicator |
| Views Per Day | Current viewing velocity |
| Median Recent Views | Recent channel baseline |
| Average Recent Views | Alternative baseline |
| Is Short | Whether the result is a Short |

***

### 💾 Export results

Export to **JSON, CSV, Excel, XML and RSS**. Use the results in Google Sheets, Excel, databases, dashboards, reporting systems, or your own applications.

***

### 🔁 Monitor competitors automatically

Use Apify schedules to repeatedly analyze competitor channels and discover new breakout videos as they appear.

***

### Why channel-normalized analysis matters

Raw views can be misleading. A video with 50,000 views may be weak for a huge creator but exceptional for a small channel. This Actor compares each video with that channel's recent performance so you can identify content that is genuinely unusual for that creator.

***

### Important

This Actor works with publicly accessible YouTube information. **Viral Score is an analytical metric created by this Actor and is not an official YouTube metric.** Performance metrics describe observed public data and do not guarantee future views or virality.

***

## Start finding winning YouTube content

Enter a competitor channel, run the Actor, and open **Viral / breakout finder**.

# Changelog

This Actor's version history is a separate document: https://apify.com/scravion/youtube-data-scraper-pro/changelog.md

# Actor input Schema

## `startUrls` (type: `array`):

Paste one or more public YouTube channel URLs. Also supports video, Shorts, playlist, live, and search URLs.

## `youtubeHandles` (type: `array`):

Optional alternative to a channel URL, for example @GoogleDevelopers.

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

Maximum number of accepted videos/Shorts to return across all sources.

## `calculateViralScore` (type: `boolean`):

Adds a 0–100 derived breakout score. This is an analytical metric, not an official YouTube metric.

## `outputSort` (type: `string`):

Recommended for competitor research: rank videos by how far they outperform the channel baseline.

## `channelAnalyticsSampleSize` (type: `integer`):

Number of recent channel videos used to calculate the average/median baseline and outlier multiplier.

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

Optional YouTube keyword search. Leave empty when analyzing a competitor channel.

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

Optional per-query settings. Each object requires query and may override maxItems, gl, hl, uploadDate, duration, features, and sort.

## `gl` (type: `string`):

Two-letter country code used by YouTube search and the popular feed, for example US, TR, or DE.

## `hl` (type: `string`):

YouTube interface/result language code, for example en, tr, de, pt-BR, or zh-CN.

## `uploadDate` (type: `string`):

Native search filter. Applies to keyword and search-URL discovery.

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

Native search duration filter. Exact seconds filters are available under Advanced filters.

## `features` (type: `string`):

Native search feature. It does not filter direct video URLs. CC maps to public subtitle/caption filtering.

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

Native YouTube search ordering.

## `getTrending` (type: `boolean`):

Request YouTube's current public popular feed for the selected country. When no stable Trending feed is exposed, output is explicitly labeled popular_fallback.

## `mode` (type: `string`):

Auto recognizes every supplied source. A specific mode limits processing to that source family.

## `includeShorts` (type: `boolean`):

Legacy compatibility alias. Explicit Shorts mode below takes precedence.

## `shortsMode` (type: `string`):

Post-processing filter across all discovered video sources.

## `minViews` (type: `integer`):

Post-processing filter for all videos.

## `maxViews` (type: `integer`):

Post-processing filter for all videos.

## `minLikes` (type: `integer`):

Post-processing filter; hidden like counts follow Missing metric behavior.

## `minSubscribers` (type: `integer`):

Post-processing filter when public subscriber count is available.

## `maxSubscribers` (type: `integer`):

Post-processing filter when public subscriber count is available.

## `minDurationSeconds` (type: `integer`):

Exact post-processing duration filter.

## `maxDurationSeconds` (type: `integer`):

Exact post-processing duration filter.

## `publishedAfter` (type: `string`):

Exact ISO date lower bound when publish date is available.

## `publishedBefore` (type: `string`):

Exact ISO date upper bound when publish date is available.

## `mustContainKeywords` (type: `array`):

Every value must occur in title or description (case-insensitive).

## `mustNotContainKeywords` (type: `array`):

Reject results containing any value in title or description.

## `missingMetricBehavior` (type: `string`):

Keep results with unavailable public metrics, or skip them when a corresponding numeric filter is active.

## `detailLevel` (type: `string`):

Basic is lean; Standard includes normal metadata; Full enables extended structures when requested.

## `resultTypes` (type: `array`):

Choose primary video/Short records and optional supporting channel/playlist records.

## `includeDescription` (type: `boolean`):

Include public video descriptions.

## `includeChannelInfo` (type: `boolean`):

Include public channel identity and subscriber information when available.

## `includeCaptions` (type: `boolean`):

Include public caption track metadata; does not automatically fetch transcript text.

## `transcriptMode` (type: `string`):

Optional transcript enrichment. Only publicly exposed transcripts are used; no access controls are bypassed.

## `maxTranscriptCharacters` (type: `integer`):

Safety cap per transcript; truncated outputs are labeled.

## `includeStreamingData` (type: `boolean`):

Optional temporary format metadata. URLs may expire and are not permanent download links.

## `includeThumbnails` (type: `boolean`):

Include public thumbnail variants and a best-thumbnail URL.

## `includeChapters` (type: `boolean`):

Include public video chapters in Full mode when available.

## `includeTags` (type: `boolean`):

Include public tags/keywords when available.

## `detectLanguage` (type: `boolean`):

Use lightweight script/keyword detection without a heavy model.

## `extractExternalLinks` (type: `boolean`):

Normalize and deduplicate URLs explicitly present in public text.

## `extractPublicContacts` (type: `boolean`):

Extract only emails and social/website URLs explicitly present in public text. No email reveal, guessing, login, or CAPTCHA bypass.

## `outputFormat` (type: `string`):

Nested JSON or flat dot-path fields for CSV, Sheets, and Airtable.

## `compatibilityMode` (type: `string`):

Reference adds stable aliases such as date, comments, channelId, channelName, channelUrl, and subscribers while retaining the modern extended fields.

## `fields` (type: `array`):

Optional safe field picker using names such as title, url, views, or channel.name. Leave empty for all fields.

## `outputMapping` (type: `object`):

Optional declarative mapping, for example channelName to $.channel.name. Only safe dot paths are accepted; no code executes.

## `incrementalMode` (type: `boolean`):

Remember stored video IDs under the chosen state key and emit only new primary results.

## `incrementalStateKey` (type: `string`):

Namespace that isolates state between Tasks or monitoring jobs.

## `stopWhenKnownItemFound` (type: `boolean`):

Useful for newest-first channel monitoring.

## `maxVideosPerChannel` (type: `integer`):

Per-channel discovery cap; global maxItems still wins.

## `maxVideosPerPlaylist` (type: `integer`):

Per-playlist discovery cap; global maxItems still wins.

## `maxItemsPerQuery` (type: `integer`):

Per-search cap; global maxItems still wins.

## `distributionMode` (type: `string`):

Balanced rotates between sources; sequential completes sources in their supplied order.

## `duplicateStrategy` (type: `string`):

Merge preserves discovered source attribution when possible; duplicates are never billed twice.

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

Use auto for adaptive concurrency (reduces after rate limits and cautiously increases while stable), or enter 1–32. Strict maxItems is serialized.

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

Optional Apify Proxy configuration. Credentials are never logged.

## `cookie` (type: `string`):

Optional encrypted public-browsing cookie. It is never logged and must not be used to bypass private, age, login, or other access controls.

## `saveErrors` (type: `boolean`):

Store sanitized per-source failures in a separate named Dataset.

## `debug` (type: `boolean`):

Log filter reasons without secrets or credentials.

## `dryRun` (type: `boolean`):

Discover and process without publishing or billing results. Experimental diagnostic option.

## `enableExperimentalFeatures` (type: `boolean`):

Reserved feature flag. Disabled by default and never changes core behavior unless explicitly enabled.

## `customMapFunction` (type: `string`):

Disabled by design: arbitrary JavaScript is unsafe. Use Output fields or Safe output mapping.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.youtube.com/@GoogleDevelopers"
    }
  ],
  "maxItems": 5,
  "calculateViralScore": true,
  "outputSort": "channel_multiplier_desc",
  "channelAnalyticsSampleSize": 20,
  "gl": "US",
  "hl": "en",
  "uploadDate": "all",
  "duration": "all",
  "features": "all",
  "sort": "relevance",
  "getTrending": false,
  "mode": "auto",
  "includeShorts": true,
  "shortsMode": "include",
  "missingMetricBehavior": "keep",
  "detailLevel": "standard",
  "resultTypes": [
    "video",
    "short"
  ],
  "includeDescription": true,
  "includeChannelInfo": true,
  "includeCaptions": false,
  "transcriptMode": "none",
  "maxTranscriptCharacters": 100000,
  "includeStreamingData": false,
  "includeThumbnails": true,
  "includeChapters": true,
  "includeTags": true,
  "detectLanguage": false,
  "extractExternalLinks": false,
  "extractPublicContacts": false,
  "outputFormat": "nested",
  "compatibilityMode": "none",
  "incrementalMode": false,
  "incrementalStateKey": "default",
  "stopWhenKnownItemFound": false,
  "distributionMode": "balanced",
  "duplicateStrategy": "merge",
  "maxConcurrency": "auto",
  "saveErrors": true,
  "debug": false,
  "dryRun": false,
  "enableExperimentalFeatures": false
}
```

# Actor output Schema

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

Accepted public YouTube results in the default Dataset.

## `runSummary` (type: `string`):

Counts, source statistics, performance, warnings, and billing observability.

## `workloadEstimate` (type: `string`):

Requested workload and optional enrichments without an unreliable up-front price promise.

## `state` (type: `string`):

Run output and optional incremental state 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 = {
    "startUrls": [
        {
            "url": "https://www.youtube.com/@GoogleDevelopers"
        }
    ],
    "maxItems": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("scravion/youtube-data-scraper-pro").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 = {
    "startUrls": [{ "url": "https://www.youtube.com/@GoogleDevelopers" }],
    "maxItems": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("scravion/youtube-data-scraper-pro").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 '{
  "startUrls": [
    {
      "url": "https://www.youtube.com/@GoogleDevelopers"
    }
  ],
  "maxItems": 5
}' |
apify call scravion/youtube-data-scraper-pro --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scravion/youtube-data-scraper-pro"
        }
    }
}
```

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/Bifadww2T5KBgJzsM/builds/CqMq7EfrNBKFR3YEz/openapi.json