Giving Open WebUI a Proxy for YouTube Transcripts
Open WebUI's YouTube loader is refused from cloud IPs. Point its Youtube Proxy URL at a residential endpoint and a pasted string fixes transcript reads.
- ai-agents
- tutorials
Open WebUI reads a YouTube video's transcript when a link is attached or pasted into a chat, which is what lets the model answer questions about a video it never watched. On a datacenter deployment that fetch usually fails, and the reason is the address the request comes from, not the loader.
Open WebUI has one setting for this. It takes a proxy URL, and if you already have an endpoint, the value is a copy and paste.
Why the fetch fails from a datacenter
The transcript loader uses the youtube-transcript-api package, which requests the video's watch page and then the player endpoint behind it to read the caption track. Those requests carry no browser session, no cookies and no playback history: they are plain HTTP calls for one small resource, repeated per video.
That is enough for YouTube to decide on the origin address. Hosting and cloud ranges are treated as automated traffic, so the request is refused before anything about headers or user agent matters. A different user agent does not help, because there is no browser session to be mistaken for. The only thing that changes the answer is a different class of address.
Open WebUI names the failure in the error it returns, and points at the setting that exists for it. That is a better diagnostic than most tools give you.
What the setting covers
The field is Youtube Proxy URL, reached from the profile menu: Admin Panel > Settings > Web search, in the same section as the search provider. Its helper text reads "Proxy URL used for Youtube loader requests", and that scope is literal: it applies to transcript fetches and nothing else.
| Traffic | Which setting routes it |
|---|---|
| YouTube transcript fetch | Youtube Proxy URL |
| Web search page fetches | Trust Proxy Environment, plus http_proxy / https_proxy |
| Model inference requests | Not this field; those go to the model endpoint |
The same URL is used for the HTTP and the HTTPS leg of the transcript request, so one value is enough. There is also an environment variable, YOUTUBE_LOADER_PROXY_URL, but once you save the field in the admin panel the saved value wins.
The string Open WebUI wants
{protocol}://{username}:{password}@{host}:{port}
That is the URL format from our generator, character for character. Three details decide whether it works.
Keep the scheme. user:password@host:port is not parsed as a proxy URL, so a copy without the http:// prefix fails on the first attempt.
Leave the protocol on HTTP. The loader hands this string to Python's requests library, which speaks HTTP proxies natively and speaks SOCKS only when an extra dependency is installed. A socks5:// string is a gamble on that dependency.
Read the placeholder as a shape, not a recommendation. The field's hint shows https://user:password@host:port. That documents the string's structure; it does not ask for a TLS-terminating proxy. Our HTTP endpoint is what belongs there, and it handles the HTTPS leg of the request itself.
Generating the endpoint
- Open the product you are using, residential or mobile, and go to the Proxy tab.
- Set Protocol to HTTP.
- Choose the Proxy username this traffic should run on.
- Set Proxy format to URL, the option whose template is
{protocol}://{username}:{password}@{host}:{port}. - Set Proxies quantity to 1. One stable endpoint is what this setting needs.
- Select Check proxy on the generated row to confirm the exit IP and latency, then copy the row with Copy.
The result is one line:
http://customer-USERNAME:PASSWORD@proxy.lightningbytes.com:1080
Paste that into Youtube Proxy URL, save, and attach a video again.
Country and region targeting are optional here and rarely change whether a transcript exists. What does change the answer is Youtube Language, the field directly above the proxy: a comma-separated list of language codes tried in order, with English as the automatic final fallback.
Confirming it routes
A saved proxy string and a working proxy look identical until you read the exit address.
Check proxy in the dashboard reports the exit IP and the latency the proxy adds. Put that address into IP lookup and confirm it resolves to a consumer ISP, not a hosting provider. If it resolves to a cloud range, the problem follows the string into Open WebUI.
Then attach a video on the deployment. A transcript block in the message means the loader reached YouTube through the endpoint. A repeat of the blocked error means the request is not using your string, so check the scheme, the port, and that the field was actually saved.
Residential or mobile, but pick one and stay
The block here is about the network class rather than about session behaviour, so a residential endpoint clears it in most cases. Mobile is the fallback when residential ranges are contested too, and carrier addresses carry a different reputation, the same reasoning as in Why Mobile IPs Have High Trust.
Two habits keep this boring:
- One endpoint, dedicated. Generate a sub-user for Open WebUI alone. Rotating a credential shared with a production scraper breaks that scraper, and the failure looks unrelated to what you changed.
- Replace rather than regenerate. Open WebUI builds the proxy config without a retry on a refused exit, so one blocked address fails that request outright. Replace gives the row a new IP and re-checks it, and the string you pasted changes in exactly one place.
Each generated endpoint carries its own sticky session, so the loader keeps one address for the life of the session instead of hopping between exits midway through a video. That is the behaviour you want; the mechanics are in Sticky Sessions.
Traffic is not the constraint
A transcript is a small text body, fetched in a handful of requests per video. Against page rendering or catalogue scraping it is noise, so the constraint is that the endpoint answers, not how many bytes it carries. That is also why a single endpoint rather than a pool is the right shape here.
When it still fails
Branch on the message. The loader distinguishes an address refusal from a property of the video, and only the first one is something a proxy can fix.
| Message | Meaning | What to do |
|---|---|---|
| YouTube blocked the transcript request | The request came from an address YouTube refuses | Set the field, then confirm the exit IP is a consumer address |
| Could not retrieve a transcript | An error the loader did not classify, usually a connection or auth failure | Recheck the string: scheme, port, and any special character in the password |
| Transcripts are disabled for this video | The uploader turned captions off | Nothing; try another video |
| The video is age restricted | Captions sit behind a session | Nothing |
| The video is unavailable | Private, removed or region-locked upload | Nothing |
| YouTube requires additional verification | A verification token was demanded, not an address refusal | Change the exit once; if it persists, treat the video as gated |
| No transcript found in these languages | Captions exist, none in your list | Add languages to Youtube Language |
The top two rows are configuration. The rest are facts about the video, and no proxy setting changes them. If this class of failure is unfamiliar, Proxy Troubleshooting Checklist sets out the order to check it in.
One failure is easy to misread as a proxy fault: when a product's allocation is exhausted, its endpoints stop serving requests rather than billing over the limit, so every fetch fails at once. Traffic and Plans covers where to check the number.
Keeping the credential where it belongs
The proxy URL lives in Open WebUI's configuration, which means it is stored, visible to whoever administers the instance, and present in backups. Treat it like any other credential:
- Do not paste it into a shared document or a chat message to debug it.
- Rotate by resetting the sub-user's password and updating the one field, not by editing strings in several places.
- Give Open WebUI its own sub-user, so a leak costs one endpoint on one product.
Getting started
Add a sub-user, generate one HTTP endpoint in URL format, and paste it into Youtube Proxy URL. Check the exit IP once, attach a video, and the loader has what it needs.
Generating Proxy Endpoints covers the generator field by field, and Proxy Formats and Exports explains the two copy formats. The products are on the residential and mobile pages. For the same account driven from an editor instead of a dashboard, see Claude Code Proxy, and for YouTube work beyond transcripts, Building a YouTube Data Collector.