YouTube API: Search, Metadata, and Subtitles
The YouTube API gives you three focused endpoints for working with public YouTube content: search results, structured video metadata, and subtitles. Each endpoint has its own required input and returns JSON. This guide explains how to choose the right endpoint, how the search filters behave, and what to check before sending a request.
Which endpoint should you use?
Use the search endpoint when you need to discover videos, channels, playlists, or movies by a query. Use the metadata endpoint when you already have a video ID and need structured details about that video. Use the subtitles endpoint when you need caption text and can provide a video ID.
The search endpoint is the broadest entry point. It accepts a required search string and optional filters for upload date, result type, duration, sort order, HD, 4K, subtitles, Creative Commons, live streams, 360-degree video, 3D video, HDR, location metadata, VR180, and a custom tag. The metadata and subtitles endpoints are narrower: both require a video ID, and the subtitles endpoint also lets you choose a language and subtitle origin.
A practical sequence is to search first, take a videoId from the result, then call metadata or subtitles for that ID. This avoids guessing IDs and keeps each request focused.
Search quick start
The search endpoint needs two things: your API key and a search query. The query is the text you would search for on YouTube. Encode it correctly before sending the request, especially when it contains spaces or special characters.
A basic call uses the path /api/v1/youtube/search with the search parameter. The response is formatted JSON. The supplied example searches for "python tutorial" and returns a results array with video details such as title, channel, view count, duration, and thumbnails.
The documented tag parameter attaches a custom label that is returned with response headers. Per the source documentation, it does not change scraping behavior. Keep the tag short and meaningful so you can trace requests later.
Set the environment inputs used by this example, then inspect the response status and body. HTTP errors are raised before the response is printed.
import os
import requests
response = requests.get(url="{{APP_BASE_URL}}/api/v1/youtube/search", headers={"Authorization": "Bearer " + os.environ["AUTH_TOKEN"]}, params={"search": "python tutorial"})
response.raise_for_status()
print(response.status_code)
print(response.text)Search filter map
The search endpoint accepts the following optional filters. Defaults are shown where the source provides them.
- upload_date: today, last_hour, this_week, this_month, or this_year. Default is empty.
- type: video, channel, playlist, or movie. Default is empty.
- duration: <4, 4-20, or >20 minutes. Default is empty.
- sort_by: rating, relevance, view_count, or upload_date. Default is relevance.
- hd: boolean, default false.
- 4k: boolean, default false.
- subtitles: boolean, default false.
- creative_commons: boolean, default false.
- live: boolean, default false.
- 360: boolean, default false.
- 3d: boolean, default false.
- hdr: boolean, default false.
- location: boolean, default false.
- vr180: boolean, default false.
- tag: string, default empty.
Use one filter at a time when debugging. Combining filters can narrow results quickly, and a boolean filter set to true excludes videos that do not match that attribute.
Search response and retry behavior
A successful search returns JSON with a results array and the search string. Each result can include a videoId, title, channel information, view count, duration, thumbnails, and other fields. The supplied example shows a result for a Python course with a videoId, channel name, view count, and duration.
The source documentation states that each successful API call costs 5 API credits, and that a failed search is retried for up to 30 seconds. Treat both figures as documented reference from that source rather than a verified current billing or retry guarantee; confirm the applicable cost and retry window against your own account terms before relying on them. Set your own client timeout with the retry window in mind so your code does not wait indefinitely. A failed search after the retry window is different from a missing subtitle language, which the documentation describes as returning 404.
Metadata quick start
The metadata endpoint requires a video_id. You can find the video ID in a YouTube watch URL. For example, in https://www.youtube.com/watch?v=rfscVS0vtbw the video ID is rfscVS0vtbw.
The response includes structured fields such as age_limit, categories, channel_id, channel_url, comment_count, description, duration, formats, is_live, like_count, tags, thumbnails, title, upload_date, uploader, uploader_id, uploader_url, video_id, and view_count. The formats array can include resolution, format_id, format_note, fps, and codec information.
Use metadata when you need details about a known video rather than a list of search results. The tag parameter works the same way as on the search endpoint: it labels the request and is returned with response headers, without affecting scraping behavior per the source documentation.
Set the environment inputs used by this example, then inspect the response status and body. HTTP errors are raised before the response is printed.
import os
import requests
response = requests.get(url="{{APP_BASE_URL}}/api/v1/youtube/metadata", headers={"Authorization": "Bearer " + os.environ["AUTH_TOKEN"]}, params={"video_id": "rfscVS0vtbw"})
response.raise_for_status()
print(response.status_code)
print(response.text)Subtitles quick start
The subtitles endpoint requires a video_id. It returns a subtitles object with auto_generated and uploader_provided groups. Each group can contain language codes, and each language maps to an array of caption segments with start_ms, d_duration_ms, and snippet runs.
Use the language parameter with an ISO language code such as en, es, or fr. The source documentation states that if the requested language has no matching subtitles for the video, the API returns 404. Use subtitle_origin to choose auto_generated or uploader_provided subtitles. The tag parameter is also available.
According to the supplied documentation, the subtitles endpoint is not available in the CLI. Use the HTTP endpoint directly.
Set the environment inputs used by this example, then inspect the response status and body. HTTP errors are raised before the response is printed.
import os
import requests
response = requests.get(url="{{APP_BASE_URL}}/api/v1/youtube/subtitles", headers={"Authorization": "Bearer " + os.environ["AUTH_TOKEN"]}, params={"video_id": "rfscVS0vtbw"})
response.raise_for_status()
print(response.status_code)
print(response.text)Credit cost and request planning
The source documentation lists a cost of 5 credits for each YouTube API request, applied equally to the search, metadata, and subtitles endpoints. Treat that as documented reference from the source rather than a verified current price; confirm the applicable cost against your own account terms before budgeting.
A useful checklist before sending a request:
- Confirm which endpoint matches your task.
- Encode the search query if you are using search.
- Provide a video_id for metadata or subtitles.
- Choose only the filters you need.
- Set a client timeout that accounts for the documented 30-second search retry window.
- Add a tag if you need to trace requests in response headers.
For subtitle requests, check the language code and subtitle_origin before assuming a 404 means the video has no captions at all. It may mean the requested language or origin is not available.
Frequently asked questions
What is required for a YouTube search request?
The search endpoint requires a search query. You also need your API key. Encode the query correctly before sending it.
How do I find the video ID for metadata or subtitles?
The video ID is the value after v= in a YouTube watch URL. For example, in https://www.youtube.com/watch?v=rfscVS0vtbw the video ID is rfscVS0vtbw.
Why does a subtitles request return 404?
The source documentation states that if the requested language has no matching subtitles for the video, the API returns 404. Check the language code and subtitle_origin before concluding that the video has no captions.
How long does a failed search retry?
The source documentation describes a retry window of up to 30 seconds for a failed search. Treat that as documented reference rather than a verified current guarantee, and set your client timeout accordingly.
Does the tag parameter change scraping behavior?
Per the source documentation, no. The tag parameter attaches a custom identifier that is returned with response headers and does not affect scraping behavior.
curl "{{APP_BASE_URL}}/api/v1/youtube/search?search=python+tutorial" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?search=python+tutorial&upload_date=this_week" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?search=python+tutorial&type=video" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?duration=4-20&search=python+tutorial" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?search=python+tutorial&sort_by=view_count" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?hd=true&search=python+tutorial" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?4k=true&search=python+tutorial" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?search=python+tutorial&subtitles=true" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?creative_commons=true&search=python+tutorial" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?live=true&search=news" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?360=true&search=travel" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?3d=true&search=movies" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?hdr=true&search=nature" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?location=true&search=travel" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?search=experience&vr180=true" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/search?search=travel&tag=your+text" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/metadata?video_id=q0aFOxT6TNw" \
-H "Authorization: Bearer YOUR-API-KEY"
{
"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://rr2---sn-uxaoxun-5g06.googlevideo.com/videoplayback?expire=1761150421&ei=dbH4aJzOE--UobIPhoy9oQU&ip=45.180.16.126&id=o-ABFVFIXCNKj-KYiGzi8UM0jUoKea68wdVY0oF1yy_atU&itag=18&source=youtube&requiressl=yes&xpc=EgVo2aDSNQ%3D%3D&met=1761128821%2C&mh=ui&mm=31%2C29&mn=sn-uxaoxun-5g06%2Csn-pmcg-bg0e&ms=au%2Crdu&mv=m&mvi=2&pl=24&rms=au%2Cau&initcwndbps=1581250&bui=ATw7iSVFwQ05IloXmWb3urO3NdkGuQbmUL3D9E4_GwMr3sUPomySHc5SuMlIW4cZc-joJSEVwlbaAB6U&spc=hcYD5d1NGTnKpFbcSrxW1CVKCVh49E5VoeHztRiEOZa0G6qsC1VRde_hdpvBTTwmQKtpYtvN0p9ypQ&vprv=1&svpuc=1&mime=video%2Fmp4&ns=LzsfFyMMQ547ChzduDY5zMwQ&rqh=1&gir=yes&clen=71923246&ratebypass=yes&dur=3605.640&lmt=1756284595277193&mt=1761128245&fvip=15&fexp=51355912%2C51552689%2C51565115%2C51565681%2C51580968&c=WEB&sefc=1&txp=5438534&n=-0CSdvEM99hOApoLj&sparams=expire%2Cei%2Cip%2Cid%2Citag%2Csource%2Crequiressl%2Cxpc%2Cbui%2Cspc%2Cvprv%2Csvpuc%2Cmime%2Cns%2Crqh%2Cgir%2Cclen%2Cratebypass%2Cdur%2Clmt&sig=AJfQdSswRgIhAKtLBPDkeF7Hhp4sr8x6zd1vWi3snO6jESRC0o5_YmuNAiEAs4QemzwiC9iVHHpQw19xLF-6j1LqxhKi7mustUJJ8HU%3D&lsparams=met%2Cmh%2Cmm%2Cmn%2Cms%2Cmv%2Cmvi%2Cpl%2Crms%2Cinitcwndbps&lsig=APaTxxMwRQIhAKYpnf_SOE_XgVi1YGFhD9eo8fYblPTa4AtnaEICi_IhAiB5RJoEuX8pJYj9GC173Ly4Lj8-7T-Me1X8UG72AjhSTw%3D%3D",
"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": 527487,
"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=-oaymwEbCKgBEF5IVfKriqkDDggBFQAAiEIYAXABwAEG&rs=AOn4CLB_LCkuuo6Y6xeSm3jK7rDyWVLGyg",
"width": 168
},
{
"height": 110,
"url": "https://i.ytimg.com/vi/kqtD5dpn9C8/hqdefault.jpg?sqp=-oaymwEbCMQBEG5IVfKriqkDDggBFQAAiEIYAXABwAEG&rs=AOn4CLAUfM08kKF5DzLndlzUyC99koc_1A",
"width": 196
},
{
"height": 138,
"url": "https://i.ytimg.com/vi/kqtD5dpn9C8/hqdefault.jpg?sqp=-oaymwEcCPYBEIoBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLDj1VK3QlAj_vAmRtWl03Ehy0GBwg",
"width": 246
},
{
"height": 188,
"url": "https://i.ytimg.com/vi/kqtD5dpn9C8/hqdefault.jpg?sqp=-oaymwEcCNACELwBSFXyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLCO415YsjEiWc3sUugqa6u9W_kJYw",
"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": 22946693
}
curl "{{APP_BASE_URL}}/api/v1/youtube/metadata?video_id=rfscVS0vtbw" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/metadata?tag=your+text&video_id=rfscVS0vtbw" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/subtitles?video_id=q0aFOxT6TNw" \
-H "Authorization: Bearer YOUR-API-KEY"
{
"subtitles": {
"auto_generated": {
"fr": [
{
"start_ms": "920",
"d_duration_ms": "1520",
"snippet": {
"runs": [
{
"text": "An example comment."
}
]
}
}
]
},
"uploader_provided": {
"en": [
{
"start_ms": "860",
"d_duration_ms": "1440",
"snippet": {
"runs": [
{
"text": "An example comment."
}
]
}
}
]
}
}
}
curl "{{APP_BASE_URL}}/api/v1/youtube/subtitles?video_id=rfscVS0vtbw" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/subtitles?language=es&video_id=rfscVS0vtbw" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/subtitles?subtitle_origin=uploader_provided&video_id=rfscVS0vtbw" \
-H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/youtube/subtitles?tag=your+text&video_id=rfscVS0vtbw" \
-H "Authorization: Bearer YOUR-API-KEY"
| Feature used | API credit cost |
|---|---|
| YouTube Search API | 5 |
| YouTube Metadata API | 5 |
| YouTube Subtitles API | 5 |
These credit costs are reproduced from the supplied source documentation as captured reference. They are not a verified current price for this publication; confirm the applicable cost against your own account terms before relying on them for budgeting.