# Fast YouTube Scraper API - Extract Videos, Channels, Playlists (`apidojo/youtube-scraper-api`) Actor

YouTube Scraper API - extract videos from channels, playlists, searches, trending & Shorts with one powerful actor. Transparent event-based pricing from $0.005/video, 30-100 free items per query, 10-19 videos/sec, rich JSON output, no proxies or login - perfect for research & analytics.

- **URL**: https://apify.com/apidojo/youtube-scraper-api.md
- **Developed by:** [API Dojo](https://apify.com/apidojo) (community)
- **Categories:** Videos, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 831 total users, 62 monthly users, 100.0% runs succeeded, 20 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.50 / 1,000 youtube video items

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?

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 Scraper API - Extract Videos, Channels, Playlists & Metadata at Scale

**Extract videos, channels, playlists, search results, trending content, Shorts, and Live Streams from YouTube-no API keys, no proxy setup required.**

Scrape @MrBeast, @kurzgesagt, any playlist, or search query in seconds. Get video metadata, engagement metrics (views, likes, comment counts), channel statistics, captions, and 50+ data fields in clean JSON/CSV format.

**Simple pricing:** $0.015 per channel/search query includes 30 FREE videos. Additional videos just $0.0005 each.

**💰 Pricing:** $0.015/query (30 videos FREE) + $0.0005/video\
**⚡ Speed:** 10-20 videos/second\
**📊 Output:** JSON/CSV with 50+ fields per video\
**🌍 Coverage:** 100+ languages, all countries\
**🚀 Start now:** Proxy handled • API & MCP ready

#### Why Teams Choose This Scraper

- ✅ **10-19 videos/second** - High-speed extraction (varies by query type and region)
- ✅ **30-100 free videos per query** - Generous free tier included
- ✅ **No API key required** - Works without official YouTube Data API access
- ✅ **No proxy setup** - Infrastructure handled automatically on Apify
- ✅ **8 query types** - Videos, channels, playlists, search, trending, Shorts, Live Streams, handles
- ✅ **MCP compatible** - Works with AI agents and LLM workflows
- ✅ **100+ languages** - Localized results via `gl` and `hl` parameters

Ideal for competitor analysis, content tracking, influencer research, market intelligence, and ML dataset building.

|                          |                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| **Use this if you need** | Channel/playlist/search/trending/Shorts/Live Streams metadata at scale                           |
| **Returns**              | JSON/CSV; key fields: `id`, `title`, `views`, `likes`, `comments` (count), `channel`, `captions` |
| **Typical speed**        | 10-19 videos/sec depending on query type                                                         |
| **Pricing**              | $0.015/query (30 videos FREE), then $0.0005/video                                                |

### 📋 Table of Contents

- [🧭 What Does YouTube Scraper Do?](#-what-does-youtube-scraper-do)
- [⚡ Features & YouTube Entity Coverage](#-features--youtube-entity-coverage)
- [💰 Pricing](#-pricing-transparent-event-based-costs)
- [🆓 Demo Mode & Free Users](#-demo-mode--free-users)
- [🍚 Input Parameters](#-input-parameters)
- [💡 Strategy Guide](#-youtube-scraper-strategy-guide)
- [📦 Output](#-output)
- [🧩 Custom Map Function](#-custom-map-function)
- [🔌 Send Results to Notion, Todoist & More](#-send-results-to-notion-todoist-and-more-mcp-connectors)
- [⚖️ YouTube Data API vs Scraper](#-youtube-data-api-vs-scraper-comparison)
- [🛡️ Reliability & Limitations](#-reliability--limitations)
- [🤖 MCP Integration](#-mcp-integration-for-ai-agents--llm-workflows)
- [🈴 Related YouTube Scrapers](#-related-youtube-scrapers--data-extraction-tools)
- [🔧 Troubleshooting](#-troubleshooting-common-issues)
- [🎯 Use Cases](#-use-cases--industries)
- [💡 Quick Start Guide](#-quick-start-guide)
- [❓ FAQ](#-frequently-asked-questions)
- [📞 Contact](#-contact)

### 🧭 What Does YouTube Scraper Do?

YouTube scraping automates the extraction of video metadata, channel statistics, playlist content, engagement metrics, and search results from YouTube.com. This enables content analysis, competitor monitoring, influencer research, trend tracking, and building ML datasets at scale.

The Api Dojo YouTube Scraper is a powerful, all-in-one actor built to extract videos, channels, playlists, searches, trending content, and Shorts. Collect structured metadata quickly and reliably-without API keys or complex setup.

This scraper serves as a practical alternative to the official YouTube Data API for bulk extraction. No quota limits, no API key management-just straightforward data access through Apify's infrastructure.

#### Complete YouTube Entity Coverage

This scraper understands and extracts all core YouTube entities:

| Entity                       | What You Get                                                                               | Use Case                               |
| ---------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------- |
| 🎬 **YouTube Video**          | Title, description, views, likes, comments, duration, thumbnails, streaming URLs, captions | Video analytics, content research      |
| 👤 **YouTube Channel**        | Name, handle, subscriber count, video count, thumbnails, badges, verification              | Channel analysis, influencer discovery |
| 📋 **YouTube Playlist**       | All videos in playlist, playlist metadata, video order                                     | Content curation, course analysis      |
| 💬 **YouTube Comment**        | Comment text, author, likes, replies (via Comments Scraper)                                | Sentiment analysis, audience insights  |
| 🎥 **YouTube Shorts**         | Short-form video data with full metadata                                                   | Shorts trend tracking                  |
| 📺 **YouTube Live Streams**   | Past and active live stream data with full metadata                                        | Live content monitoring                |
| 🔍 **YouTube Search Results** | Videos matching keywords with filters; Shorts when `includeShorts` is enabled              | Keyword research, content discovery    |
| 📈 **YouTube Trending**       | Currently trending videos by country                                                       | Trend analysis, viral content          |

### ⚡ Features & YouTube Entity Coverage

Complete, structured access to YouTube's public data-videos, channels, playlists, search, trending, Shorts, and Live Streams. Built for content analysis and growth intelligence at scale.

#### 8 Query Types for Complete Coverage

| Query Type           | What It Extracts                       | Example Input                              |
| -------------------- | -------------------------------------- | ------------------------------------------ |
| 🎬 **Single Video**   | Detailed data from individual videos   | `https://www.youtube.com/watch?v=VIDEO_ID` |
| 👤 **Channel**        | All videos from any YouTube channel    | `https://www.youtube.com/@MrBeast`         |
| 📋 **Playlist**       | Complete playlists with all video data | `https://www.youtube.com/playlist?list=ID` |
| 🔍 **Search**         | Videos matching specific keywords (add `includeShorts` for Shorts) | `machine learning tutorial`                |
| 📈 **Trending**       | Currently trending videos by country   | `getTrending: true`                        |
| 🎥 **Shorts**         | YouTube Shorts from channels **and** keyword searches | `includeShorts: true`                      |
| 📺 **Live Streams**   | Past and active live streams           | `includeLiveStreams: true`                  |
| 🔥 **Handle**         | Channels by handle (@username)         | `@kurzgesagt`                              |

#### Core Features

| Feature                   | Description                                      | Benefit                                    |
| ------------------------- | ------------------------------------------------ | ------------------------------------------ |
| 💰 **Event-Based Pricing** | Pay only for videos you extract-no subscriptions | Cost control: Only pay for what you scrape |
| 🎁 **30-100 Free Videos**  | Generous free tier with every query              | Budget-friendly: Substantial free data     |
| ⚡ **10-19 Videos/Second** | High-speed extraction across all query types     | Time savings: Extract thousands in minutes |
| 🔑 **No API Key Required** | Works without YouTube Data API access            | Simple: No quota limits or API setup       |
| 🚀 **No Proxy Setup**      | Infrastructure handled on Apify                  | Cost savings: No proxy management          |
| 🌍 **100+ Languages**      | Multi-language and country support               | Global: Localized content extraction       |
| 📅 **Advanced Filters**    | Upload date, duration, features, sorting         | Precision: Target specific content         |
| 🎯 **Query Wizard**        | Build queries without technical knowledge        | Easy: No coding required                   |
| 📊 **Rich Metadata**       | 50+ fields including captions and streaming URLs | Complete: All video data in one call       |
| 🤖 **MCP Compatible**      | Works with AI agents and LLM workflows           | Future-ready: AI-native integration        |
| 📥 **JSON/CSV Export**     | Clean structured output for analysis             | Integration-ready: Direct pipeline import  |

### 💰 Pricing: Transparent Event-Based Costs

Pay-per-use pricing with no subscriptions, hidden fees, or monthly minimums. Significantly more affordable than most alternatives for bulk extraction.

**Free users**: Limited to **5 runs per month**, each capped at **10 items**.

#### 📊 Event Costs by Query Type

| Event Type             | Price       | Free Videos Included | What Triggers It                |
| ---------------------- | ----------- | -------------------- | ------------------------------- |
| **Playlist Query**     | **$0.05**   | **100 videos FREE**  | Scraping a YouTube playlist     |
| **Trending Query**     | **$0.025**  | **50 videos FREE**   | Getting trending videos         |
| **Shorts Query**       | **$0.02**   | **40 videos FREE**   | When `includeShorts` is enabled on a channel or keyword search |
| **Live Streams Query** | **$0.02**   | **40 videos FREE**   | When `includeLiveStreams` is enabled   |
| **Channel Query**      | **$0.015**  | **30 videos FREE**   | Scraping a YouTube channel      |
| **Search Query**       | **$0.015**  | **30 videos FREE**   | Performing a keyword search     |
| **Single Video Query** | **$0.005**  | **Flat rate**        | Fetching a single video         |
| **Dataset Item**       | **$0.0005** | N/A                  | Each video beyond free quota    |

#### 💡 How Charges Work

**Playlist Queries ($0.05):**

- Each query includes **100 videos FREE**
- Additional videos beyond 100 cost $0.0005 each

**Trending Queries ($0.025):**

- Each query includes **50 videos FREE**
- Additional videos beyond 50 cost $0.0005 each

**Channel/Search Queries ($0.015):**

- Each query includes **30 videos FREE**
- Additional videos beyond 30 cost $0.0005 each

**Shorts Queries ($0.02):**

- Charged once per channel **or** keyword when `includeShorts: true`
- Each query includes **40 videos FREE**
- Additional videos beyond 40 cost $0.0005 each

**Single Video Queries ($0.005):**

- Flat rate per video (returns 1 video per query)
- No additional charges

#### 📈 Cost Examples

| Scenario                   | Charges                  | Calculation                    | Total Cost |
| -------------------------- | ------------------------ | ------------------------------ | ---------- |
| **1 channel, 30 videos**   | 1 channel query          | $0.015                         | **$0.015** |
| **1 channel, 200 videos**  | 1 query + 170 items      | $0.015 + ($0.0005 × 170)       | **$0.100** |
| **1 playlist, 100 videos** | 1 playlist query         | $0.05                          | **$0.050** |
| **1 playlist, 500 videos** | 1 query + 400 items      | $0.05 + ($0.0005 × 400)        | **$0.250** |
| **5 searches, 300 videos** | 5 queries + 150 items    | ($0.015 × 5) + ($0.0005 × 150) | **$0.150** |
| **1 search + shorts, 200 videos** | 1 search + 1 shorts + 130 items | $0.015 + $0.02 + ($0.0005 × 130) | **$0.100** |
| **Trending, 100 videos**   | 1 query + 50 items       | $0.025 + ($0.0005 × 50)        | **$0.050** |
| **10 single videos**       | 10 queries               | $0.005 × 10                    | **$0.050** |
| **10,000 videos**          | Multiple queries + items | Varies by source               | **~$5.00** |

💡 **Pro Tip**\
Each query includes generous FREE videos! This makes **YouTube data collection** incredibly **cost-effective** for market research, content analysis, and **YouTube data for machine learning** projects.

### 🆓 Demo Mode & Free Users

If you run on Apify's Free plan, you can still use this **YouTube Scraper API** in Demo Mode. **Free users can run the actor up to 5 times per month**, with each run capped at a maximum of 10 items — just enough to test it out. For unrestricted **YouTube data collection**, subscribe to a paid plan on Apify. [Subscribe here](https://apify.com/pricing?fpr=yhdrb).

### 🍚 Input Parameters

Flexible input options for targeting multiple YouTube data surfaces - videos, channels, playlists, search, trending, and Shorts - with simple configuration.

| Field                 | Type    | Description                                             | Default    |
| --------------------- | ------- | ------------------------------------------------------- | ---------- |
| **startUrls**         | array   | YouTube URLs (Video, Channel, Playlist, Shorts, Search) | `[]`       |
| **youtubeHandles**    | array   | YouTube handles (e.g., @MrBeast, @kurzgesagt)           | `[]`       |
| **keywords**          | array   | Search keywords for YouTube search. Pair with `includeShorts` to also return Shorts. | `[]`       |
| **getTrending**       | boolean | Retrieve currently trending videos                      | `false`    |
| **includeShorts**     | boolean | Include YouTube Shorts from channels **and** keyword searches | `false`    |
| **includeLiveStreams** | boolean | Include YouTube Live Streams from channels              | `false`    |
| **fetchLatestMetadata** | boolean | Make an extra request per video to fetch its latest view and like counts (added as `latestMetadata`) | `false`    |
| **gl**                | string  | Country code (US, GB, DE, etc.)                         | `US`       |
| **hl**                | string  | Language code (en, es, de, etc.)                        | `en`       |
| **uploadDate**        | string  | Filter: any, hour, today, week, month, year (This filter only works with search keywords, not with profiles or startUrls)            | `all`      |
| **duration**          | string  | Filter: any, short, long                                | `all`      |
| **features**          | string  | Filter: 4k, hd, live, movie, cc, subtitles, etc.        | `all`      |
| **sort**              | string  | Sort: relevance, upload_date, view_count, rating        | `r`        |
| **maxItems**          | integer | Maximum total videos to output                          | `Infinity` |
| **customMapFunction** | string  | JavaScript function to transform each output item. Ignored with a warning if it is not a usable function | `null`     |
| **outputConnector**   | string  | MCP connector to deliver the results to - pick one (see [Send Results to Notion, Todoist and More (MCP Connectors)](#-send-results-to-notion-todoist-and-more-mcp-connectors)). | `null`     |
| **deliverTarget**     | string  | Where the connector writes - paste the URL or ID (Notion example: `https://www.notion.so/My-Posts-24f8a1b2c3d44e5f8a9b0c1d2e3f4a5b`); some services need none. | `null`     |
| **deliverMode**       | string  | `perPost` (one record per item) or `summary` (one roll-up per run). | `perPost`  |
| **deliverMaxItems**   | integer | Optional cap on how many records `perPost` delivers (ignored in `summary`). | `null`     |

**Note:** Provide at least one of: `startUrls`, `youtubeHandles`, `keywords`, or enable `getTrending`.

#### Supported URL Types

| URL Type             | Format                                                 | Example                                                                    |
| -------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- |
| 🎬 **Single Video**   | `https://www.youtube.com/watch?v=ID`                   | `https://www.youtube.com/watch?v=dQw4w9WgXcQ`                              |
| 👤 **Channel**        | `https://www.youtube.com/@handle`                      | `https://www.youtube.com/@MrBeast`                                         |
| 📋 **Playlist**       | `https://www.youtube.com/playlist?list=ID`             | `https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf` |
| 🔍 **Search**         | `https://www.youtube.com/results?search_query=keyword` | `https://www.youtube.com/results?search_query=AI`                          |
| 🎥 **Shorts**         | `https://www.youtube.com/shorts/ID`                    | `https://www.youtube.com/shorts/abc123`                                    |
| 📺 **Channel Shorts**        | `https://www.youtube.com/@handle/shorts`   | `https://www.youtube.com/@MrBeast/shorts`   |
| 🔴 **Channel Live Streams**  | `https://www.youtube.com/@handle/streams`  | `https://www.youtube.com/@MrBeast/streams`  |

### 💡 YouTube Scraper Strategy Guide

Choose the right strategy based on your data needs and budget. Each approach optimizes for different **YouTube data extraction** use cases.

#### Strategy 1: Scrape YouTube Channel (Creator Analysis)

**Best for:** YouTube competitor analysis, influencer research, content performance tracking

```json
{
  "startUrls": ["https://www.youtube.com/@kurzgesagt"],
  "maxItems": 200
}
```

| Cost Breakdown        | Calculation            |
| --------------------- | ---------------------- |
| 1 channel query       | $0.015                 |
| 170 additional videos | $0.0005 × 170 = $0.085 |
| **Total**             | **$0.100**             |

**Use case:** Extract complete channel data for **YouTube channel statistics API** analysis, content strategy research, and creator benchmarking.

***

#### Strategy 2: Scrape YouTube Playlist (Course/Series Analysis)

**Best for:** Educational content research, playlist curation, series analysis

```json
{
  "startUrls": ["https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"],
  "maxItems": 500
}
```

| Cost Breakdown        | Calculation            |
| --------------------- | ---------------------- |
| 1 playlist query      | $0.05                  |
| 400 additional videos | $0.0005 × 400 = $0.200 |
| **Total**             | **$0.250**             |

**Use case:** Extract complete playlist for course analysis, content curation, and **YouTube playlist** research.

***

#### Strategy 3: YouTube Search Scraping (Keyword Research)

**Best for:** YouTube keyword search API, content discovery, market research

```json
{
  "keywords": ["machine learning tutorial", "AI for beginners"],
  "hl": "en",
  "gl": "US",
  "uploadDate": "month",
  "maxItems": 200
}
```

| Cost Breakdown        | Calculation            |
| --------------------- | ---------------------- |
| 2 search queries      | $0.015 × 2 = $0.030    |
| 140 additional videos | $0.0005 × 140 = $0.070 |
| **Total**             | **$0.100**             |

**Use case:** **Scrape YouTube search results** for keyword research, content gap analysis, and **YouTube trending videos API** discovery.

**Tip:** Set `includeShorts: true` to also extract Shorts matching each keyword (see Strategy 7).

***

#### Strategy 4: YouTube Trending Videos (Trend Analysis)

**Best for:** Viral content discovery, trend tracking, cultural analysis

```json
{
  "getTrending": true,
  "gl": "US",
  "maxItems": 100
}
```

| Cost Breakdown       | Calculation           |
| -------------------- | --------------------- |
| 1 trending query     | $0.025                |
| 50 additional videos | $0.0005 × 50 = $0.025 |
| **Total**            | **$0.050**            |

**Use case:** Track **YouTube trending videos** for viral content analysis and cultural trend research.

***

#### Strategy 5: Single Video Extraction (Specific Content)

**Best for:** Competitor video analysis, viral content study, specific video data

```json
{
  "startUrls": [
    "https://www.youtube.com/watch?v=xuCn8ux2gbs",
    "https://www.youtube.com/watch?v=kXYiU_JCYtU"
  ]
}
```

| Cost Breakdown         | Calculation         |
| ---------------------- | ------------------- |
| 2 single video queries | $0.005 × 2 = $0.010 |
| **Total**              | **$0.010**          |

**Use case:** Get detailed **YouTube video stats API** data for specific videos.

***

#### Strategy 6: Channel + Shorts (Complete Creator Data)

**Best for:** Full creator analysis including short-form content

```json
{
  "youtubeHandles": ["@MrBeast"],
  "includeShorts": true,
  "maxItems": 200
}
```

| Cost Breakdown        | Calculation            |
| --------------------- | ---------------------- |
| 1 channel query       | $0.015                 |
| 1 shorts query        | $0.02                  |
| 130 additional videos | $0.0005 × 130 = $0.065 |
| **Total**             | **$0.100**             |

**Use case:** Complete creator analysis including **YouTube Shorts** for comprehensive content strategy research.

***

#### Strategy 7: Search + Shorts (Keyword Discovery Including Short-Form)

**Best for:** Keyword research that should also cover YouTube Shorts, not just long-form results

```json
{
  "keywords": ["machine learning tutorial"],
  "includeShorts": true,
  "maxItems": 200
}
```

| Cost Breakdown        | Calculation            |
| --------------------- | ---------------------- |
| 1 search query        | $0.015                 |
| 1 shorts query        | $0.02                  |
| 130 additional videos | $0.0005 × 130 = $0.065 |
| **Total**             | **$0.100**             |

**Use case:** Discover both regular videos and **YouTube Shorts** for a search term. Each keyword charges one Search Query plus one Shorts Query.

***

#### Strategy Comparison Table

| Strategy           | Best For         | Cost per 100 Videos | Free Videos    |
| ------------------ | ---------------- | ------------------- | -------------- |
| 👤 Channel          | Creator analysis | $0.050              | 30             |
| 📋 Playlist         | Course/series    | $0.050              | 100            |
| 🔍 Search           | Keyword research | $0.050              | 30 per keyword |
| 📈 Trending         | Trend analysis   | $0.050              | 50             |
| 🎬 Single Video     | Specific content | $0.005/video        | N/A            |
| 🎥 Channel + Shorts | Full creator     | $0.065              | 70             |
| 🔍 Search + Shorts  | Keyword + short-form | $0.065          | 70             |

#### Pro Tips for Cost Optimization

##### ✅ Maximize Free Videos

- **Use playlists** - 100 free videos per playlist query
- **Batch channels** - 30 free videos per channel
- **Combine searches** - 30 free videos per keyword
- **Enable `includeShorts`** - 40 extra free videos per channel or keyword

##### ✅ Control Spending

- **Set `maxItems`** - Limit total videos to control costs
- **Use filters** - Narrow results with uploadDate, duration, features
- **Start small** - Test with 50-100 videos before scaling

### 📦 Output

Clean, structured JSON output with comprehensive video information. Each video object contains 50+ fields.

#### Minimal Example (Core Fields)

```json
{
  "id": "lfR7Qj04-UA",
  "title": "The Ultimate Pixel Art Tutorial",
  "url": "https://www.youtube.com/watch?v=lfR7Qj04-UA",
  "description": "Learn pixel art fundamentals in this comprehensive tutorial...",
  "duration": 854,
  "views": 1997072,
  "likes": 93698,
  "comments": 1449,
  "channel": {
    "id": "UCMLJ_TROV89ll587opuuY4w",
    "name": "Saultoons",
    "handle": "/@saultoons",
    "subscriberCount": "177K subscribers",
    "badges": ["Verified"]
  },
  "keywords": ["pixel art tutorial", "pixel art", "aseprite"],
  "category": "Entertainment",
  "publishDate": "2021-06-17T10:46:54-07:00",
  "isLive": false,
  "isFamilySafe": true
}
```

#### Field Availability Guarantees

Understanding which fields are always present vs. conditionally available helps you build reliable integrations.

| Field           | Availability | Data Type | Notes                             |
| --------------- | ------------ | --------- | --------------------------------- |
| `id`            | ✅ Always     | string    | Unique video ID                   |
| `url`           | ✅ Always     | string    | Full video URL                    |
| `title`         | ✅ Always     | string    | Video title                       |
| `channel.id`    | ✅ Always     | string    | Channel ID                        |
| `channel.name`  | ✅ Always     | string    | Channel display name              |
| `views`         | ✅ Always     | integer   | Total view count                  |
| `duration`      | ✅ Always     | integer   | Length in seconds                 |
| `publishDate`   | ✅ Always     | ISO-8601  | Publication timestamp             |
| `likes`         | ⚠️ Sometimes  | integer   | Hidden on some videos             |
| `comments`      | ⚠️ Sometimes  | integer   | Disabled on some videos           |
| `captions`      | ⚠️ Sometimes  | array     | Not all videos have captions      |
| `streamingData` | ⚠️ Sometimes  | object    | May be restricted; optional field |
| `description`   | ⚠️ Sometimes  | string    | May be empty                      |

**Note:** `streamingData` contains direct video URLs in multiple qualities. This field is optional and may not be available for all videos (age-restricted, geo-blocked, or premium content). Use `customMapFunction` to exclude it if not needed.

<details>
<summary><strong>📋 Full Example Output (click to expand)</strong></summary>

```json
{
  "inputSource": "pixel art",
  "type": "video",
  "id": "lfR7Qj04-UA",
  "title": "The Ultimate Pixel Art Tutorial",
  "status": "OK",
  "url": "https://www.youtube.com/watch?v=lfR7Qj04-UA",
  "description": "Learn pixel art fundamentals...",
  "duration": 854,
  "views": 1997072,
  "likes": 93698,
  "comments": 1449,
  "channel": {
    "id": "UCMLJ_TROV89ll587opuuY4w",
    "name": "Saultoons",
    "handle": "/@saultoons",
    "url": "https://www.youtube.com/channel/UCMLJ_TROV89ll587opuuY4w",
    "subscriberCount": "177K subscribers",
    "thumbnails": [{"url": "...", "width": 176, "height": 176}],
    "badges": ["Verified"]
  },
  "keywords": ["pixel art tutorial", "pixel art", "aseprite", "..."],
  "superTitle": "#pixelarttutorial #pixelart #tutorial",
  "isRatingsAllowed": true,
  "isLive": false,
  "isFamilySafe": true,
  "category": "Entertainment",
  "isPrivate": false,
  "thumbnails": [{"url": "...", "width": 1280, "height": 720}],
  "embedUrl": "https://www.youtube.com/embed/lfR7Qj04-UA",
  "isEmbeddable": true,
  "publishDate": "2021-06-17T10:46:54-07:00",
  "uploadDate": "2021-06-17T10:46:54-07:00",
  "captions": {"captionTracks": [{"name": "English", "languageCode": "en"}]},
  "streamingData": {"formats": [{"qualityLabel": "1080p", "...": "..."}]},
  "videoPreviews": [{"url": "...", "width": 320, "height": 180}]
}
```

</details>

#### Export Options

- **JSON:** Complete datasets with nested objects-ideal for programmatic processing
- **CSV:** Direct download from Apify Console-perfect for spreadsheets and databases
- **API:** RESTful endpoints for Python, Node.js, or any HTTP client

### 🧩 Custom Map Function

Transform output using the `customMapFunction` parameter. This JavaScript function receives each video object and returns your desired format-add engagement metrics, flatten channel data, or calculate custom analytics.

**Important:** Custom map function is for data transformation-**not for filtering**. Filtering items may result in automatic restrictions. Returning an empty object does not remove the item from the dataset-it is saved as `{ "noResults": true }` instead.

#### Example: Engagement Rate Calculation

```javascript
(object) => ({
  ...object,
  engagementRate: (object.likes / object.views * 100).toFixed(2),
  channelName: object.channel?.name,
  subscriberCount: object.channel?.subscriberCount,
  durationMinutes: Math.floor(object.duration / 60),
  isViral: object.views > 1000000,
  streamingData: undefined,
  captions: undefined
})
```

#### Common Transformations

| Use Case                | What to Add                                           |
| ----------------------- | ----------------------------------------------------- |
| **Engagement Analysis** | `engagementRate`, `likesToViews`, `performanceScore`  |
| **Channel Flattening**  | `channelName`, `subscriberCount`, `isVerified`        |
| **Viral Detection**     | `isViral`, `viralTier`, `viewsPerDay`                 |
| **Data Cleanup**        | Set `streamingData: undefined`, `captions: undefined` |

#### Requirements & Error Handling

The value must be a **single JavaScript function** that takes one item and returns the transformed item. Arrow functions and regular functions both work; `async` and generator functions are not supported.

**Limits:** the function runs in an isolated sandbox. It must be synchronous and finish within about 1 second per item, and only plain JavaScript is available (no network requests, `require` or `console`). Each item is passed in as plain JSON data.

**An unusable function never stops your run.** The actor logs a warning, ignores the function, and saves the original, unmodified items instead-so you still get your data:

| Situation | What happens |
| --------- | ------------ |
| Not valid JavaScript (for example, plain text pasted into the field) | Rejected before the first request; original items are saved |
| Valid JavaScript but not a function (for example, an object) | Rejected before the first request; original items are saved |
| `async` or generator function | Rejected before the first request; original items are saved |
| Returns a Promise (for example, `(object) => Promise.resolve(object)`) | Rejected at that point; the remaining items are saved unmodified |
| Returns something other than an object (for example, a number or `null`) | Rejected at that point; the remaining items are saved unmodified |
| Throws while transforming an item | Rejected at that point; the remaining items are saved unmodified |
| Takes longer than about 1 second on one item (for example, an endless loop) | Rejected at that point; the remaining items are saved unmodified |
| Uses date operations (`new Date`, `Date.now`, `1970`) | Rejected before the first request; original items are saved. Use the `uploadDate` input to filter search results by date instead |

If your output does not look transformed, check the run log for a warning that starts with `Your "customMapFunction" input was rejected:`-it explains exactly what was wrong.

If you do not need to transform the output, simply leave this field empty.

### 🔌 Send Results to Notion, Todoist and More (MCP Connectors)

Skip the manual exports - the YouTube Scraper can deliver its results directly into the tools you already work in, through [Apify MCP Connectors](https://apify.com/store/collections/mcp-connectors). This is the reverse of [MCP Integration for AI Agents](#-mcp-integration-for-ai-agents--llm-workflows) below: there an AI agent runs this Actor; here the Actor writes its results into your own tools.

1. Authorize a connector (Notion, Todoist, or any service whose MCP server offers non-destructive write tools) once in [Console → Settings → API & Integrations → MCP connectors](https://console.apify.com/settings/integrations).
2. Pick it from the **Send results to Notion, Todoist, …** dropdown.
3. Fill in where and how to write:
   - **Destination target** - paste the URL or ID (Notion example: `https://www.notion.so/My-Posts-24f8a1b2c3d44e5f8a9b0c1d2e3f4a5b`); share it with your connector first via Notion's **•••  → Connections** menu. For structured columns use a **page** URL (the Actor builds the database for you) or a database that **already has columns** - an empty database only receives titles. (Some services need no target.)
   - **Write mode** - `perPost` writes one record per video; `summary` writes a single roll-up for the run.
   - **Max records to deliver** *(optional)* - cap on how many records `perPost` delivers.

**Notion, structured like a spreadsheet:** for a table of typed columns, point the target at a Notion **page** - the Actor auto-creates a database from the data, one matching, correctly-typed column per field (URL, number, date, text). Pointing at an **existing database** fills the columns it already has (matched by name); an **empty database** receives only the title, and the rest of each record goes to the row body - the connector can't add columns to an existing database without destructive access it never requests. Nested fields are flattened into columns too - a `channel` object becomes `channel.name`, `channel.subscriberCount`, … and a list like `keywords` becomes a comma-joined column - so everything is sortable and filterable in the grid. Fields that don't fit a column go to the row's page body, so nothing is lost.

Your credentials stay yours: the Actor talks to your services exclusively through your own authorized connector and only ever uses non-destructive write tools - it cannot delete or overwrite anything you already have. Delivery is best-effort and runs after the scrape: if a connector is misconfigured or a delivery fails, your run still finishes normally with all results intact - the failure is reported in the run log, never by failing the run. If the run is about to hit its timeout, delivery stops early so the run still succeeds, and the log tells you how many records were delivered.

### ⚖️ YouTube Data API vs Scraper Comparison

Choosing between the official YouTube Data API and a scraper depends on your use case, volume, and budget. Here's an honest comparison.

| Factor               | Official YouTube Data API       | YouTube Scraper (This Tool)                                                          |
| -------------------- | ------------------------------- | ------------------------------------------------------------------------------------ |
| **Quota limits**     | 10,000 units/day (strict)       | No quota limits                                                                      |
| **Setup complexity** | OAuth, API keys, project setup  | No setup-runs on Apify                                                               |
| **Cost at scale**    | Free tier, then complex pricing | $0.50 per 1,000 videos                                                               |
| **Data coverage**    | Official but limited fields     | 50+ fields including streaming URLs                                                  |
| **Rate limiting**    | Aggressive throttling           | Managed automatically                                                                |
| **Comment threads**  | Requires separate API calls     | Use [Comments Scraper](https://apify.com/apidojo/youtube-comments-scraper?fpr=yhdrb) |
| **Compliance**       | Official, ToS-compliant         | Public data extraction                                                               |

#### When to Use the Official API

- You need **write access** (upload, modify playlists)
- Your app requires **OAuth user authentication**
- You're building a **production app** that needs official support
- Volume is **low** (<10K requests/day)

#### When to Use This Scraper

- You need **bulk data extraction** (10K+ videos)
- You want **no quota limits** or API key management
- You need **additional fields** not in the official API
- You're doing **research, analysis, or ML training**
- You want **predictable, transparent pricing**

### 🛡️ Reliability & Limitations

Transparency about what this scraper can and cannot do helps you plan integrations and set realistic expectations.

#### What Affects Speed

| Factor                 | Impact                                  |
| ---------------------- | --------------------------------------- |
| **Query type**         | Playlists are faster than searches      |
| **Region**             | Some regions have slower response times |
| **Time of day**        | Peak hours may be slightly slower       |
| **Video availability** | Deleted/private videos are skipped      |

**Typical performance:** 10-19 videos/second under normal conditions. Large playlists (1000+ videos) may take longer due to pagination.

#### Data That May Be Missing

| Field           | When It's Missing                               |
| --------------- | ----------------------------------------------- |
| `likes`         | Creator has hidden like counts                  |
| `comments`      | Comments are disabled on the video              |
| `captions`      | No captions uploaded for the video              |
| `streamingData` | Age-restricted, geo-blocked, or premium content |
| `description`   | Creator left description empty                  |

#### Content We Cannot Access

- ❌ **Private videos** - Not publicly accessible
- ❌ **Member-only content** - Requires channel membership
- ❌ **Age-restricted videos** - May have limited data
- ❌ **Geo-blocked content** - Depends on Apify server location
- ❌ **Deleted videos** - No longer exist on YouTube

#### Retry Behavior

The scraper automatically retries failed requests with exponential backoff. If a video consistently fails, it's skipped and logged. Check the run log for any skipped items.

#### Compliance Note

This scraper extracts publicly available data from YouTube. It does not bypass any authentication, access private content, or violate user privacy. Use extracted data responsibly and in accordance with applicable laws and YouTube's Terms of Service.

### 🤖 MCP Integration for AI Agents & LLM Workflows

This scraper is **MCP (Model Context Protocol) compatible**, making it ideal for AI agents, LLM workflows, and automated intelligence systems.

#### What is MCP?

MCP (Model Context Protocol) is an emerging standard for connecting AI models to external data sources and tools. It enables AI agents like Claude, GPT, and custom LLMs to access real-time YouTube data for analysis, research, and decision-making.

#### Why MCP Matters for YouTube Data

| Capability                | Benefit                                                          |
| ------------------------- | ---------------------------------------------------------------- |
| **Real-time data access** | AI agents can query live YouTube trends, not just training data  |
| **Structured output**     | Clean JSON format integrates seamlessly with LLM context windows |
| **Automated workflows**   | Trigger scrapes based on AI agent decisions                      |
| **Research augmentation** | Enhance AI research with current video intelligence              |

#### MCP Use Cases

- **AI-Powered Content Analysis** - LLMs analyze YouTube trends in real-time
- **Automated Competitor Monitoring** - AI agents track competitor channels
- **Content Strategy Bots** - Automated content research and ideation
- **Brand Monitoring Agents** - AI monitors brand mentions and sentiment
- **Research Assistants** - AI researchers access current YouTube data

#### Integration Example

```python
## Example: Using YouTube Scraper with AI agent via Apify API
from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

## Run YouTube Scraper
run = client.actor("apidojo/youtube-scraper").call(run_input={
    "keywords": ["AI tutorial"],
    "maxItems": 100
})

## Get results for LLM context
dataset = client.dataset(run["defaultDatasetId"]).list_items()

## Feed to AI agent for analysis
youtube_context = json.dumps(dataset.items)
## Pass youtube_context to your LLM/AI agent
```

### 🈴 Related YouTube Scrapers & Data Extraction Tools

Expand your **YouTube data extraction** capabilities with our complete suite of specialized YouTube scraper APIs. Each tool focuses on specific data types for comprehensive video intelligence.

#### 📦 Complete Apidojo YouTube Scraper Ecosystem

| Tool                                                                                           | What It Extracts                                      | Best For                                 |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------- |
| 📺 **YouTube Scraper**                                                                          | Videos, channels, playlists, search, trending, Shorts | All-in-one extraction **(You are here)** |
| 💬 **[YouTube Comments Scraper](https://apify.com/apidojo/youtube-comments-scraper?fpr=yhdrb)** | Comments, replies, user interactions                  | Sentiment analysis, audience insights    |
| 👤 **[YouTube Channel Scraper](https://apify.com/apidojo/youtube-channel-scraper?fpr=yhdrb)**   | Channel statistics, subscriber data                   | Channel analysis, influencer research    |
| 📋 **[YouTube Playlist Scraper](https://apify.com/apidojo/youtube-playlist-scraper?fpr=yhdrb)** | Playlist videos, course content                       | Educational content, series analysis     |

#### 🌐 Cross-Platform Social Media Scrapers

| Platform    | Tool                                                                           | What It Extracts                    |
| ----------- | ------------------------------------------------------------------------------ | ----------------------------------- |
| 🎵 TikTok    | **[TikTok Scraper](https://apify.com/apidojo/tiktok-scraper?fpr=yhdrb)**       | Videos, profiles, hashtags, sounds  |
| 📸 Instagram | **[Instagram Scraper](https://apify.com/apidojo/instagram-scraper?fpr=yhdrb)** | Posts, profiles, hashtags, comments |
| 🐦 Twitter   | **[Twitter Scraper](https://apify.com/apidojo/twitter-scraper?fpr=yhdrb)**     | Tweets, profiles, followers         |

### 🔧 Troubleshooting Common Issues

#### ❓ Getting Fewer Results Than Expected?

**Problem:** Extraction returns fewer YouTube videos than anticipated

**Solutions:**

✅ **Check `maxItems` setting** - Increase the limit if you need more videos\
✅ **Verify filters** - Ensure `uploadDate`, `duration`, `features` aren't too restrictive\
✅ **Remember free tiers** - Each query includes 30-100 FREE videos automatically\
✅ **Remember Free Plan limits** - Free users are limited to **5 runs per month**, each capped at **10 items**

***

#### 💰 Unexpected Costs?

**Problem:** Your YouTube Scraper run cost more than anticipated

**Solutions:**

✅ **Each URL/keyword creates a separate query** - 10 channels = 10 × $0.015 = $0.15 in base costs\
✅ **`includeShorts` adds a Shorts Query** - $0.02 extra per channel **or** keyword when enabled\
✅ **Playlist queries cost more** - $0.05 vs $0.015 for channels, but include 100 free videos\
✅ **Use `maxItems` to cap spending** - Set a limit to control total extraction volume

***

#### ❓ No Results Returned?

**Problem:** Extraction completes but returns empty dataset

**Solutions:**

✅ **Verify input format** - Provide at least one of: `startUrls`, `youtubeHandles`, `keywords`, or `getTrending`\
✅ **Check URLs** - Must be valid YouTube URLs\
✅ **Test filters** - Overly restrictive filters may return no results

***

#### ❓ Missing Data Fields?

**Problem:** Some expected fields are missing from output

**Solutions:**

✅ **Open Storage tab** - Full datasets available in Apify Console, not all fields show in preview\
✅ **Check video availability** - Private or deleted videos won't appear in results

### 🎯 Use Cases & Industries

This scraper serves professionals who need fast, structured YouTube insights-from competitor analysis to ML dataset building.

***

#### 📊 Marketing & Campaign Strategy

Track content performance, analyze trends, and optimize campaigns.

- Analyze competitor channel strategies
- Track views, likes, and engagement across campaigns
- Monitor trending videos for viral opportunities

**Example:** Benchmark your content against 5 competitor channels.

***

#### 🔬 Research & Data Science

Build large-scale datasets for academic research, NLP, and ML training.

- Extract 100K+ videos for research datasets
- Structured JSON/CSV for statistical analysis
- Analyze cultural trends and social movements

**Example:** Build a 50K video dataset on climate change content.

***

#### 🎥 Influencer Marketing

Discover creators, analyze engagement, and measure campaign ROI.

- Track subscriber counts and engagement rates
- Vet influencers with channel metadata
- Discover emerging creators by niche

**Example:** Find tech creators with 50K-500K subscribers.

***

#### 🏢 Brand & Competitive Intelligence

Monitor brand mentions and track competitor activity.

- Track brand mentions in video titles/descriptions
- Monitor competitor channel growth
- Analyze sentiment via [Comments Scraper](https://apify.com/apidojo/youtube-comments-scraper?fpr=yhdrb)

**Example:** Track brand keywords vs. competitor mentions.

***

#### 🎵 Music & Entertainment

Track music trends, discover artists, and analyze audience engagement.

- Monitor music video performance
- Discover trending artists and genres
- Track viral content patterns

**Example:** Identify emerging artists for talent scouting.

***

#### 📈 SEO & Content Strategy

Research keywords, analyze rankings, and plan content.

- Analyze top-ranking videos for target keywords
- Extract video tags for keyword research
- Track trending topics for content ideation

**Example:** Analyze top 100 videos for "Python tutorial".

***

#### 🎓 Academic & Education

Collect data for media studies, cultural research, and educational content analysis.

- Build datasets for communication research
- Analyze educational playlists and courses
- Track content virality patterns

**Example:** Analyze how online learning content is structured.

### 💡 Quick Start Guide

Simple setup-whether extracting a single video or building a database of thousands.

#### Copy-Paste Examples by Persona

**For Analysts (Channel → CSV):**

```json
{
  "startUrls": ["https://www.youtube.com/@kurzgesagt"],
  "maxItems": 100
}
```

→ Run, then export to CSV from Storage tab.

**For Developers (API → JSON):**

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_TOKEN")
run = client.actor("apidojo/youtube-scraper").call(run_input={
    "keywords": ["machine learning"],
    "maxItems": 50
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

**For AI Agents (MCP pattern):**

```python
## Fetch data, then pass to LLM
youtube_data = client.dataset(run["defaultDatasetId"]).list_items().items
context = json.dumps(youtube_data[:10])  # First 10 videos as context
## Pass context to your AI agent
```

#### 3 Steps to Get Started

1. **Choose input:** URLs, handles (@username), keywords, or enable `getTrending`
2. **Configure:** Set `maxItems`, `gl` (country), `hl` (language), filters. Use `includeShorts: true` to include Shorts from channels and keyword searches.
3. **Run & Export:** Click Start, then download JSON/CSV from Storage tab

***

#### 📋 Method 1: Scrape by URL

**Best for:** Specific channels, playlists, videos

```json
{
  "startUrls": [
    "https://www.youtube.com/@kurzgesagt",
    "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"
  ],
  "maxItems": 500
}
```

***

#### 📋 Method 2: Scrape by Keywords

**Best for:** Content discovery, trend research, market analysis

```json
{
  "keywords": ["AI tutorial", "machine learning", "data science"],
  "includeShorts": true,
  "gl": "US",
  "hl": "en",
  "uploadDate": "month",
  "maxItems": 300
}
```

Set `includeShorts: true` to also pull Shorts for each keyword (one extra Shorts Query per keyword). Omit it if you only want regular search results.

***

#### 📋 Method 3: Get Trending Videos

**Best for:** Viral content discovery, trend tracking

```json
{
  "getTrending": true,
  "gl": "US",
  "maxItems": 100
}
```

***

#### 🔧 Best Practices for YouTube Scraping

##### ✅ DO:

- **Start with test runs** - Use 50-100 videos to validate output format
- **Use filters** - Narrow results with uploadDate, duration, features
- **Batch similar sources** - Combine related channels or keywords in one run
- **Set `maxItems`** - Control costs by limiting total extraction

##### ❌ DON'T:

- **Use customMapFunction for filtering** - This causes automatic blocking
- **Use date operations inside customMapFunction** - `new Date`, `Date.now` and `1970` are rejected; use the `uploadDate` input instead
- **Scrape private content** - Only public YouTube data is accessible
- **Use overly restrictive filters** - May return zero results

### ❓ Frequently Asked Questions

#### What is a YouTube Scraper API?

A tool that programmatically extracts YouTube data-videos, channels, playlists, and engagement metrics. It serves as an alternative to the official YouTube Data API without quota limits or API key requirements.

#### How much does it cost to scrape 10,000 videos?

**$5.00** total ($0.50 per 1,000 videos)-significantly cheaper than most alternatives.

#### Can I scrape YouTube comments?

This actor extracts video-level data including comment *counts*. For full comment threads, use our [YouTube Comments Scraper](https://apify.com/apidojo/youtube-comments-scraper?fpr=yhdrb).

#### Does this work for channel scraping?

Yes. Provide a channel URL or handle. Each channel query costs $0.015 and includes 30 videos FREE.

#### Can I export to CSV?

Yes. Download directly from Apify Console in JSON, CSV, or Excel format.

#### Can I use Python?

Yes. Full Python support via the Apify Client library. See the [copy-paste examples](#copy-paste-examples-by-persona) above.

#### Is this faster than the official YouTube API?

Yes. 10-19 videos/second without quota limits. The official API has strict daily quotas (10K units/day).

#### Can I scrape YouTube Shorts?

Yes. Enable `includeShorts: true` with a channel (URL or handle) **or** with `keywords`. Shorts queries cost $0.02 and include 40 videos FREE — charged once per channel or keyword. You can also pass a Shorts URL (`/shorts/ID`) or a channel `/shorts` URL directly.

#### Can I scrape YouTube Live Streams?

Yes. Enable `includeLiveStreams: true`, or pass a channel `/streams` URL directly. Live Streams queries cost $0.02 and include 40 videos FREE.

#### Can I scrape trending videos?

Yes. Enable `getTrending: true` to extract trending videos by country. Costs $0.025 with 50 videos FREE.

#### Can I use this for machine learning datasets?

Yes. Extract structured JSON with 50+ fields per video-ideal for NLP, computer vision, and trend prediction models.

### 📞 Contact

Questions or support: **apidojo10@gmail.com**

***

**Ready to start?** Transparent pricing, 10-19 videos/sec, no API key required, 7 query types. Start extracting YouTube data today. 📺

# Actor input Schema

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

YouTube URLs to scrape. Supports: Video, Channel, Playlist, Shorts, Search URLs. Required if keywords, youtubeHandles, or getTrending is not provided.

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

YouTube handles/channels to scrape (e.g., @MrBeast, @nike). Required if startUrls, keywords, or getTrending is not provided.

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

When enabled, includes YouTube Shorts from channels and search keywords. This triggers additional Shorts Query charges.

## `includeLiveStreams` (type: `boolean`):

When enabled, includes YouTube Live Streams from channels. This triggers additional Live Streams Query charges.

## `fetchLatestMetadata` (type: `boolean`):

When enabled, makes an extra request for every video to fetch its latest view and like counts and adds them to the video as latestMetadata.

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

If enabled, retrieves currently trending YouTube videos. Triggers Trending Query charge.

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

Search keywords for YouTube search. Required if startUrls, youtubeHandles, or getTrending is not provided.

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

Location for the search results, which is passed to YouTube as the gl URL query parameter. (US, AF, AL, etc...)

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

Language for the search results, which is passed to YouTube as the hl URL query parameter. (af, tr, de, etc...)

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

Upload date for the search results, which is passed to YouTube as the upload date URL query parameter. (any, hour, today, week, month, year) Only works with search keywords.

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

Duration of the video for the search results, which is passed to YouTube as the duration URL query parameter. (any, short, long)

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

Features for video. (any, 4k, hd, live, movie, cc, 3d, hdr, location, purchased, subtitles, vr180, vr360)

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

Sorts search results by the given option. Only works with search keywords.

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

Maximum total videos to output across entire run.

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

JavaScript function to transform each output video. Use to add computed fields, modify values, or remove unnecessary data. NOT intended for filtering - filtering may result in automatic bans. Must be a single synchronous function, e.g. (object) => { return {...object} }. It runs in a sandbox with plain JavaScript only (no network or require) and about 1 second per item. Leave empty if you do not need to transform the output - an unusable function is ignored and the original items are saved instead.

## `outputConnector` (type: `string`):

Pick an MCP connector you authorized in Console → Settings → API & Integrations → MCP connectors (e.g. Notion, Todoist — any service whose MCP server offers non-destructive write tools works best-effort). The scraped results are written through your own connector — the Actor never sees your third-party credentials. Only non-destructive write tools are used; it can never delete or overwrite your existing data.

## `deliverTarget` (type: `string`):

Where to write into the connector — paste the URL or ID. Notion example: https://www.notion.so/My-Posts-24f8a1b2c3d44e5f8a9b0c1d2e3f4a5b. Leave empty for services that need no target (e.g. Todoist Inbox, Slack). For Notion, share the page or database with your connector first (Notion's ••• → Connections menu), and point at a PAGE for structured columns (the Actor builds the database for you) — an empty database receives only the title (the rest of each record goes to the row's body).

## `deliverMode` (type: `string`):

perPost writes one record per scraped item; summary writes a single roll-up for the run.

## `deliverMaxItems` (type: `integer`):

Cap on how many records perPost mode writes to the connector; ignored in summary mode. Leave empty to deliver everything scraped.

## Actor input object example

```json
{
  "startUrls": [
    "https://www.youtube.com/results?search_query=never+gonna+give+you+up"
  ],
  "gl": "us",
  "hl": "en",
  "uploadDate": "all",
  "duration": "all",
  "features": "all",
  "sort": "r",
  "maxItems": 1000,
  "customMapFunction": "(object) => { return {...object} }",
  "deliverMode": "perPost"
}
```

# Actor output Schema

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

No description

# 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": [
        "https://www.youtube.com/results?search_query=never+gonna+give+you+up"
    ],
    "uploadDate": "all",
    "duration": "all",
    "features": "all",
    "sort": "r",
    "maxItems": 1000,
    "customMapFunction": (object) => { return {...object} }
};

// Run the Actor and wait for it to finish
const run = await client.actor("apidojo/youtube-scraper-api").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": ["https://www.youtube.com/results?search_query=never+gonna+give+you+up"],
    "uploadDate": "all",
    "duration": "all",
    "features": "all",
    "sort": "r",
    "maxItems": 1000,
    "customMapFunction": "(object) => { return {...object} }",
}

# Run the Actor and wait for it to finish
run = client.actor("apidojo/youtube-scraper-api").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": [
    "https://www.youtube.com/results?search_query=never+gonna+give+you+up"
  ],
  "uploadDate": "all",
  "duration": "all",
  "features": "all",
  "sort": "r",
  "maxItems": 1000,
  "customMapFunction": "(object) => { return {...object} }"
}' |
apify call apidojo/youtube-scraper-api --silent --output-dataset

```

## MCP server setup

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

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/gXSReGYeawn5nwDhI/builds/v8oOoSWCEZkHCcJeu/openapi.json