YouTube Video Finder ⚡

Fast YouTube video discovery tool powered by YouTube Data API. Extract 14 essential fields with automatic bot detection bypass. 100% reliable, no proxy needed.

---

🚀 Key Features

• ⚡ 10-30x Faster with API: Automatic YouTube Data API fallback for bot detection
• 💰 Zero Cost: No proxy needed - API handles all bot detection automatically
• 📊 14 Essential Fields: Complete discovery data including thumbnails, descriptions, and engagement metrics
• 🔄 Smart Extraction: Tries Puppeteer first, falls back to API when blocked
• 🌍 Localization: Country and language support
• 📦 Bulk Processing: Text file upload or remote file links
• 🎯 Multiple Inputs: Keywords, channels, playlists, direct URLs

Best for: Video discovery, candidate selection, building watch lists, market research, and SEO analysis

---

🎯 At a Glance

Feature	Value
Speed	~2-3s per video (Puppeteer) or ~100-150ms (API)
Throughput	20-30 videos/minute (1,200-1,800/hour)
Fields	14 essential fields with 100% reliability
Bot Detection	✅ Automatic API fallback
Concurrency	5 parallel video visits

---

💡 Why This Scraper?

Traditional YouTube scrapers fail when hit by bot detection. YouTube Video Finder uses the official YouTube Data API as automatic fallback:

Metric	YouTube Video Finder	Traditional Scrapers
Bot detection handling	✅ Auto API fallback	❌ Fails or requires proxy
Time per video	~100ms-3s	~5-6s
Proxy requirement	❌ Never needed	✅ Required
Field reliability	100% (via API)	10-50%

Performance Optimizations:

• YouTube Data API integration for bot detection bypass
• Automatic fallback when CAPTCHA detected
• Multiple DOM fallbacks for Puppeteer extraction
• Resource blocking (video streams, fonts, ads)
• Optimized timeouts (8s page load, 6s data check, 15s navigation, 20s handler)

---

📋 Input Parameters

Field	Key	Type	Default	Description
Search Keywords	searchQueries	Array	[]	Search terms, topics, or channel handles (@name)
YouTube URLs	startUrls	Array<Object|string>	[]	Direct video/channel/playlist URLs. Supports file upload
Include Shorts	includeShorts	boolean	false	Include YouTube Shorts in results
Max Results	maxResultsPerQuery	integer	10	Max videos per search term/channel
Country	regionCode	string	"US"	ISO country code (US, GB, CA, AU, etc.)
Language	language	string	"en"	Language code (en, es, de, fr, etc.)
From Date	dateFrom	string	""	Filter start date (YYYY-MM-DD). Search keywords only
To Date	dateTo	string	""	Filter end date (YYYY-MM-DD). Search keywords only

Important Notes:

• 📅 Date filtering only applies to Search Keywords, not Direct URLs
• 📁 Bulk upload: Upload text file (one URL per line) or link to remote file

---

📤 Output Schema

Complete Discovery Data: 14 Essential Fields

All fields extracted via YouTube Data API with 100% reliability when bot detection occurs.

#	Field	Type	Description	Reliability
1	type	String	One of: video, shorts, live	✅ 100%
2	VideoId	String	YouTube video ID (e.g., dQw4w9WgXcQ)	✅ 100%
3	PageURL	String	Full YouTube video URL	✅ 100%
4	thumbnails	String | null	High-quality thumbnail URL (maxres/high)	✅ 100%
5	title	String	Video title	✅ 100%
6	duration	String | null	Duration in HH:MM:SS format	✅ 100%
7	viewCount	Integer | null	Total view count	✅ 100%
8	likeCount	Integer | null	Total like count	✅ 100%
9	commentCount	Integer | null	Total comment count	✅ 100%
10	description	String | null	Full video description	✅ 100%
11	publishDate	String | null	Publish date (YYYY-MM-DD)	✅ 100%
12	channelId	String | null	Channel ID (UC...)	✅ 100%
13	channelTitle	String | null	Channel name	✅ 100%
14	channelUrl	String | null	Full channel URL	✅ 100%

Why These 14 Fields?

• ✅ Complete discovery data: All key metrics for video analysis and filtering
• ✅ 100% reliable: YouTube Data API ensures all fields are populated
• ✅ Rich metadata: Includes thumbnails, descriptions, and engagement metrics
• ✅ Channel details: Full channel information with direct URL
• ✅ Perfect for analysis: Everything needed for SEO research, market analysis, and content strategy

---

📊 Output Examples

Single Video Output

