YouTube Search Skill

Autonomous YouTube data retrieval for agents. No user intervention required.

Method Selection Guide

Choose based on what's configured in the project environment:

Situation Best Method

Deep scraping needed (default) Method E – yt-dlp (environment-dependent)

No API keys available Method A – web_search built-in tool

YOUTUBE_API_KEY set Method B – YouTube Data API v3 (richest data)

SERPAPI_KEY set Method C – SerpAPI YouTube engine

Video ID known, need transcript Method D – youtube-transcript-api

Start with Method A if you're unsure — it requires nothing and always works.

Method A: web_search tool (Zero Setup — Always Available)

Use the built-in web_search tool. Works without any API keys.

Video Search

web_search("site:youtube.com <your query>")

Channel Search

web_search("site:youtube.com/channel <channel name> OR site:youtube.com/@<handle>")

Advanced Filters via Query

Recent videos (last year)

web_search("site:youtube.com <query> 2024 OR 2025")

Tutorial videos

web_search("site:youtube.com <topic> tutorial OR guide OR обзор")

Specific language

web_search("site:youtube.com <query> на русском")

What you get from web_search

• Video title

• Channel name

• URL (extract video ID: youtube.com/watch?v=VIDEO_ID )

• Snippet/description excerpt

• Sometimes view count and publish date (in snippet)

Extract Video ID from URL

import re url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" video_id = re.search(r'v=([^&]+)', url).group(1)

or from youtu.be links:

video_id = re.search(r'youtu.be/([^?]+)', url).group(1)

Limitation: No structured JSON, metadata is text-parsed. For richer data, use Method B.

Method B: YouTube Data API v3 (Recommended for Production)

Requires: YOUTUBE_API_KEY environment variable (free, 10,000 units/day quota).

Get key: https://console.cloud.google.com → Enable "YouTube Data API v3" → Create API key.

Search Videos

import requests, os

API_KEY = os.environ.get("YOUTUBE_API_KEY") BASE = "https://www.googleapis.com/youtube/v3"

def youtube_search(query, max_results=10, order="relevance", video_duration=None, published_after=None, lang=None): """ order: relevance | date | viewCount | rating | title video_duration: short (<4min) | medium (4-20min) | long (>20min) published_after: ISO 8601 e.g. "2024-01-01T00:00:00Z" lang: ISO 639-1 e.g. "ru", "en" """ params = { "part": "snippet", "q": query, "maxResults": max_results, "type": "video", "order": order, "key": API_KEY, } if video_duration: params["videoDuration"] = video_duration if published_after: params["publishedAfter"] = published_after if lang: params["relevanceLanguage"] = lang

r = requests.get(f"{BASE}/search", params=params)
r.raise_for_status()
items = r.json().get("items", [])

return [{
    "video_id": item["id"]["videoId"],
    "title": item["snippet"]["title"],
    "channel": item["snippet"]["channelTitle"],
    "channel_id": item["snippet"]["channelId"],
    "description": item["snippet"]["description"],
    "published_at": item["snippet"]["publishedAt"],
    "thumbnail": item["snippet"]["thumbnails"]["high"]["url"],
    "url": f"https://youtube.com/watch?v={item['id']['videoId']}"
} for item in items if item["id"].get("videoId")]

Get Video Statistics (views, likes, duration)

def get_video_stats(video_ids: list): """Pass list of video IDs, get stats back. Costs 1 quota unit per call.""" ids = ",".join(video_ids[:50]) # max 50 per request params = { "part": "statistics,contentDetails,snippet", "id": ids, "key": API_KEY, } r = requests.get(f"{BASE}/videos", params=params) r.raise_for_status()

results = []
for item in r.json().get("items", []):
    stats = item.get("statistics", {})
    content = item.get("contentDetails", {})
    results.append({
        "video_id": item["id"],
        "title": item["snippet"]["title"],
        "views": int(stats.get("viewCount", 0)),
        "likes": int(stats.get("likeCount", 0)),
        "comments": int(stats.get("commentCount", 0)),
        "duration_iso": content.get("duration"),  # e.g. "PT5M30S"
        "tags": item["snippet"].get("tags", []),
    })
