🎬 YouTube Fast Scraper — Video Metrics & Engagement (No API Key Required)

🔗 View on Apify Store | 🇺🇸 English | 🇧🇷 Português

Extract complete YouTube video data from channels, playlists, and individual videos: views, likes, comments, duration, hashtags, thumbnails, Shorts detection, and channel info. Powered by yt-dlp with multi-proxy failover. No API key required — optional YouTube Data API v3 enrichment for accurate stats.

✨ Features

• 📺 Channels, Playlists & Videos — Scrape any YouTube URL type (channel, playlist, or single video)
• 📊 Full video metrics — Views, likes, comments count extracted from each video
• ⏱️ Duration & thumbnails — ISO 8601 duration format and high-resolution thumbnail URLs
• 🏷️ Hashtag extraction — From video tags and description text, deduplicated
• 📱 Shorts detection — Automatic identification of YouTube Shorts based on duration, URL, and aspect ratio
• 📝 Subtitle download — Optional auto-generated captions in English and Portuguese
• 🔑 Optional API enrichment — Provide a YouTube Data API v3 key for accurate likes, comments, and subscriber counts
• 🔄 Multi-proxy failover — Residential, Datacenter, Direct strategies tried automatically
• ✅ Contract validation — Every output item validated against a strict data contract before push
• 💰 Pay per result — $0.02/video

✅ Capabilities & Limits

What this actor can and cannot do, based on its real input/output schema. (Use this to avoid surprises — see the FAQ for workarounds.)

