# Youtube Scraper (`jprime/youtube-scraper`) Actor

Alternative to the YouTube API with zero quota limits. Crawl YouTube videos and channels to extract names, views, likes, and subscriber data.

- **URL**: https://apify.com/jprime/youtube-scraper.md
- **Developed by:** [JPrime](https://apify.com/jprime) (community)
- **Categories:** Automation, Videos, Developer tools
- **Stats:** 12 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 results

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

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## YouTube Scraper

A powerful [Apify Actor](https://apify.com/actors) for scraping videos, channels, playlists, and search results from YouTube. Extract comprehensive video metadata including views, likes, channel information, and more.

### Features

- 🎥 **Multiple URL Types**: Scrape individual videos, entire channels, playlists, and search results
- 🎬 **Shorts Support**: Automatically discovers and tags YouTube Shorts from channels
- 📺 **Streams Support**: Automatically discovers and tags live streams and past streams
- 🔍 **Search Functionality**: Search YouTube by keywords and scrape the results
- 🎛️ **Advanced Search Filters**: Filter search results by type, duration, features, sort order, and upload date
- 📊 **Rich Metadata**: Extract titles, descriptions, views, likes count, upload dates, and more
- 👤 **Channel Information**: Get channel names, URLs, subscriber counts
- 🖼️ **Thumbnails**: Get high-quality video thumbnail URLs
- ⚙️ **Flexible Configuration**: Control what data to scrape and how many results to collect

### Input

The Actor accepts the following input parameters:

| Field | Type | Description | Default |
|-------|------|-------------|---------|
| `startUrls` | Array | List of YouTube URLs to scrape (videos, channels, playlists, search results) | Required |
| `searchQueries` | Array | Search queries to find videos | `[]` |
| `searchFilters` | Object | Filters to apply to search results (see Search Filters section) | `{}` |
| `maxResults` | Number | Maximum number of videos to scrape per channel/playlist/search query | `20` |
| `maxRequestsPerCrawl` | Number | Maximum number of pages to process (0 = unlimited) | `100` |
| `scrapeVideoDetails` | Boolean | Extract detailed information from each video page | `true` |
| `scrapeChannelInfo` | Boolean | Extract channel information when scraping videos | `true` |
| `proxyConfiguration` | Object | Proxy settings (recommended for YouTube) | Uses Apify Proxy |

#### Example Input

```json
{
  "startUrls": [
    { "url": "https://www.youtube.com/@lexfridman" },
    { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
    { "url": "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" }
  ],
  "searchQueries": ["web scraping tutorial", "machine learning"],
  "maxResults": 20,
  "scrapeVideoDetails": true
}
```

#### Search Filters

The Actor supports advanced search filters to refine YouTube search results. Filters can be combined to create highly targeted searches.

##### Available Filters

| Filter | Type | Options | Description |
|--------|------|---------|-------------|
| `type` | String (Single) | `videos`, `shorts`, `channels`, `playlists`, `movies` | Filter by content type |
| `duration` | String (Single) | `under3`, `3to20`, `over20` | Filter by video duration |
| `features` | Array (Multi) | `live`, `4k`, `hd`, `subtitles`, `creativeCommons`, `360`, `vr180`, `3d`, `hdr`, `location`, `purchased` | Filter by video features |
| `sortBy` | String (Single) | `relevance`, `popularity` | Sort search results |
| `uploadDate` | String (Single) | `today`, `thisWeek`, `thisMonth`, `thisYear` | Filter by upload date |

##### Important Notes

- **Upload Date Limitation**: The `uploadDate` filter is only applicable to `videos`, `shorts`, and `movies`. When an upload date is applied, YouTube automatically defaults to video type.
- **Filter Combination**: ✅ **Fully Supported!** You can now combine filters from different categories (e.g., type + duration + sortBy + uploadDate)into a single SP parameter.
- **Multi-Select Features**: ✅ **Fully Supported!** You can combine multiple features (e.g., `["hd", "4k", "subtitles"]`).

##### Example with Search Filters

```json
{
  "startUrls": [],
  "searchQueries": ["web scraping tutorial", "machine learning basics"],
  "searchFilters": {
    "type": "videos",
    "duration": "3to20",
    "features": ["hd", "subtitles"],
    "sortBy": "popularity",
    "uploadDate": "thisMonth"
  },
  "maxResults": 10,
  "scrapeVideoDetails": true
}
```

This example searches for popular videos about "web scraping tutorial" and "machine learning basics" that are:

- Between 3-20 minutes long
- In HD with subtitles
- Uploaded within the last month
- Sorted by popularity

##### Search Filter Examples

**Example 1: Recent HD Shorts**

```json
{
  "searchQueries": ["cooking recipes"],
  "searchFilters": {
    "type": "shorts",
    "features": ["hd"],
    "uploadDate": "thisWeek"
  }
}
```

**Example 2: Long-form Educational Videos**

```json
{
  "searchQueries": ["python programming"],
  "searchFilters": {
    "type": "videos",
    "duration": "over20",
    "features": ["subtitles"],
    "sortBy": "relevance"
  }
}
```

**Example 3: 4K HDR Content**

```json
{
  "searchQueries": ["nature documentary"],
  "searchFilters": {
    "type": "videos",
    "features": ["4k", "hdr"],
    "duration": "over20"
  }
}
```

### Output

The Actor outputs structured data for each video scraped:

```json
{
  "videoId": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "type": "video",
  "description": "The official video for "Never Gonna Give You Up"...",
  "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "channelId": "@RickAstleyYT",
  "channelName": "Rick Astley",
  "channelUrl": "https://www.youtube.com/@RickAstleyYT",
  "channelSubscribers": "3.5M subscribers",
  "viewCount": 1500000000,
  "likeCount": 15000000,
  "commentCount": 1200000,
  "uploadDate": "Oct 25, 2009",
  "duration": "3:33",
  "category": "Music",
  "tags": ["rick astley", "never gonna give you up", "80s music"]
}
```

### Supported URL Types

The Actor automatically detects and handles different YouTube URL types:

- **Videos**: `https://www.youtube.com/watch?v=VIDEO_ID` or `https://youtu.be/VIDEO_ID`
- **Shorts**: `https://www.youtube.com/shorts/VIDEO_ID`
- **Channels**: `https://www.youtube.com/@CHANNEL_NAME` or `https://www.youtube.com/channel/CHANNEL_ID`
- **Playlists**: `https://www.youtube.com/playlist?list=PLAYLIST_ID`
- **Search Results**: `https://www.youtube.com/results?search_query=QUERY`

### Use Cases

- **Market Research**: Analyze video trends, engagement metrics, and popular content across all content types
- **Competitor Analysis**: Monitor competitor channels and their video performance (videos, shorts, and streams)
- **Content Discovery**: Find videos on specific topics for research or curation
- **SEO Analysis**: Extract metadata and tags from successful videos
- **Data Analysis**: Build datasets for machine learning or analytics projects
- **Channel Monitoring**: Track new uploads and engagement on specific channels
- **Content Type Analysis**: Compare performance across videos, shorts, and streams
- **Stream Analysis**: Track live stream performance and archived streams

### Performance Tips

1. **Use Proxies**: YouTube may rate-limit or block requests without proxies. Enable Apify Proxy in the input.
2. **Limit Results**: Use `maxResults` to control how many videos to scrape per source.
3. **Adjust Concurrency**: The Actor uses conservative concurrency (3) to avoid blocks. This is configurable in the code.

### Notes

- The Actor respects YouTube's Terms of Service. Use responsibly and ethically.
- For production use, always use proxies to avoid IP blocks
- YouTube may show different content based on location/cookies
- Some videos may have restricted data (age-restricted, private, etc.)

# Actor input Schema

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

Search queries to find videos. Each query will search YouTube and scrape the results.

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

List of YouTube URLs to scrape. Only valid YouTube URLs are accepted. Supported formats:
• Videos: youtube.com/watch?v=..., youtube.com/shorts/..., youtu.be/...
• Channels: youtube.com/@username, youtube.com/channel/..., youtube.com/c/..., youtube.com/user/...
• Playlists: youtube.com/playlist?list=..., youtube.com/show/...
• Search: youtube.com/results?search\_query=...

Direct video/shorts URLs are scraped immediately. Channel/playlist/search URLs will discover and scrape videos based on maxResults setting.

## `searchFilters` (type: `object`):

Filters to apply to search results. Note: Upload date filter is only applicable to videos, shorts, and movies.

## `maxResults` (type: `integer`):

Maximum number of videos to scrape per channel/playlist/search query. Set to 0 for unlimited.

## `maxRequestsPerCrawl` (type: `integer`):

Maximum number of pages to process. Set to 0 for unlimited.

## `scrapeVideoDetails` (type: `boolean`):

Extract detailed information from each video page (title, description, views, likes, comments count, etc.)

## `scrapeChannelInfo` (type: `boolean`):

Extract channel information when scraping videos

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

Maximum number of pages to process concurrently. Lower values are more respectful to servers but slower.

## `maxRequestRetries` (type: `integer`):

Maximum number of times to retry a failed request

## `requestHandlerTimeoutSecs` (type: `integer`):

Timeout for processing each page in seconds. Increase if pages are timing out.

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

Proxy settings for the crawler. YouTube may block requests without proxies.

## Actor input object example

```json
{
  "searchQueries": [
    "Web Scraping"
  ],
  "searchFilters": {},
  "maxResults": 1,
  "maxRequestsPerCrawl": 100,
  "scrapeVideoDetails": true,
  "scrapeChannelInfo": true,
  "maxConcurrency": 2,
  "maxRequestRetries": 3,
  "requestHandlerTimeoutSecs": 180,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Basic video information (thumbnail, title, URL, channel, views, likes)

## `fullDetails` (type: `string`):

Complete video data including description, tags, and comments

## `datasetJSON` (type: `string`):

Download all scraped data as JSON

## `datasetCSV` (type: `string`):

Download scraped data as CSV

## `datasetExcel` (type: `string`):

Download scraped data as Excel spreadsheet

# 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 = {
    "searchQueries": [
        "Web Scraping"
    ],
    "searchFilters": {},
    "maxResults": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("jprime/youtube-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 = {
    "searchQueries": ["Web Scraping"],
    "searchFilters": {},
    "maxResults": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("jprime/youtube-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 '{
  "searchQueries": [
    "Web Scraping"
  ],
  "searchFilters": {},
  "maxResults": 1
}' |
apify call jprime/youtube-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jprime/youtube-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/9s1fCZN81iPrbfjHG/builds/6UjHY5gwsld4T7eZM/openapi.json