Youtube Search

YouTube Search

Search YouTube and fetch transcripts via TranscriptAPI.com.

Setup

If $TRANSCRIPT_API_KEY is not set, read references/auth-setup.md [blocked] and follow the instructions there to get and store the key.

Required Headers

Every request needs two headers:

• Authorization: Bearer $TRANSCRIPT_API_KEY
• User-Agent: your agent's name and version if known (e.g. HermesAgent/0.11.0, ClaudeCode/1.0). Version is optional — agent name alone is fine. Do not omit this header or send a bare default — Cloudflare will return a 403 (error code 1010) and block the request.

API Reference

Full OpenAPI spec: transcriptapi.com/openapi.json — consult this for the latest parameters and schemas.

GET /api/v2/youtube/search — 1 credit/page

Search YouTube globally for videos, channels, playlists, or movies.

curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20" \  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \  -H "User-Agent: YourAgent/1.0"

Provide exactly one of q (first page) or continuation (next pages) — the token already encodes the filters. sort/upload_date/duration/features apply to the first page only.

Find recent, most-viewed videos:

curl -s "https://transcriptapi.com/api/v2/youtube/search\?q=innovation&sort=views&duration=long&upload_date=month" \  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \  -H "User-Agent: YourAgent/1.0"

Search for playlists on a topic:

curl -s "https://transcriptapi.com/api/v2/youtube/search?q=react+tutorial&type=playlist" \  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \  -H "User-Agent: YourAgent/1.0"

Video search response:

{  "results": [    {      "type": "video",      "videoId": "dQw4w9WgXcQ",      "title": "Rick Astley - Never Gonna Give You Up",      "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",      "channelTitle": "Rick Astley",      "channelHandle": "@RickAstley",      "channelVerified": true,      "lengthText": "3:33",      "viewCountText": "1.5B views",      "publishedTimeText": "14 years ago",      "hasCaptions": true,      "thumbnails": [{ "url": "...", "width": 120, "height": 90 }]    }  ],  "result_count": 20}

Channel search response (type=channel):

{  "results": [{    "type": "channel",    "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",    "title": "Rick Astley",    "handle": "@RickAstley",    "url": "https://www.youtube.com/@RickAstley",    "description": "Official channel...",    "subscriberCount": "4.2M subscribers",    "verified": true,    "rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UC...",    "thumbnails": [...]  }],  "result_count": 5}

GET /api/v2/youtube/channel/search — 1 credit

Search videos within a specific channel. Accepts channel — an @handle, channel URL, or UC... ID.

curl -s "https://transcriptapi.com/api/v2/youtube/channel/search\?channel=@TED&q=climate+change&limit=30" \  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \  -H "User-Agent: YourAgent/1.0"

Returns up to ~30 results (YouTube limit). Same video response shape as global search.

GET /api/v2/youtube/channel/resolve — FREE

Convert @handle to channel ID:

curl -s "https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED" \  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \  -H "User-Agent: YourAgent/1.0"

Workflow: Search → Transcript

# 1. Search for videoscurl -s "https://transcriptapi.com/api/v2/youtube/search\?q=python+web+scraping&type=video&limit=5" \  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \  -H "User-Agent: YourAgent/1.0"
# 2. Get transcript from resultcurl -s "https://transcriptapi.com/api/v2/youtube/transcript\?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true" \  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" \  -H "User-Agent: YourAgent/1.0"

Errors

Free tier: 100 credits, 300 req/min.