{
    "type": "video",
    "VideoId": "E19_kwN0f38",
    "PageURL": "https://www.youtube.com/watch?v=E19_kwN0f38",
    "thumbnails": "https://i.ytimg.com/vi/E19_kwN0f38/maxresdefault.jpg",
    "title": "GPT-5 Codex is the best way to build apps with AI ever (5 tricks you need to know)",
    "duration": "16:39",
    "viewCount": 2176,
    "likeCount": 123,
    "commentCount": 45,
    "description": "In this video, I'll show you 5 amazing tricks to build apps faster with GPT-5 Codex...",
    "publishDate": "2025-10-09",
    "channelId": "UCfQNB91qRP_5ILeu_S_bSkg",
    "channelTitle": "Alex Finn Official",
    "channelUrl": "https://www.youtube.com/channel/UCfQNB91qRP_5ILeu_S_bSkg"
}

Multiple Videos (Batch Discovery)

[
    {
        "type": "video",
        "VideoId": "E19_kwN0f38",
        "PageURL": "https://www.youtube.com/watch?v=E19_kwN0f38",
        "thumbnails": "https://i.ytimg.com/vi/E19_kwN0f38/maxresdefault.jpg",
        "title": "GPT-5 Codex is the best way to build apps with AI ever (5 tricks you need to know)",
        "duration": "16:39",
        "viewCount": 2176,
        "likeCount": 123,
        "commentCount": 45,
        "description": "In this video, I'll show you 5 amazing tricks...",
        "publishDate": "2025-10-09",
        "channelId": "UCfQNB91qRP_5ILeu_S_bSkg",
        "channelTitle": "Alex Finn Official",
        "channelUrl": "https://www.youtube.com/channel/UCfQNB91qRP_5ILeu_S_bSkg"
    },
    {
        "type": "shorts",
        "VideoId": "7Sx0o-41r2k",
        "PageURL": "https://www.youtube.com/shorts/7Sx0o-41r2k",
        "thumbnails": "https://i.ytimg.com/vi/7Sx0o-41r2k/maxresdefault.jpg",
        "title": "Quick AI tip #shorts",
        "duration": "00:45",
        "viewCount": 15200,
        "likeCount": 892,
        "commentCount": 234,
        "description": "Quick tip for AI developers...",
        "publishDate": "2025-10-10",
        "channelId": "UCfQNB91qRP_5ILeu_S_bSkg",
        "channelTitle": "Alex Finn Official",
        "channelUrl": "https://www.youtube.com/channel/UCfQNB91qRP_5ILeu_S_bSkg"
    }
]

Performance Benefits:

• ⚡ Complete data: All 14 fields with 100% reliability via API
• ⚡ Fast: ~100-150ms per video with API, ~2-3s with Puppeteer
• ⚡ Bot-proof: Automatic API fallback when CAPTCHA detected
• ⚡ Rich metadata: Includes thumbnails, descriptions, and full engagement metrics
• ⚡ Perfect for comprehensive analysis and decision-making

---

🎬 Quick Start

Example 1: Search with Date Filter

{
    "searchQueries": ["AI tools", "machine learning", "@veritasium"],
    "maxResultsPerQuery": 20,
    "includeShorts": false,
    "dateFrom": "2025-01-01",
    "dateTo": "2025-12-31",
    "regionCode": "US",
    "language": "en"
}

Example 2: Direct Video URLs

{
    "startUrls": [
        { "url": "https://www.youtube.com/watch?v=7Sx0o-41r2k" },
        { "url": "https://www.youtube.com/watch?v=5oAnKSCP4do" }
    ],
    "maxResultsPerQuery": 10,
    "regionCode": "US",
    "language": "en"
}

Example 3: Bulk URL Upload (Remote File)

{
    "startUrls": [
        {
            "requestsFromUrl": "https://raw.githubusercontent.com/coregentdevspace/youtube-scraper-assets/main/youtube-scraper-pro-direct-url-text-file.txt"
        }
    ],
    "maxResultsPerQuery": 100
}

---

💪 Performance & Reliability

Architecture

• Concurrency: 5 parallel video page visits
• Timeouts: Optimized (8s page load, 6s data check, 15s navigation, 20s handler)
• Rate Limiting: Error-based exponential backoff (2s→4s→8s→16s→30s)
• Resource Blocking: Blocks video streams, fonts, ads for speed
• DOM Fallbacks: Multiple extraction paths for each field
• Script Parsing: Early exit optimization (max 5 scripts processed)

Smart Rate Limiting

Traditional scrapers add 3-8s artificial delays every video. YouTube Video Finder adds 0s delay when running smoothly, only backing off when errors occur.

• ✅ 0 errors: Full speed (no delays)
• ⚠️ 1-2 errors: 2-4s backoff
• ⚠️ 3-5 errors: 8-16s backoff
• ✅ 5 successes: Backoff resets to 0

Throughput Comparison