return results

Parse ISO 8601 Duration

import re def parse_duration(iso_duration): """Convert PT5M30S → 330 seconds""" match = re.match(r'PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?', iso_duration) if not match: return 0 h, m, s = [int(x or 0) for x in match.groups()] return h * 3600 + m * 60 + s

Channel Search & Stats

def search_channel(channel_name, max_results=5): params = { "part": "snippet", "q": channel_name, "type": "channel", "maxResults": max_results, "key": API_KEY, } r = requests.get(f"{BASE}/search", params=params) channel_ids = [item["id"]["channelId"] for item in r.json().get("items", [])]

# Get channel stats
params2 = {"part": "statistics,snippet", "id": ",".join(channel_ids), "key": API_KEY}
r2 = requests.get(f"{BASE}/channels", params=params2)
return [{
    "channel_id": ch["id"],
    "name": ch["snippet"]["title"],
    "subscribers": int(ch["statistics"].get("subscriberCount", 0)),
    "total_views": int(ch["statistics"].get("viewCount", 0)),
    "video_count": int(ch["statistics"].get("videoCount", 0)),
    "url": f"https://youtube.com/channel/{ch['id']}"
} for ch in r2.json().get("items", [])]

Quota Costs (10,000 units/day free)

Operation Cost

search.list 100 units

videos.list (stats) 1 unit

channels.list 1 unit

playlists.list 1 unit

Tip: Search = 100 units. Get stats for 50 videos = 1 unit. Always batch videos.list calls.

Method C: SerpAPI (Structured Scraping, No Quota Issues)

Requires: SERPAPI_KEY environment variable.

Free tier: 100 searches/month. Paid plans available.

import requests, os

