Use when the user wants to find YouTube content on any topic: searching for videos or channels, finding creators who cover a subject, discovering tutorials, talks, or expert discussions, or looking up a channel by name or handle. Also use proactively when the user wants to research a topic and YouTu

YouTube Search Search YouTube and fetch transcripts via [TranscriptAPI.com](https://transcriptapi.com). Setup If $TRANSCRIPT API KEY is not set, read [references/auth setup.md](references/auth setup.md) 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](https://transcriptapi.com/openapi.json) — consult this for the latest parameters and schemas. GET /api/v2/youtube/search — 1 credit Search YouTube globally for videos or channels. Param Required Default Validation q yes — 1 200 chars (trimmed) type no video video or channel limit no 20 1 50 Video search response: Channel search response ( type=channel ): GET /api/v2/youtube/channel/search — 1 credit Search videos within a specific channel. Accepts channel — an @handle , channel URL, or UC... ID. Param Required Validation channel yes @handle , channel URL, or UC... ID q yes 1 200 chars limit no 1 50 (default 30) 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: Workflow: Search → Transcript Errors Code Meaning Action 401 Bad API key Check key 402 No credits transcriptapi.com/billing 403/1010 Cloudflare block Add or fix User Agent header 404 Not found Resource doesn't exist 408 Timeout Retry once 422 Invalid param Check param format Free tier: 100 credits, 300 req/min. Copy paste examples Every request in this file as a ready to run one liner: [references/curl examples.md](references/curl examples.md)

youtube-search