Videos	YouTube Video Finder	Traditional Scraper
10 videos	~20-30 seconds	~50-60 seconds
50 videos	~2-3 minutes	~4-5 minutes
100 videos	~4-5 minutes	~8-10 minutes
500 videos	~25 minutes	~40-50 minutes
1,000 videos	~30-50 minutes	~85 minutes

---

📚 Use Cases

• SEO Research: Analyze keywords, tags, titles, descriptions
• Content Strategy: Study successful formats, posting patterns
• Competitive Intelligence: Benchmark creators, track performance
• Market Research: Identify trends by topic, region, language
• Brand Monitoring: Find mentions and gauge engagement
• Influencer Discovery: Filter by views/engagement in your niche
• Trend Analysis: Spot emerging topics and viral patterns

---

❓ FAQ

Q: How does the YouTube API integration work? A: The scraper tries Puppeteer first for fast extraction. If YouTube blocks with CAPTCHA, it automatically falls back to the official YouTube Data API, ensuring 100% success rate with no manual intervention needed.

Q: Do I need residential proxy? A: No! Proxy is completely removed. The YouTube Data API handles all bot detection automatically, making proxy unnecessary.

Q: What about Shorts and live videos? A: Toggle includeShorts to control Shorts inclusion. Live/live-replay videos are auto-detected via type field.

Q: Can I filter by date? A: Yes! Use dateFrom and dateTo (YYYY-MM-DD). Note: Date filtering only applies to Search Keywords, not Direct URLs.

Q: Can I target a specific country/language? A: Yes! Set regionCode and language for localized search results.

Q: How do I bulk upload URLs? A: Upload a text file (one URL per line) or provide a requestsFromUrl pointing to a remote text file.

Q: What fields are included in v2.5? A: We now extract 14 complete discovery fields including thumbnails, commentCount, description, and channelUrl - everything needed for comprehensive video analysis with 100% reliability via YouTube API.

---

🛠️ Technologies & Architecture

Built with modern web scraping tools and official YouTube APIs for maximum reliability:

• Primary Extraction: Puppeteer (headless Chrome) - Full JavaScript execution
• Bot Detection Bypass: YouTube Data API v3 - Official API with automatic fallback
• Framework: Crawlee - Enterprise-grade crawling with queue management
• Runtime: Node.js 18+ - Fast async processing with native fetch API
• Data Sources: Direct parsing of YouTube's internal APIs (ytInitialData, ytInitialPlayerResponse)
• Optimization: Resource blocking (video streams, fonts, ads), parallel processing, intelligent timeouts

Why This Architecture?

• ✅ 100% success rate: API fallback ensures no failures from bot detection
• ✅ Cost-effective: No proxy costs
• ✅ Fast: Puppeteer when possible (~2-3s), API when blocked (~100ms)
• ✅ Reliable: Multiple extraction paths guarantee data availability
• ✅ Scalable: Handles high-volume scraping efficiently

---

📋 Best Practices

1. Start small: Test with maxResultsPerQuery: 10 to verify your configuration
2. Filter early: Use dateFrom/dateTo to narrow results
3. Bulk wisely: Group URLs by topic/channel for better performance
4. Export: JSON/CSV/Excel to your datastore, Google Sheets, or S3

---

📜 Changelog

v2.5.1 (Current - Production Ready - API Integration Release)

• 🔑 YouTube Data API Integration: Automatic fallback when CAPTCHA detected
• ✅ 100% Success Rate: No more bot detection failures
• 📊 14 Complete Fields: Added thumbnails, commentCount, description, channelUrl
• ❌ Proxy Removed: No longer needed - API handles all bot detection
• 🚀 Hybrid Speed: Puppeteer (~2-3s) or API (~100ms) depending on detection
• ✅ publishDate Fixed: Now populates 100% via API or microformat extraction
• 📋 Simplified Input: Removed all proxy configuration fields
• 🎯 Enhanced Output: Complete video metadata for comprehensive analysis

v2.5 (Discovery Release)

• ⚡ 2x faster extraction (~2-3s per video vs 5-6s)
• 📊 Optimized to 10 minimal discovery fields
• 🚀 79% code reduction (34KB vs 165KB)
• 💰 Zero artificial delays (error-based backoff only)
• 📅 Date range filtering for search keywords
• 📁 Bulk URL upload via text file or remote link

v2.0

• Caption tracks in output
• Richer channel fields
• Improved localization

---

🤝 Compliance

• Intended for legitimate research & business intelligence
• Collects only public YouTube data
• Respect YouTube's Terms of Service
• Users responsible for compliance with applicable laws

---

💬 Support

• Issues: Report via GitHub or Apify support
• Feature requests: Open an issue with your use case
• Documentation: See /docs folder for detailed guides

---

Built with ❤️ for performance and reliability