def serpapi_youtube_search(query, max_results=10, lang="ru"): params = { "engine": "youtube", "search_query": query, "api_key": os.environ.get("SERPAPI_KEY"), "hl": lang, # interface language } r = requests.get("https://serpapi.com/search", params=params) r.raise_for_status()

results = []
for item in r.json().get("video_results", [])[:max_results]:
    results.append({
        "title": item.get("title"),
        "video_id": item.get("id") or item.get("link", "").split("v=")[-1],
        "url": item.get("link"),
        "channel": item.get("channel", {}).get("name"),
        "views": item.get("views"),
        "duration": item.get("length"),
        "published": item.get("published_date"),
        "description": item.get("description"),
        "thumbnail": item.get("thumbnail", {}).get("static"),
    })
return results

Advantage over YouTube API: Returns views, duration, publish date directly from search — no extra API calls needed.

Method D: youtube-transcript-api (Transcripts by Video ID)

Requires: pip install youtube-transcript-api --break-system-packages

No API key needed.

from youtube_transcript_api import YouTubeTranscriptApi, TranscriptsDisabled, NoTranscriptFound

def get_transcript(video_id, languages=["ru", "en"]): """ Returns full transcript as string. languages: preference order, falls back to auto-generated. """ try: transcript_list = YouTubeTranscriptApi.list_transcripts(video_id)

    # Try preferred languages first
    try:
        transcript = transcript_list.find_transcript(languages)
    except NoTranscriptFound:
        # Fall back to any available
        transcript = transcript_list.find_generated_transcript(
            transcript_list._generated_transcripts.keys()
        )
    
    entries = transcript.fetch()
    full_text = " ".join([e["text"] for e in entries])
    return {
        "video_id": video_id,
        "language": transcript.language_code,
        "is_generated": transcript.is_generated,
        "text": full_text,
        "entries": entries  # list of {text, start, duration}
    }
except TranscriptsDisabled:
    return {"error": "Transcripts disabled for this video"}
except Exception as e:
    return {"error": str(e)}

def get_available_languages(video_id): """List all available transcript languages for a video.""" tl = YouTubeTranscriptApi.list_transcripts(video_id) return [{"code": t.language_code, "name": t.language, "generated": t.is_generated} for t in tl]

Use case: After finding video IDs via Method A or B, extract full text content for analysis, summarization, or content research.

Method E: yt-dlp (Deep Metadata + Transcripts)

Requires: pip install yt-dlp --break-system-packages

No API key. May be blocked in sandboxed environments — test first.

import yt_dlp, json

def ytdlp_search(query, max_results=10): """Search YouTube with yt-dlp. Returns rich metadata.""" ydl_opts = { "quiet": True, "no_warnings": True, "extract_flat": True, } with yt_dlp.YoutubeDL(ydl_opts) as ydl: results = ydl.extract_info(f"ytsearch{max_results}:{query}", download=False)

return [{
    "title": v.get("title"),
    "video_id": v.get("id"),
    "url": f"https://youtube.com/watch?v={v.get('id')}",
    "duration": v.get("duration"),
    "view_count": v.get("view_count"),
    "channel": v.get("channel"),
    "upload_date": v.get("upload_date"),
} for v in results.get("entries", []) if v]

def ytdlp_get_video_info(video_url): """Get full metadata for a single video.""" ydl_opts = {"quiet": True, "no_warnings": True} with yt_dlp.YoutubeDL(ydl_opts) as ydl: info = ydl.extract_info(video_url, download=False) return info

def ytdlp_get_subtitles(video_url, lang="ru"): """Download and return subtitle text.""" import tempfile, os with tempfile.TemporaryDirectory() as tmpdir: ydl_opts = { "quiet": True, "writesubtitles": True, "writeautomaticsub": True, "subtitleslangs": [lang, "en"], "skip_download": True, "outtmpl": f"{tmpdir}/%(id)s.%(ext)s", } with yt_dlp.YoutubeDL(ydl_opts) as ydl: ydl.download([video_url])

    for f in os.listdir(tmpdir):
        if f.endswith(".vtt") or f.endswith(".srt"):
            return open(os.path.join(tmpdir, f)).read()
return None

Note: yt-dlp makes direct requests to YouTube — may be blocked in restricted network environments. Always test with a quick yt-dlp --version call first.

Recommended Workflow for Automation Projects

Pattern 1: Competitor/Topic Research

1. Search for videos

results = youtube_search("AI сервисы обзор", max_results=20, order="viewCount", lang="ru")

2. Enrich with stats

video_ids = [v["video_id"] for v in results] stats = get_video_stats(video_ids)

3. Get transcripts for top videos

top_videos = sorted(stats, key=lambda x: x["views"], reverse=True)[:5] for v in top_videos: transcript = get_transcript(v["video_id"], languages=["ru"]) # analyze, summarize, extract keywords...

Pattern 2: Zero-Config Content Discovery (web_search only)

No setup required - use built-in web_search tool

web_search("site:youtube.com AI сервисы обзор 2025")

Parse results, extract video IDs, then use transcript API if needed

Pattern 3: Channel Monitoring

Find channel

channels = search_channel("название канала") channel_id = channels[0]["channel_id"]

Get latest videos from channel

params = { "part": "snippet", "channelId": channel_id, "order": "date", "maxResults": 10, "type": "video", "key": API_KEY, } r = requests.get(f"{BASE}/search", params=params)

Environment Setup Checklist

Required for Method B (YouTube Data API)

export YOUTUBE_API_KEY="AIza..."

Required for Method C (SerpAPI)

export SERPAPI_KEY="..."

Required for Methods D & E (Python libraries)

pip install youtube-transcript-api yt-dlp --break-system-packages

See Also

• references/youtube-api-quota.md — Quota optimization strategies

• references/parsing-examples.md — Real-world parsing examples for Russian-language content