YouTube Scraper API
A hosted API for pulling YouTube search results, per-video metadata, and subtitles as structured JSON.
This page explains what each endpoint returns, which inputs control the result, and how to tell a blocked request apart from an empty or mis-targeted one.
What the API returns
Three endpoints cover the common YouTube data tasks. The search endpoint returns videos, channels, or playlists matching a query. The metadata endpoint returns a single video's title, description, view and like counts, duration, channel details, tags, thumbnails, and available formats. The subtitles endpoint returns caption segments grouped by origin (auto-generated or uploader-provided) and by language. All three return JSON, so downstream code can read fields directly instead of parsing page markup. On the request side, the service is documented to handle proxy rotation, headless browser rendering, and anti-bot challenges, so your code only sends parameters and reads the response. Whether those request-side measures are sufficient for your target volume and geography is a question to settle with a small pilot before committing a pipeline.
Which endpoint fits your task
Use the search endpoint when you need discovery: a keyword, a channel, or a playlist list. Use the metadata endpoint when you already have a video ID and need the full record for that video. Use the subtitles endpoint when you need the spoken text, either for transcription, translation, or content analysis.
A practical rule: if your input is a query, start with search; if your input is a video ID, start with metadata or subtitles. Search results already include a videoId for each hit, so a common pipeline is search first, then metadata or subtitles per returned ID.
Search endpoint
The search endpoint takes a query string and returns matching videos, channels, or playlists. The captured example uses the query "python tutorial" with language "en" and returns a results array whose entries include videoId, title, channel name, view count, duration, thumbnails, and chapter markers.
Inputs described for this endpoint: search (the text you would type into YouTube's search bar), search_type (videos, channels, or playlists), sort_by (relevance, upload date, view count, or rating), and 4k (restrict to 4K outputs). Additional parameters are documented in the full API reference.
Metadata endpoint
The metadata endpoint takes a single video_id and returns the full record for that video. The captured example uses video_id kqtD5dpn9C8 and returns fields including title, description, duration, view_count, like_count, comment_count, upload_date, uploader, channel_id, tags, thumbnails, and a formats array with resolution and codec details.
Input described for this endpoint: video_id, the unique YouTube video identifier taken from the URL. Additional parameters are documented in the full API reference.
Subtitles endpoint
The subtitles endpoint takes a video_id plus optional language and subtitle_origin, and returns caption segments with start_ms, d_duration_ms, and snippet text. Results are grouped first by origin (auto_generated or uploader-provided) and then by language code.
Inputs described for this endpoint: video_id (the unique identifier from the URL), language (for example "en", "es", or "fr"), and subtitle_origin (auto-generated or uploader-provided). Additional parameters are documented in the full API reference.
Field and control map
The table below maps each endpoint to its documented inputs and the kind of output it produces. Use it as a quick reference before writing a request.
| Endpoint | Required input | Optional inputs | Output shape |
|---|---|---|---|
| Search | search | search_type, sort_by, 4k | results array with videoId, title, channel, views, duration |
| Metadata | video_id | (documented extras) | single object with title, description, counts, duration, tags, formats |
| Subtitles | video_id | language, subtitle_origin | subtitles object grouped by origin then language, each a list of timed segments |
This map reflects the inputs described on this page; the full documentation lists additional parameters for each endpoint.
Worked example: from search to subtitles
Suppose you want the transcript of a popular Python tutorial. First, call the search endpoint with search="python tutorial" and language="en". The captured response includes a result with videoId K5KVEU3aaeQ, title "Python Full Course for Beginners [2026]", channel "Programming with Mosh", and a view count of 3,804,720.
Next, call the metadata endpoint with video_id=K5KVEU3aaeQ to get the full record for that video. If you need the spoken text, call the subtitles endpoint with the same video_id, language="en", and subtitle_origin="auto_generated". The response returns timed segments you can feed into a transcript, a search index, or a language model.
This sequence shows the intended division of labor: search finds candidates, metadata enriches a known video, and subtitles extract the spoken content.
Telling failures apart
Three outcomes look similar but need different fixes. A blocked request usually returns an error status or a challenge page; the API's proxy and browser handling is meant to absorb this, but if it persists, check your plan's concurrency and credit limits. An empty result set with a 200 status usually means the query or filters were too narrow, or the requested search_type has no matches. A metadata or subtitles call that returns the wrong video usually means the video_id was copied incorrectly or belongs to a different URL form.
Before scaling, confirm that your video_id values come from the URL's v parameter, that language codes match the captions you expect, and that subtitle_origin matches whether the captions were auto-generated or uploaded.
Pre-scale checklist
- Confirm each endpoint's required input: search for discovery, video_id for metadata and subtitles. - Decide whether you need auto-generated or uploader-provided subtitles before requesting. - Check that your language code matches an available caption track. - Estimate request volume against your plan's YouTube API request allowance and concurrency. - Keep video_id values in a separate column so metadata and subtitle calls can be retried independently. - Log the HTTP status and a short response excerpt for each call so blocked, empty, and mis-targeted results are distinguishable later. - Before quoting any commercial terms, record the current plan prices, request and credit allowances, per-request credit cost, free-trial allowance, card requirement, support channel, cancellation terms, VAT treatment, customer count, rating, success-rate and speed figures, and data-handling statement from the operator's own published sources. - Treat testimonials and named individuals as unverified until the operator confirms them for publication.
Frequently asked questions
Is scraping YouTube legal?
Scraping YouTube can be legally complex and may conflict with YouTube's terms of service. Review the applicable terms and legal guidance for your jurisdiction and use case before running a collection pipeline, and use the API's settings responsibly.
Does YouTube block web scrapers?
YouTube uses anti-bot measures such as CAPTCHAs, IP rate limiting, and browser fingerprinting. The service is documented to handle these with rotating proxies, headless browsers, and CAPTCHA solving. How reliably that holds for your specific queries, regions, and request rates is best established with a small test batch before you scale, and any success-rate or blocking guarantee should be confirmed against the operator's current published terms.
How do I get YouTube video subtitles?
Call the subtitles endpoint with the video_id and, optionally, language and subtitle_origin. The response returns timed caption segments grouped by origin and language, ready to store or analyze.
Can I get YouTube search results?
Yes. The search endpoint returns videos, channels, or playlists for a query, with fields such as videoId, title, channel, view count, and duration. Confirm that your use case complies with YouTube's terms of service and applicable law.
What is the difference between the metadata and subtitles endpoints?
Metadata returns descriptive and statistical fields for a video, such as title, description, view count, duration, and tags. Subtitles returns the timed caption text itself, grouped by origin and language. Both take a video_id, but they answer different questions.
{
"age_limit": 0,
"categories": [
"Education"
],
"channel_id": "UCWv7vMbMWH4-V0ZXdmDpPBA",
"channel_url": "https://www.youtube.com/channel/UCWv7vMbMWH4-V0ZXdmDpPBA",
"comment_count": 26000,
"description": "Example post details.",
"duration": 3605,
"formats": [
{
"acodec": "mp4a.40.2",
"ext": "mp4",
"format_id": "18",
"format_note": "360p",
"fps": 30,
"resolution": "640x360",
"url": "https://rr4---sn-woc7knel.googlevideo.com/videoplayback?expire=1761220181&ei=9cH5aMDpKfmtvdIPpf3coAc&ip=160.242.39.18&id=o-ABJJihCcFmY05DcUZZU_t8A17taP5pTkixQgIeSEXhYF&itag=18&source=youtube&requiressl=yes&xpc=EgVo2aDSNQ%3D%3D&met=1761198581%2C&mh=ui&mm=31%2C26&mn=sn-woc7knel%2Csn-hc57en7d&ms=au%2Conr&mv=m&mvi=4&pl=22&rms=au%2Cau&initcwndbps=512500&bui=AdEuB5So6Oy2O_NyQemCTqWOM1fU6R_-mk4KKVLSJcShGUd5JYA_hLpib5Ko6cHGVfaRWa__t9NE8p81&spc=6b0G_HY_A0AEU4Bdi3jpd4JAK_ILwQpMgY7R_UuykXxWIzXpK0wwBfpABO5uSLsFaRT2t_ZP10BStg&vprv=1&svpuc=1&mime=video%2Fmp4&ns=Y4cnSxq1OuON-czOpiroTY4Q&rqh=1&gir=yes&clen=71923246&ratebypass=yes&dur=3605.640&lmt=1756284595277193&mt=1761198293&fvip=1&fexp=51355912%2C51552689%2C51565115%2C51565682%2C51580968&c=WEB&sefc=1&txp=5438534&n=-DgWoO84ndUYekNlf&sparams=expire%2Cei%2Cip%2Cid%2Citag%2Csource%2Crequiressl%2Cxpc%2Cbui%2Cspc%2Cvprv%2Csvpuc%2Cmime%2Cns%2Crqh%2Cgir%2Cclen%2Cratebypass%2Cdur%2Clmt&sig=AJfQdSswRQIgbNEydYacEJ89s89ISCKgdGxUHYc9aQuQHdF7ulG-WkkCIQDheWlzxz33j5p1EVIni2EuwkRdP-vLzRFabDbv-nQfgw%3D%3D&lsparams=met%2Cmh%2Cmm%2Cmn%2Cms%2Cmv%2Cmvi%2Cpl%2Crms%2Cinitcwndbps&lsig=APaTxxMwRAIgH7I2oSzGyMtKElvCKlgMDNCbjZhNtFpmdFSvF2uIh_kCIAaHbyRk4ti6VLyncJtAShzwDIOVsjFoJCZVH9EM6lv_",
"vcodec": "avc1.42001E"
},
{
"acodec": null,
"ext": "mp4",
"format_id": "137",
"format_note": "1080p, MISSING POT",
"fps": 30,
"resolution": "1920x1080",
"url": null,
"vcodec": "avc1.640028"
},
...
],
"is_live": false,
"like_count": 527577,
"tags": [
"code with mosh",
"introduction to python",
"learn python",
"learn python programming",
"mosh hamedani",
"programming",
"programming with mosh",
"python",
"python 2020",
"python 3",
"python basics",
"python course",
"python crash course",
"python for beginners",
"python from scratch",
"python programming",
"python tutorial",
"python tutorial for beginners",
"web development"
],
"thumbnails": [
{
"height": 94,
"url": "https://i.ytimg.com/vi/kqtD5dpn9C8/hqdefault.jpg?sqp=-oaymwEmCKgBEF5IWvKriqkDGQgBFQAAiEIYAdgBAeIBCggYEAIYBjgBQAE=&rs=AOn4CLAlw90fLox2Cpl4sR4_lYGbkEBOlA",
"width": 168
},
{
"height": 110,
"url": "https://i.ytimg.com/vi/kqtD5dpn9C8/hqdefault.jpg?sqp=-oaymwEmCMQBEG5IWvKriqkDGQgBFQAAiEIYAdgBAeIBCggYEAIYBjgBQAE=&rs=AOn4CLAgC9wqGU1HpYZsO6mtkRsaE-tzuQ",
"width": 196
},
{
"height": 138,
"url": "https://i.ytimg.com/vi/kqtD5dpn9C8/hqdefault.jpg?sqp=-oaymwEnCPYBEIoBSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLBRBdwWceylwJf5KZ3QTAmVyxHm8Q",
"width": 246
},
{
"height": 188,
"url": "https://i.ytimg.com/vi/kqtD5dpn9C8/hqdefault.jpg?sqp=-oaymwEnCNACELwBSFryq4qpAxkIARUAAIhCGAHYAQHiAQoIGBACGAY4AUAB&rs=AOn4CLBmg3x02WsuMlRV-5IBl9xeXFumyA",
"width": 336
},
{
"height": 1080,
"url": "https://i.ytimg.com/vi_webp/kqtD5dpn9C8/maxresdefault.webp",
"width": 1920
},
{
"height": 720,
"url": "https://i.ytimg.com/vi/kqtD5dpn9C8/maxresdefault.jpg",
"width": 1280
}
],
"title": "Python for Beginners - Learn Coding with Python in 1 Hour",
"upload_date": "20200916",
"uploader": "Programming with Mosh",
"uploader_id": "@programmingwithmosh",
"uploader_url": "https://www.youtube.com/@programmingwithmosh",
"video_id": "kqtD5dpn9C8",
"view_count": 22952109
}
{
"subtitles": {
"auto_generated": {
"en": [
{
"start_ms": "920",
"d_duration_ms": "1520",
"snippet": {
"runs": [
{
"text": "An example comment."
}
]
}
}
],
"fr": [
{
"start_ms": "920",
"d_duration_ms": "1520",
"snippet": {
"runs": [
{
"text": "An example comment."
}
]
}
}
]
}
}
}