YouTube Search API
The FetchTranscript YouTube Search API runs a YouTube search for your query and returns the matching videos as JSON: video ID, title, description snippet, channel name and ID, duration in seconds, view count and thumbnail URL, up to 50 results per call. It is the starting point for anything that begins with “find videos about…”, and every video ID it returns plugs straight into the transcript, comments and metadata endpoints of the same API.
No credit card needed. One API key works on every endpoint.
Quick example
/v1/search?q={query}&limit=10Put the search terms in q and authenticate with your key in the X-API-Key header. With cURL, --data-urlencode takes care of the spaces; the SDKs encode the query for you.
curl -G "https://api.fetchtranscript.com/v1/search" \
--data-urlencode "q=how to make sourdough bread" \
-d limit=20 \
-H "X-API-Key: yt_your_api_key"Sample response
The response to the same query with limit=2. Results come in the order YouTube ranks them for the query.
{
"query": "how to make sourdough bread",
"results": [
{
"video_id": "4gEoh3sk2AE",
"title": "Bake the Perfect Sourdough Bread: A Step-by-Step Guide",
"description": "Learn how to bake sourdough bread with the perfect rise, ear, and texture—just like you've always dreamed of! This step-by-step ...",
"channel_name": "Natashas Kitchen",
"channel_id": "UC-pC1xsFPzcrL09DaW4jlBA",
"duration": 713,
"view_count": 3540512,
"thumbnail_url": "https://i.ytimg.com/vi/4gEoh3sk2AE/hq720.jpg",
"upload_date": null
},
{
"video_id": "CTuGXdyrWUo",
"title": "The BEST Beginner Sourdough Bread Tutorial on YouTube",
"description": "If you're looking for the best beginner sourdough bread recipe, you have found it. I've been making a variation of this ...",
"channel_name": "Grant Bakes",
"channel_id": "UC8c1ioTr-GoXoB7p5JydYkg",
"duration": 721,
"view_count": 1131928,
"thumbnail_url": "https://i.ytimg.com/vi/CTuGXdyrWUo/hq720.jpg",
"upload_date": null
}
],
"total_results": 2
}Illustrative values: a real response carries the live data of the video or channel you ask for.
| Field | Type | Description |
|---|---|---|
| query | string | The query you sent, as received. |
| results | array | The videos YouTube returns for the query, in YouTube’s own order. |
| results[].video_id | string | The 11-character video ID, ready for the transcript, comments and metadata endpoints. |
| results[].title | string | The video title. |
| results[].description | string | null | The description snippet shown in search results, usually cut short with “...”. |
| results[].channel_name | string | null | The name of the channel that published the video. |
| results[].channel_id | string | null | The channel ID (UC…), usable with the channel endpoints. |
| results[].duration | integer | null | Length in seconds; null when YouTube shows none, for example on a live stream. |
| results[].view_count | integer | null | Views as shown in the results. |
| results[].thumbnail_url | string | null | URL of the video thumbnail. |
| results[].upload_date | string | null | Upload date (YYYYMMDD) when search results include it, which is rare: call the video metadata endpoint when you need the date. |
| total_results | integer | null | How many results this response contains. |
Parameters
| Parameter | In | Type | Default | Description |
|---|---|---|---|---|
| q | query | string | required | What to search for, 1 to 500 characters, the same words you would type in YouTube’s search box. URL-encode spaces and symbols. |
| limit | query | integer | 10 | Maximum number of results, from 1 to 50. |
A missing or empty q, or a limit outside 1 to 50, is refused with a 422 validation error. Authentication errors are 401 missing_api_key or invalid_api_key, an empty balance is 402 insufficient_credits, and 503 service_unavailable means the search could not run: retry after a moment. Searches are always live, never served from a cache.
Search, then read the transcripts
The most common pattern is a two-step pipeline: search to collect candidate videos, then fetch what you need for each one. The Python SDK’s find_videos_with_transcripts helper does the first half and also tells you which results have captions, and in which languages, so you only request transcripts that exist.
from fetchtranscript import FetchTranscriptClient
client = FetchTranscriptClient(api_key="yt_your_api_key")
# 1 search call + 1 language check per result
videos = client.search.find_videos_with_transcripts("sourdough starter not rising", limit=5)
for video in videos:
if any(code.startswith("en") for code in video["available_languages"]):
text = client.transcripts.get_text(video["video_id"], lang="en") # 1 call each
print(video["title"], "-", len(text.split()), "words")This example costs at most 11 calls: one search, five language checks and up to five transcripts. Videos without captions are skipped before any transcript is requested, and a request that fails is not billed anyway.
Use cases
Content discovery in your app
Let users search YouTube from inside your product and show results with thumbnails, durations and view counts, without sending them to another site first.
Research pipelines
Turn a research question into a set of videos, then pull their transcripts, comments and metadata for analysis: lectures on a topic, product reviews, interviews with an expert.
AI agents and RAG
Give an agent a tool to find the videos that answer a question, read their transcripts and cite the video it learned from. Search plus transcript is a complete YouTube research loop.
Keyword research for creators
See which videos rank for a query, how long they are and how many views they have, before you plan, title and script your own video on the same topic.
Trend monitoring
Run the same queries every day and store the results: new video IDs show you what was published on a subject, and view counts show what is taking off.
Dataset building
Collect topic corpora by running many related queries and de-duplicating by video ID, then download the transcripts to build training or evaluation data.
Search and the official YouTube Data API
Google’s YouTube Data API searches with its search.list method. According to Google’s quota cost table, search.list has its own quota bucket with a default limit of 100 calls per day per project, and each request for an additional page of results counts as another call.
FetchTranscript has no daily cap on searches: you pay one credit per successful search and can send up to 500 requests per minute. That suits pipelines and agents that run many queries in a burst.
Pricing
One search returns up to 50 videos and costs one credit. Fetching the transcript or the metadata of a result is one more credit each.
- 25 free calls every month, no credit card
- Then $1 per 1,000 calls, pay as you go
- Only successful calls are billed: errors cost nothing
- Credits never expire; bulk packs from 10,000 calls for $9
Also in the MCP server for AI assistants
The FetchTranscript MCP server gives Claude, Cursor and other MCP clients the same data as tools: search_videos, get_transcript and list_languages. An assistant can answer “find me a good talk on vector databases and summarize it” by calling search_videos, picking a result and reading it with get_transcript.
Run it with uvx fetchtranscript-mcp and your API key in FETCHTRANSCRIPT_API_KEY; the MCP server guide has the configuration for each client. Tool calls are billed like API calls.
YouTube Search API: frequently asked questions
- Do I need a YouTube Data API key to search YouTube?
- No. FetchTranscript runs the search for you: send your FetchTranscript API key in the X-API-Key header and the query in the q parameter. There is no Google Cloud project or OAuth to set up.
- How many results can one search return?
- Up to 50, set with the limit parameter (10 by default). There is no offset parameter, so a query gives you its top results only; total_results is the number of results in the response.
- Does the search return channels or playlists?
- No, it returns videos. Each result carries the channel ID, so you can look up the channel with the channel endpoints afterwards.
- Can I filter results by upload date, duration or language?
- There are no filter parameters: the endpoint takes a query and a limit. Each result includes the duration in seconds and the view count, so you can filter or sort them in your code.
- How do I get the transcripts of the videos I find?
- Pass each video_id to GET /v1/transcripts/{video_id}. The Python SDK also has find_videos_with_transcripts, which searches and checks which results have captions in one step, at the cost of one call per result checked.
- How much does a YouTube search cost?
- One credit per search, whether it returns 5 results or 50. Every account gets 25 free calls per month, then it is $1 per 1,000 calls; failed calls are free.
Related APIs
- YouTube Transcript APIThe full transcript of a video as timed JSON, plain text or SRT.
- YouTube Comments APIUp to 500 comments of a video as JSON, with author, likes, date and pinned flag.
- YouTube Channel APIA channel’s details by @handle or ID, and the list of its videos page by page.
- YouTube Video Metadata APITitle, description, views, likes, tags, categories and chapters of any video.
- YouTube Subtitles APICaptions as SRT, plain text or timed JSON, in every language a video has.
Every parameter and error code is in the search section of the API reference.
Search YouTube from your code
Create an account and get 25 free calls every month. The Python and TypeScript SDKs get you from install to first results in a few lines.