Discover / accept input by	Supported?
🔗 Channel / Playlist / Video URL (incl. @handle channel URL)	✅ Yes — via startUrls
👤 Channel handle / username	✅ Yes — as a channel URL (e.g. https://www.youtube.com/@MrBeast)
🔍 Keyword / search query (find videos by topic)	✅ Yes — via searchQuery (+ sortBy: relevance/date/views)
🏷️ Hashtag as a seed (e.g. discover videos for #shorts)	✅ Partial — pass the hashtag text as a searchQuery (e.g. "#shorts"); hashtags are also extracted from output

ℹ️ startUrls is no longer strictly required. Provide at least one of startUrls, seeds, or searchQuery. (The startUrls prefill is kept so the Apify Automated Quality Test still passes.)

Output includes: views ✅ · likes ✅ · comments count ✅ · comment text ✅ (optional — set includeComments: true; off by default) · uploader/channel ✅ · upload date (uploadDate, YYYY-MM-DD) ✅ · duration ✅ · thumbnail ✅ · hashtags (extracted from tags + description) ✅ · Shorts flag ✅ · subscriber & channel video count ✅ (only with optional API key — null otherwise)

📥 Input

One of startUrls, seeds, or searchQuery is required (not all three). If all are empty, the run fails fast with a clear error.

Parameter	Type	Required	Default	Description
startUrls	object[]	Conditional¹	—	YouTube URLs (channel, playlist, or video) to scrape
searchQuery	string	Conditional¹	—	Keyword search: find videos by topic instead of by URL. When set, it replaces startUrls/seeds.
sortBy	string (enum)	No	relevance	Order for searchQuery results: relevance, date (newest first), or views (highest first). Ignored unless searchQuery is set.
includeComments	boolean	No	false	If true, each video gets a comments[] array of { author, text, likes }. Slow — off by default.
commentsLimit	integer	No	20	Max top-level comments per video when includeComments is true (capped at 100).
maxItems	integer	No	50	Maximum number of videos to scrape (also = number of search results when searchQuery is set)
maxResults	integer	No	—	Optional alias of maxItems. If set, overrides maxItems.
seeds	string[]	Conditional¹	—	Optional alias of startUrls (plain YouTube URLs). Used when non-empty and seedType is url.
seedType	string (enum)	No	url	Type of seeds values. Only url is supported.
normalizeOutput	boolean	No	false	Add an additive _normalized block + _dataQuality flag per item.
downloadSubtitles	boolean	No	false	Extract auto-generated captions (EN, PT)
proxyConfiguration	object	No	{ "useApifyProxy": true }	Apify proxy settings. YouTube blocks datacenter IPs aggressively; residential is recommended as fallback
youtubeApiKey	string	No	—	YouTube Data API v3 key for enriched stats (likes, comments, subscribers). Read by the actor at runtime; pass it via JSON input.

¹ Conditional: provide at least one of startUrls, seeds, or searchQuery.

Input Example

{
  "startUrls": [
    { "url": "https://www.youtube.com/@MrBeast" },
    { "url": "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" },
    { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
  ],
  "maxItems": 20,
  "downloadSubtitles": false
}

Keyword search + comments example:

{
  "searchQuery": "mr beast challenge",
  "sortBy": "views",
  "maxResults": 10,
  "includeComments": true,
  "commentsLimit": 10
}

📤 Output

Every video includes these fields:

Field	Type	Description
id	string	YouTube video ID
url	string	Full video URL
title	string	Video title
description	string	Video description text
viewCount	integer	Number of views
likes	integer	Number of likes
commentsCount	integer	Number of comments
duration	string	ISO 8601 duration (e.g. PT3M12S)
durationSecs	integer	Duration in seconds
uploadDate	string	Upload date (YYYY-MM-DD)
thumbnail	string	High-resolution thumbnail URL
hashtags	string[]	Tags and hashtags from description
uploader	string	Channel/uploader name
uploaderUrl	string	Channel URL
uploaderFollowers	integer	Channel subscriber count (via API enrichment)
channelId	string	YouTube channel ID
channelVideoCount	integer	Total videos on channel (via API enrichment)
isShort	boolean	Whether the video is a YouTube Short
comments	object[]	Top-level comments { author, text, likes }, truncated to commentsLimit. Present only when includeComments is true.

Output Example

{
  "id": "fC7oUOUEEi4",
  "url": "https://www.youtube.com/watch?v=fC7oUOUEEi4",
  "title": "$456,000 Squid Game In Real Life!",
  "description": "I recreated every single game from Squid Game in real life...",
  "viewCount": 592000000,
  "likes": 18200000,
  "commentsCount": 1400000,
  "duration": "PT25M44S",
  "durationSecs": 1544,
  "uploadDate": "2021-11-24",
  "thumbnail": "https://i.ytimg.com/vi/fC7oUOUEEi4/maxresdefault.jpg",
  "hashtags": ["squidgame", "mrbeast", "challenge"],
  "uploader": "MrBeast",
  "uploaderUrl": "https://www.youtube.com/@MrBeast",
  "uploaderFollowers": 345000000,
  "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA",
  "channelVideoCount": 820,
  "isShort": false
}

📋 Use Cases

• 🎯 Content Strategy — Analyze top-performing videos to inform your content plan
• 🔍 Competitor Research — Track competitor channels, uploads, and engagement rates
• 📈 Trend Analysis — Identify trending topics and formats across channels
• 👥 Influencer Vetting — Evaluate creator metrics (subscribers, avg views, engagement)
• 🏷️ SEO & Keywords — Extract hashtags and tags used by successful videos
• 📱 Shorts vs Long-Form — Compare performance between Shorts and regular videos

❓ FAQ

Q: Do I need a YouTube Data API key? A: No. The actor works without an API key using yt-dlp data extraction. However, providing a YouTube Data API v3 key enables more accurate likes, comments, and subscriber counts via batch API calls.

Q: Does it work with private or age-restricted videos? A: No. The actor can only extract data from publicly accessible videos. Private, unlisted, or age-restricted videos will be skipped.

Q: How does Shorts detection work? A: Videos are classified as Shorts based on multiple signals: duration under 61 seconds, /shorts/ in the URL, #shorts in the title, or vertical aspect ratio (height > width).

Q: Why do some videos have null likes or comments? A: Some creators disable like counts or comments on their videos. The actor reports these as null when the data is not available from YouTube.

Q: Can I scrape entire channels? A: Yes. Provide the channel URL (e.g. https://www.youtube.com/@MrBeast) and the actor will extract videos up to the maxItems limit.

💰 Pricing

This actor uses Pay Per Event (PPE) pricing:

Metric	Cost
video-scraped	$0.03 per video

Example: Scraping 1,000 videos costs $30.00.

🔗 Related Actors

• TikTok Viral Scanner — TikTok profile & video data
• Instagram Reels Scraper — Instagram metrics
• SEO Intelligence Suite — Full website SEO audit
• Website Change Monitor — Track page changes

🆕 Available — Optional Unified / Normalized Mode

✅ The items below are live now and fully backward-compatible. If you leave the new fields unset (and normalizeOutput as false, the default), the output is byte-for-byte identical to previous versions — existing integrations are unaffected.

New optional input fields (all optional; existing inputs keep working):

Parameter	Type	Default	Description
maxResults	integer	—	Alias of maxItems (unified ViralAnalyzer vocabulary). If set, it overrides maxItems.
seeds	string[]	—	Alias of startUrls — a plain list of YouTube URLs. When non-empty and seedType is url, they are mapped into startUrls.
seedType	string (enum)	url	Type of values in seeds. This actor discovers videos only from URLs, so url is the only supported value.
normalizeOutput	boolean	false	When true, each item gets an additive _normalized block + a _dataQuality flag. When false, output is unchanged.

_normalized block (added per item when normalizeOutput: true):

"_normalized": {
  "platform": "youtube",
  "url": "https://www.youtube.com/watch?v=fC7oUOUEEi4",
  "author": "MrBeast",
  "text": "$456,000 Squid Game In Real Life!",
  "views": 592000000,
  "likes": 18200000,
  "comments": 1400000,
  "shares": null,
  "publishedAtISO": "2021-11-24T00:00:00+00:00",
  "lang": null,
  "hashtags": ["squidgame", "mrbeast", "challenge"],
  "engagementVelocity": 612.4
},
"_dataQuality": "full"

• shares is null (YouTube exposes no public share count) and lang is null (not extracted) — these are reported as null, never invented.
• publishedAtISO is an ISO-8601 UTC string derived from uploadDate.
• engagementVelocity = (likes + comments + shares) / max(hours_since_published, 1), or null when no date is available.

🔍 Keyword search (searchQuery + sortBy)

Find videos by topic instead of by URL. When searchQuery is set, it replaces startUrls/seeds, and the actor runs a YouTube keyword search returning up to maxResults/maxItems videos.

Parameter	Type	Default	Description
searchQuery	string	—	Topic / keywords to search for. When set, replaces startUrls/seeds.
sortBy	string (enum)	relevance	relevance, date (newest first), or views (highest first).

• relevance — YouTube's default relevance ranking (ytsearch).
• date — uses the date-ordered search (ytsearchdate) and re-sorts the results by uploadDate descending in the actor, because YouTube's server-side date ordering is currently unreliable.
• views — YouTube has no native sort by views, so the actor fetches the results and sorts them by viewCount descending in Python.

💬 Comment text (includeComments + commentsLimit)

Parameter	Type	Default	Description
includeComments	boolean	false	When true, attach a comments[] array per video.
commentsLimit	integer	20	Max top-level comments per video (capped at 100).

When includeComments: true, each item gets an additive comments field:

"comments": [
  { "author": "@someuser", "text": "First! Amazing video 🔥", "likes": 1240 },
  { "author": "@another",  "text": "How did you film this?",   "likes": 87 }
]

⚠️ Comment fetching is slow and adds run time. It is off by default and capped aggressively (top-level comments only, no replies, limit ≤ 100) to protect the run timeout. When includeComments is false, only commentsCount is returned and there is no extra cost.

Roadmap items now implemented: #1 unified input vocabulary, #2 normalized output block, #3 keyword search, #5 comment text, #6 ISO date + engagement velocity, #7 _dataQuality quality flag.

📝 Changelog

v1.3 (Current)

• YouTube Data API v3 enrichment for accurate likes/comments/subscribers
• Batch API calls (50 videos per request) for efficiency
• Channel statistics lookup (subscriber count, video count)
• Graceful fallback — API key optional, yt-dlp data used if no key
• PPE billing via Actor.charge()

v1.2

• Residential proxy via --proxy flag (YouTube blocks datacenter IPs)
• Multi-strategy: proxy residential, datacenter, direct
• Full video data via --dump-json (description, likes, comments, hashtags)
• YouTube Shorts detection
• Contract validation on all output items

v1.0

• Channel, playlist, and video URL scraping
• yt-dlp powered extraction
• View count, duration, thumbnail, uploader info

---

🎬 YouTube Fast Scraper — Métricas de Vídeos e Engajamento (Sem API Key)

🇺🇸 English | 🇧🇷 Português

Extraia dados completos de vídeos do YouTube de canais, playlists e vídeos individuais: visualizações, curtidas, comentários, duração, hashtags, thumbnails, detecção de Shorts e informações do canal. Alimentado por yt-dlp com failover multi-proxy. Sem necessidade de API key — enriquecimento opcional com YouTube Data API v3 para estatísticas precisas.

✨ Funcionalidades

• 📺 Canais, Playlists e Vídeos — Extraia dados de qualquer tipo de URL do YouTube (canal, playlist ou vídeo individual)
• 📊 Métricas completas — Visualizações, curtidas e contagem de comentários extraídos de cada vídeo
• ⏱️ Duração e thumbnails — Formato de duração ISO 8601 e URLs de thumbnails em alta resolução
• 🏷️ Extração de hashtags — De tags do vídeo e texto da descrição, sem duplicatas
• 📱 Detecção de Shorts — Identificação automática de YouTube Shorts baseada em duração, URL e proporção de tela
• 📝 Download de legendas — Legendas auto-geradas opcionais em inglês e português
• 🔑 Enriquecimento opcional via API — Forneça chave da YouTube Data API v3 para curtidas, comentários e inscritos precisos
• 🔄 Failover multi-proxy — Estratégias Residencial, Datacenter e Direto tentadas automaticamente
• ✅ Validação de contrato — Cada item de saída validado contra contrato de dados rigoroso antes do push
• 💰 Pague por resultado — $0.02/vídeo

✅ Capacidades e Limites

O que este actor consegue e não consegue fazer, com base no schema real de entrada/saída. (Use para evitar surpresas — veja workarounds no FAQ.)

Descobre / aceita entrada por	Suportado?
🔗 URL de canal / playlist / vídeo (incl. URL de canal com @handle)	✅ Sim — via startUrls
👤 Handle / username do canal	✅ Sim — como URL de canal (ex: https://www.youtube.com/@MrBeast)
🔍 Palavra-chave / busca (achar vídeos por tema)	✅ Sim — via searchQuery (+ sortBy: relevância/data/views)
🏷️ Hashtag como semente (ex: descobrir vídeos de #shorts)	✅ Parcial — passe o texto da hashtag como searchQuery (ex: "#shorts"); hashtags também são extraídas na saída

ℹ️ startUrls não é mais estritamente obrigatório. Forneça pelo menos um entre startUrls, seeds ou searchQuery. (O prefill de startUrls é mantido para que o Teste de Qualidade Automatizado da Apify continue passando.)

A saída inclui: visualizações ✅ · curtidas ✅ · contagem de comentários ✅ · texto dos comentários ✅ (opcional — defina includeComments: true; desligado por padrão) · uploader/canal ✅ · data de upload (uploadDate, AAAA-MM-DD) ✅ · duração ✅ · thumbnail ✅ · hashtags (extraídas de tags + descrição) ✅ · flag de Shorts ✅ · inscritos & total de vídeos do canal ✅ (somente com chave de API opcional — null caso contrário)

📥 Entrada

Um entre startUrls, seeds ou searchQuery é obrigatório (não os três). Se todos estiverem vazios, a execução falha imediatamente com um erro claro.

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
startUrls	object[]	Condicional¹	—	URLs do YouTube (canal, playlist ou vídeo) para extrair
searchQuery	string	Condicional¹	—	Busca por palavra-chave: acha vídeos por tema em vez de por URL. Quando definido, substitui startUrls/seeds.
sortBy	string (enum)	Não	relevance	Ordem dos resultados de searchQuery: relevance, date (mais recentes primeiro) ou views (mais vistos primeiro). Ignorado sem searchQuery.
includeComments	boolean	Não	false	Se true, cada vídeo ganha um array comments[] de { author, text, likes }. Lento — desligado por padrão.
commentsLimit	inteiro	Não	20	Máximo de comentários de nível superior por vídeo quando includeComments é true (limite de 100).
maxItems	inteiro	Não	50	Número máximo de vídeos para extrair (= número de resultados da busca quando searchQuery é definido)
maxResults	inteiro	Não	—	Alias opcional de maxItems. Se definido, sobrepõe maxItems.
seeds	string[]	Condicional¹	—	Alias opcional de startUrls (URLs simples do YouTube). Usado quando não-vazio e seedType for url.
seedType	string (enum)	Não	url	Tipo dos valores em seeds. Apenas url é suportado.
normalizeOutput	boolean	Não	false	Adiciona um bloco aditivo _normalized + flag _dataQuality por item.
downloadSubtitles	boolean	Não	false	Extrair legendas auto-geradas (EN, PT)
proxyConfiguration	object	Não	{ "useApifyProxy": true }	Configuração de proxy Apify. O YouTube bloqueia IPs de datacenter agressivamente; residencial é recomendado como fallback
youtubeApiKey	string	Não	—	Chave da YouTube Data API v3 para estatísticas enriquecidas (curtidas, comentários, inscritos). Lida pelo actor em runtime; passe via JSON de entrada.

¹ Condicional: forneça pelo menos um entre startUrls, seeds ou searchQuery.

Exemplo de Entrada

{
  "startUrls": [
    { "url": "https://www.youtube.com/@MrBeast" },
    { "url": "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" },
    { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
  ],
  "maxItems": 20,
  "downloadSubtitles": false
}

Exemplo de busca por palavra-chave + comentários:

{
  "searchQuery": "mr beast desafio",
  "sortBy": "views",
  "maxResults": 10,
  "includeComments": true,
  "commentsLimit": 10
}

📤 Saída

Cada vídeo inclui estes campos:

Campo	Tipo	Descrição
id	string	ID do vídeo no YouTube
url	string	URL completa do vídeo
title	string	Título do vídeo
description	string	Texto da descrição
viewCount	inteiro	Número de visualizações
likes	inteiro	Número de curtidas
commentsCount	inteiro	Número de comentários
duration	string	Duração ISO 8601 (ex: PT3M12S)
durationSecs	inteiro	Duração em segundos
uploadDate	string	Data de upload (AAAA-MM-DD)
thumbnail	string	URL da thumbnail em alta resolução
hashtags	string[]	Tags e hashtags da descrição
uploader	string	Nome do canal/uploader
uploaderUrl	string	URL do canal
uploaderFollowers	inteiro	Número de inscritos do canal (via enriquecimento API)
channelId	string	ID do canal no YouTube
channelVideoCount	inteiro	Total de vídeos no canal (via enriquecimento API)
isShort	boolean	Se o vídeo é um YouTube Short
comments	object[]	Comentários de nível superior { author, text, likes }, truncados em commentsLimit. Presente apenas quando includeComments é true.

Exemplo de Saída

{
  "id": "fC7oUOUEEi4",
  "url": "https://www.youtube.com/watch?v=fC7oUOUEEi4",
  "title": "$456,000 Squid Game In Real Life!",
  "description": "I recreated every single game from Squid Game in real life...",
  "viewCount": 592000000,
  "likes": 18200000,
  "commentsCount": 1400000,
  "duration": "PT25M44S",
  "durationSecs": 1544,
  "uploadDate": "2021-11-24",
  "thumbnail": "https://i.ytimg.com/vi/fC7oUOUEEi4/maxresdefault.jpg",
  "hashtags": ["squidgame", "mrbeast", "challenge"],
  "uploader": "MrBeast",
  "uploaderUrl": "https://www.youtube.com/@MrBeast",
  "uploaderFollowers": 345000000,
  "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA",
  "channelVideoCount": 820,
  "isShort": false
}

📋 Casos de Uso

• 🎯 Estratégia de conteúdo — Analise vídeos de melhor desempenho para planejar seu conteúdo
• 🔍 Pesquisa de concorrentes — Acompanhe canais, uploads e taxas de engajamento dos concorrentes
• 📈 Análise de tendências — Identifique tópicos e formatos em alta entre canais
• 👥 Avaliação de influenciadores — Avalie métricas de criadores (inscritos, média de views, engajamento)
• 🏷️ SEO e palavras-chave — Extraia hashtags e tags usadas por vídeos de sucesso
• 📱 Shorts vs longa duração — Compare performance entre Shorts e vídeos regulares

❓ Perguntas Frequentes

P: Preciso de uma chave da YouTube Data API? R: Não. O actor funciona sem chave de API usando extração de dados via yt-dlp. Porém, fornecer uma chave da YouTube Data API v3 permite curtidas, comentários e contagem de inscritos mais precisos através de chamadas em lote.

P: Funciona com vídeos privados ou com restrição de idade? R: Não. O actor só consegue extrair dados de vídeos acessíveis publicamente. Vídeos privados, não listados ou com restrição de idade serão ignorados.

P: Como funciona a detecção de Shorts? R: Vídeos são classificados como Shorts com base em múltiplos sinais: duração abaixo de 61 segundos, /shorts/ na URL, #shorts no título ou proporção vertical (altura > largura).

P: Por que alguns vídeos têm curtidas ou comentários nulos? R: Alguns criadores desabilitam contagem de curtidas ou comentários em seus vídeos. O actor reporta esses valores como null quando os dados não estão disponíveis no YouTube.

P: Posso extrair canais inteiros? R: Sim. Forneça a URL do canal (ex: https://www.youtube.com/@MrBeast) e o actor extrairá vídeos até o limite definido em maxItems.

💰 Preços

Este actor usa precificação Pay Per Event (PPE):

Métrica	Custo
Por vídeo extraído	$0.02

Exemplo: Extrair 100 vídeos custa $2.00.

🔗 Actors Relacionados

• TikTok Viral Scanner — Dados de perfis e vídeos do TikTok
• Instagram Reels Scraper — Métricas do Instagram
• SEO Intelligence Suite — Auditoria SEO completa
• Website Change Monitor — Monitoramento de mudanças

🆕 Disponível — Modo Unificado / Normalizado (opcional)

✅ Os itens abaixo já estão ativos e são totalmente retrocompatíveis. Se você deixar os novos campos sem preencher (e normalizeOutput como false, o padrão), a saída é byte a byte idêntica às versões anteriores — integrações existentes não são afetadas.

Novos campos de entrada opcionais (todos opcionais; as entradas existentes continuam funcionando):

Parâmetro	Tipo	Padrão	Descrição
maxResults	inteiro	—	Alias de maxItems (vocabulário unificado ViralAnalyzer). Se definido, sobrepõe maxItems.
seeds	string[]	—	Alias de startUrls — uma lista simples de URLs do YouTube. Quando não-vazia e seedType for url, são mapeadas para startUrls.
seedType	string (enum)	url	Tipo dos valores em seeds. Este actor descobre vídeos apenas por URL, então url é o único valor suportado.
normalizeOutput	boolean	false	Quando true, cada item ganha um bloco aditivo _normalized + uma flag _dataQuality. Quando false, a saída é inalterada.

Bloco _normalized (adicionado por item quando normalizeOutput: true):

"_normalized": {
  "platform": "youtube",
  "url": "https://www.youtube.com/watch?v=fC7oUOUEEi4",
  "author": "MrBeast",
  "text": "$456,000 Squid Game In Real Life!",
  "views": 592000000,
  "likes": 18200000,
  "comments": 1400000,
  "shares": null,
  "publishedAtISO": "2021-11-24T00:00:00+00:00",
  "lang": null,
  "hashtags": ["squidgame", "mrbeast", "challenge"],
  "engagementVelocity": 612.4
},
"_dataQuality": "full"

• shares é null (o YouTube não expõe contagem pública de compartilhamentos) e lang é null (não extraído) — reportados como null, nunca inventados.
• publishedAtISO é uma string ISO-8601 em UTC derivada de uploadDate.
• engagementVelocity = (likes + comments + shares) / max(horas_desde_publicação, 1), ou null quando não há data disponível.

🔍 Busca por palavra-chave (searchQuery + sortBy)

Acha vídeos por tema em vez de por URL. Quando searchQuery é definido, ele substitui startUrls/seeds, e o actor roda uma busca por palavra-chave no YouTube retornando até maxResults/maxItems vídeos.

Parâmetro	Tipo	Padrão	Descrição
searchQuery	string	—	Tema / palavras-chave a buscar. Quando definido, substitui startUrls/seeds.
sortBy	string (enum)	relevance	relevance, date (mais recentes primeiro) ou views (mais vistos primeiro).

• relevance — ranking de relevância padrão do YouTube (ytsearch).
• date — usa a busca ordenada por data (ytsearchdate) e reordena os resultados por uploadDate decrescente no actor, porque a ordenação por data do lado do YouTube está atualmente instável.
• views — o YouTube não tem ordenação nativa por views, então o actor busca os resultados e os ordena por viewCount decrescente em Python.

💬 Texto dos comentários (includeComments + commentsLimit)

Parâmetro	Tipo	Padrão	Descrição
includeComments	boolean	false	Quando true, anexa um array comments[] por vídeo.
commentsLimit	inteiro	20	Máximo de comentários de nível superior por vídeo (limite de 100).

Quando includeComments: true, cada item ganha um campo aditivo comments:

"comments": [
  { "author": "@someuser", "text": "Primeiro! Vídeo incrível 🔥", "likes": 1240 },
  { "author": "@another",  "text": "Como você filmou isso?",      "likes": 87 }
]

⚠️ A coleta de comentários é lenta e aumenta o tempo de execução. Vem desligada por padrão e é limitada agressivamente (apenas comentários de nível superior, sem respostas, limite ≤ 100) para proteger o timeout da execução. Quando includeComments é false, apenas commentsCount é retornado e não há custo extra.

Itens do roadmap agora implementados: #1 vocabulário de entrada unificado, #2 bloco de saída normalizado, #3 busca por palavra-chave, #5 texto dos comentários, #6 data ISO + velocidade de engajamento, #7 flag de qualidade _dataQuality.

📝 Changelog

v1.3 (Atual)

• Enriquecimento via YouTube Data API v3 para curtidas/comentários/inscritos precisos
• Chamadas API em lote (50 vídeos por requisição) para eficiência
• Consulta de estatísticas do canal (contagem de inscritos e vídeos)
• Fallback gracioso — chave de API opcional, dados do yt-dlp usados se sem chave
• Cobrança PPE via Actor.charge()

v1.2

• Proxy residencial via flag --proxy (YouTube bloqueia IPs de datacenter)
• Multi-estratégia: proxy residencial, datacenter, direto
• Dados completos de vídeo via --dump-json (descrição, curtidas, comentários, hashtags)
• Detecção de YouTube Shorts
• Validação de contrato em todos os itens de saída

v1.0

• Extração de URLs de canal, playlist e vídeo
• Extração alimentada por yt-dlp
• Contagem de views, duração, thumbnail, info do uploader