YOUTUBE TRANSCRIPT API · GUIDE

How Do I Use youtube-transcript-api in Python, and Why Does It Fail on My Server?

youtube-transcript-api is a free, open-source Python library: pip install it and call fetch() with a video ID. It works well on your own computer, but on a cloud server YouTube often blocks it. We ran it from one on November 21, 2026 and got IpBlocked on both videos.

Updated November 21, 2026 · 5 min read

youtube-transcript-api is a free, open-source Python library that fetches a YouTube video's captions: pip install youtube-transcript-api, then YouTubeTranscriptApi().fetch(video_id). It works well from your own computer, but from a cloud server YouTube often blocks it with RequestBlocked or IpBlocked, and it can't help with videos that have no captions.

We ran it from a cloud machine on November 21, 2026, and then ran the same two videos through our own hosted API from the same machine. Here is what each did, how to use the library, and when a hosted API is the better fit.

What is youtube-transcript-api?

It is a Python library by Jonas Depoix, on GitHub and PyPI, under the MIT license. Version 1.2.5 is current as we write, for Python 3.8 and up.

  • It reads the captions YouTube already has, the creator's own or YouTube's automatic ones.
  • It needs no API key and no headless browser.
  • It can list a video's caption languages, prefer one language over another, and use YouTube's machine translation.
  • It formats output as text, JSON, SRT or WebVTT, and has a command line tool.

Its README is open about the trade-off: it uses an undocumented part of YouTube's web player, so there is "no guarantee that it won't stop working tomorrow".

How do I use it?

pip install youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import SRTFormatter

ytt_api = YouTubeTranscriptApi()

# English if it exists, else German
transcript = ytt_api.fetch("aircAruvnKk", languages=["en", "de"])

for snippet in transcript:
    print(snippet.start, snippet.text)

print(SRTFormatter().format_transcript(transcript))

From the command line, youtube_transcript_api aircAruvnKk --languages en --format json > transcript.json does the same. The README covers listing languages, translation and the rest.

Why does it fail with IpBlocked on my server?

Because YouTube blocks most requests from cloud providers. The library's README says it plainly: YouTube "has started blocking most IPs that are known to belong to cloud providers (like AWS, Google Cloud Platform, Azure, etc.)", so you will "most likely run into RequestBlocked or IpBlocked exceptions" once your code is deployed. A home IP can be blocked too, after too many requests.

We saw it first-hand. On November 21, 2026 we installed version 1.2.5 on a cloud machine and asked for two public lectures:

youtube-transcript-api raising IpBlocked on a cloud machine, and the same two videos returned by YouTubeTranscript.dev's API from the same machineSame machine, same two videos, November 21, 2026 (UTC).

Both calls raised IpBlocked after about 1.1 seconds. A plain request to youtube.com from that machine was redirected to Google's "unusual traffic" page, so this was YouTube refusing the machine, not a bug in the library.

The README's workaround is proxies, and it recommends rotating residential ones, because YouTube bans static proxies after extended use. That works, but it means another paid service, another account, and blocks to watch for.

What else can stop it?

  • No captions. The library reads captions; it does not transcribe audio. Captions turned off raise TranscriptsDisabled, and a missing language raises NoTranscriptFound.
  • Age-restricted videos. The README says cookie sign-in, which these need, is "currently not available" after changes on YouTube's side.
  • YouTube changes. Because it uses an undocumented interface, an update on YouTube's side can break it until a new release comes out.

None of this is a reason to avoid it for a script on your laptop. It is a reason to plan for it before you put it in a product.

What can I use instead when it's blocked?

A hosted transcript API, which does the fetching from its side. Ours is YouTubeTranscript.dev's API. From the same cloud machine, a few minutes earlier, the same two videos:

VideoLengthTimeWordsTimed linesCredits
But what is a neural network? (3Blue1Brown)18:404.2 seconds3,3572861
1. What is Computation? (MIT OpenCourseWare)43:064.2 seconds6,3638871
Same 3Blue1Brown video, asked for again18:401.3 seconds3,3572860

How we measured: one request each to POST /api/v2/transcribe with captions only and timestamps on, timed by curl from send to full response. Credits are what each response reported. One run each, so treat the times as examples.

