Use when subtitles or the spoken text of a YouTube video is needed: pasted video links or IDs, requests to translate a video, read along, follow foreign-language content, or extract what was said. Also use for language learning or accessibility. Fetches timestamped subtitles from any YouTube video.

Subtitles Fetch YouTube video subtitles 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. GET /api/v2/youtube/transcript Param Values Use case video url YouTube URL or video ID Required format json , text json for sync'd subs with timing include timestamp true , false false for clean text for reading/translation send metadata true , false Include title, channel, description For language learning — clean text without timestamps: For translation — structured segments: Response ( format=json ): Response ( format=text , include timestamp=false ): Tips Many videos have auto generated subtitles in multiple languages. Use format=json to get timing for each line (great for sync'd reading). Use include timestamp=false for clean text suitable for translation apps. 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 No subtitles No subtitles available 408 Timeout Retry once after 2s 1 credit per request. 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)