YouTube Data

Retrieve data from the YouTube Data API v3. Supports searching videos, fetching video/channel details, reading transcripts and comments, and discovering trending or related content.

Core principle: Data retrieval only — this skill fetches and returns structured data. It does not produce written content or visual assets.

When to Use

Search YouTube for videos matching a query or criteria
Get detailed statistics for a specific video or channel
Fetch video transcripts/captions for analysis
Read and analyze video comments
Find videos related to a specific video
Discover trending videos by region
Extract enhanced transcripts with time filtering, search, and segmentation

Prerequisites

YOUTUBE_API_KEY — Set in environment or ~/.claude/.env. Get from Google Cloud Console
uv (recommended) or Python 3.10+ with dependencies installed

With uv (recommended — zero setup): Dependencies are declared inline via PEP 723 and auto-installed on first run. Just use uv run.

With pip (fallback):

pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

Quick Start

Search for videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py search "python tutorial" --max-results 5

Get video details:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py video "dQw4w9WgXcQ"

Get transcript:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py transcript "dQw4w9WgXcQ" --language en

Get channel info:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py channel "UC_x5XG1OV2P6uZZ5FSM9Ttw"

Get comments:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py comments "dQw4w9WgXcQ" --max-results 10 --include-replies

Find related videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py related "dQw4w9WgXcQ" --max-results 5

Get trending videos:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py trending --region US --max-results 10

Enhanced multi-video transcript:

uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py enhanced-transcript "vid1" "vid2" \
  --format merged --include-metadata --language en

Script Reference

`scripts/youtube_api.py`

Self-contained YouTube Data API script with 8 subcommands.

Subcommands

Subcommand	Description
`search`	Search for YouTube videos with advanced filtering
`video`	Get detailed information about a video
`channel`	Get detailed information about a channel
`comments`	Get comments for a video
`transcript`	Get transcript/captions for a video
`related`	Get videos related to a specific video
`trending`	Get trending videos by region
`enhanced-transcript`	Advanced multi-video transcript with filtering

`search`

youtube_api.py search QUERY [OPTIONS]

Arguments:
  QUERY                          Search query string

Options:
  --max-results N                Number of results (default: 10, max: 50)
  --channel-id ID                Filter by channel
  --order ORDER                  Sort: date, rating, viewCount, relevance, title
  --duration DURATION            Filter: short (<4min), medium (4-20min), long (>20min)
  --published-after DATE         ISO date filter (e.g. 2024-01-01T00:00:00Z)
  --published-before DATE        ISO date filter
  --region CODE                  ISO country code (e.g. US, GB, JP)

`video`

youtube_api.py video VIDEO_ID

Returns: title, description, publish date, channel, tags, view/like/comment counts, duration, thumbnails.

`channel`

youtube_api.py channel CHANNEL_ID

Returns: title, description, subscriber/video/view counts, custom URL, thumbnails.

`comments`

youtube_api.py comments VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of comments (default: 20)
  --order ORDER                  Sort: relevance (default) or time
  --include-replies              Include reply threads
  --page-token TOKEN             Pagination token

`transcript`

youtube_api.py transcript VIDEO_ID [OPTIONS]

Options:
  --language CODE                Language code (e.g. en, ko, fr)

Returns: timestamped segments and full text with timestamps.

`related`

youtube_api.py related VIDEO_ID [OPTIONS]

Options:
  --max-results N                Number of results (default: 10)

`trending`

youtube_api.py trending [OPTIONS]

Options:
  --region CODE                  ISO country code (default: US)
  --max-results N                Number of results (default: 5)

`enhanced-transcript`

youtube_api.py enhanced-transcript VIDEO_ID [VIDEO_ID...] [OPTIONS]

Arguments:
  VIDEO_IDS                      One or more video IDs (max 5)

Options:
  --language CODE                Language code
  --format FORMAT                Output: raw, timestamped (default), merged
  --start-time SECONDS           Filter from this time
  --end-time SECONDS             Filter until this time
  --search QUERY                 Search within transcript text
  --case-sensitive               Case-sensitive search
  --segment-method METHOD        Segmentation: equal (default), smart
  --segment-count N              Number of segments (default: 1)
  --include-metadata             Include video details with transcript

Return Structure

All subcommands output JSON to stdout with this consistent structure:

{
  "success": true,
  "data": { ... },
  "error": null,
  "metadata": {
    "timestamp": "2025-01-26T12:00:00",
    ...
  }
}

On failure, success is false, data is null, and error contains the message. Exit code is 0 on success, 1 on failure.

Python API

Direct import (from another skill's script):

import sys
from pathlib import Path
sys.path.insert(0, str(Path("${CLAUDE_SKILL_DIR}/scripts")))
from youtube_api import search_videos, get_video_details, get_video_transcript

# Search videos
result = search_videos("python tutorial", max_results=5)

# Get video details
result = get_video_details("dQw4w9WgXcQ")

# Get transcript
result = get_video_transcript("dQw4w9WgXcQ", language="en")

Available functions:

Function	Description
`search_videos(query, ...)`	Search YouTube videos
`get_video_details(video_id)`	Get video details
`get_channel_details(channel_id)`	Get channel details
`get_video_comments(video_id, ...)`	Get video comments
`get_video_transcript(video_id, ...)`	Get video transcript
`get_related_videos(video_id, ...)`	Get related videos
`get_trending_videos(region, ...)`	Get trending videos
`get_enhanced_transcript(video_ids, ...)`	Enhanced multi-video transcript

All functions return the same {success, data, error, metadata} dict.

Downstream Skill Integration

Pattern 1: CLI wrapper (recommended for agents)

result=$(uv run ${CLAUDE_SKILL_DIR}/scripts/youtube_api.py search "AI tutorials" --max-results 5)
echo "$result" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['data']['items'][0]['title'])"

Pattern 2: Python import with custom defaults

# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "google-api-python-client>=2.169.0",
#     "youtube-transcript-api>=1.0.3",
#     "python-dotenv>=1.1.0",
# ]
# ///

import sys
from pathlib import Path
sys.path.insert(0, str(Path("${CLAUDE_SKILL_DIR}/scripts")))
from youtube_api import search_videos, get_video_transcript

def research_topic(topic: str, count: int = 10) -> list:
    """Search and get transcripts for top videos on a topic."""
    search_result = search_videos(topic, max_results=count)
    if not search_result["success"]:
        return []
    videos = search_result["data"]["items"]
    for v in videos:
        t = get_video_transcript(v["videoId"], language="en")
        v["transcript"] = t["data"]["text"] if t["success"] else None
    return videos

Environment Variables

Variable	Description	Default
`YOUTUBE_API_KEY`	YouTube Data API v3 key	Required

Troubleshooting

"uv: command not found"

Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv

"Required packages not installed"

Use uv run instead of python3 to auto-install dependencies
Or install manually: pip install -r ${CLAUDE_SKILL_DIR}/requirements.txt

"YOUTUBE_API_KEY environment variable not set"

Set YOUTUBE_API_KEY in your shell, ~/.claude/.env, or local .env

"HttpError 403: quotaExceeded"

YouTube Data API has a daily quota (default 10,000 units)
Wait until quota resets or request a quota increase
The script retries rate-limited requests automatically (3 attempts with exponential backoff)

"No transcript available"

Video may not have captions enabled
Try a different --language code
Auto-generated captions may be available in other languages

References

references/youtube-data-api.md — YouTube Data API v3 endpoints, quotas, and response structures

youtube-data