The call from Python:

import requests

r = requests.post(
    "https://www.youtubetranscript.dev/api/v2/transcribe",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"video": "aircAruvnKk", "mode": "auto", "format": {"timestamp": True}},
)
data = r.json()["data"]
for seg in data["transcript"]["segments"]:
    print(seg["start"], seg["text"])  # start and end are in milliseconds

The trade-off is cost: the library is free, the API is 1 credit per captioned video, with 10 free credits a month and paid plans from $5 for 500. With "mode": "auto" it also transcribes videos that have no captions, at 1 credit per 2 minutes of audio. There is a Python SDK if you would rather not write the request yourself.

How do I integrate a transcription API into my product?

The same pattern works whichever API you choose:

  1. Keep the key on your server. Your users send a link to your backend; your backend calls the API. Never put the key in browser or app code.
  2. Accept any link format. Pass the link through as the user typed it; ours takes full URLs, youtu.be, Shorts, embeds and bare IDs (the full list).
  3. Store the transcript by video ID. Most products ask for the same popular videos again and again. With ours, a transcript your account already has costs nothing to fetch again, as the third row above shows, but a local copy is faster still.
  4. Treat no-caption videos as a job. Audio transcription takes longer than a web request should wait. Send mode: "auto" with a webhook_url, or poll the returned job ID, and show the user a progress state.
  5. Batch when you have many. For a playlist, channel or backlog, use the batch endpoint instead of a loop of single calls, so you stay inside your rate limit.

The API docs have every field, and our speech-to-text API guide measures accuracy and cost on audio with no captions.

Which one should I use?

If you are...Use
Running a script on your own computer, a few videos at a timeyoutube-transcript-api
Deploying to a cloud server, a serverless function or a productA hosted API, or the library plus rotating residential proxies
Handling videos with no captionsA service that transcribes audio
Fetching whole playlists or channelsA hosted API with a batch endpoint

Summary

  • youtube-transcript-api is free, MIT-licensed and easy: YouTubeTranscriptApi().fetch(video_id).
  • On a cloud server YouTube often blocks it; on our cloud machine both videos raised IpBlocked in about 1.1 seconds. The fix it suggests is proxies.
  • It only reads existing captions, and age-restricted videos are out for now.
  • A hosted API returned the same videos from the same machine in 4.2 seconds each, for 1 credit each, and handles videos with no captions.

Frequently asked questions

What is youtube-transcript-api?+

An open-source Python library (MIT license) that fetches the captions YouTube already has for a video, including automatic ones, without an API key or a browser. Install it with pip install youtube-transcript-api and call YouTubeTranscriptApi().fetch(video_id).

Why does youtube-transcript-api raise RequestBlocked or IpBlocked?+

Because YouTube blocks most requests from cloud providers' IP addresses, and can block any IP that makes too many requests. The library's README says so and suggests rotating residential proxies. From our cloud machine on November 21, 2026, both videos we tried raised IpBlocked after about 1.1 seconds.

Can youtube-transcript-api transcribe a video with no captions?+

No. It reads captions that already exist. A video with captions turned off raises TranscriptsDisabled, and one without your language raises NoTranscriptFound. To get text from audio you need a speech-to-text service.

Is youtube-transcript-api free?+

Yes, the library is free and MIT licensed. Running it on a server usually means paying for proxies, because cloud IPs are blocked.

What can I use instead of youtube-transcript-api on a server?+

A hosted transcript API that does the fetching for you. From the same machine where the library was blocked, YouTubeTranscript.dev's API returned both videos in 4.2 seconds each, for 1 credit each, and a repeat request in 1.3 seconds for free.

How do I integrate a transcription API into my product?+

Keep the API key on your server, send the video link to one endpoint, store the transcript by video ID so you never pay twice, handle videos with no captions as an async job with a webhook, and use a batch endpoint for many videos at once.

Keep reading

Start extracting transcripts for free

Convert any YouTube video to text in seconds. No credit card required.

TRY YOUTUBETRANSCRIPT.DEV →
youtube-transcript-api (Python): How to Use It, Why It Fails | Creator Research