Developer Guide · Last updated: June 12, 2026
YouTube Search API: How search.list Works, What It Costs & Smarter Alternatives
Everything developers ask about searching YouTube via API: the search.list reference with working curl, Python, and JavaScript examples, the quota math nobody warns you about, and what to use when keyword-literal search isn't enough.
Quick answer
To search YouTube programmatically, call the search.list method of the YouTube Data API v3 at GET https://www.googleapis.com/youtube/v3/search with an API key, a q parameter, and part=snippet. Each search.list call costs 100 quota units — 1% of the default 10,000-unit daily quota — and returns up to 50 results per page ranked by keyword relevance, without view counts. For research workloads, semantic alternatives such as the OutlierKit API's POST /outliers/search return meaning-matched videos with outlier performance scores for 1 credit per call.
YouTube search API: facts at a glance
| Official method | search.list (YouTube Data API v3) |
|---|---|
| Cost | 100 quota units per call |
| Max results | 50 per page (paginate with pageToken) |
| Sort options | relevance, date, viewCount, rating, title |
| View counts included | No — requires a follow-up videos.list call |
| Semantic matching | No |
| OutlierKit semantic search | POST /api/v1/outliers/search, 1 credit per call |
Beyond keyword-literal search.list
The OutlierKit API's semantic /outliers/search returns meaning-matched videos with composite performance scores for 1 credit — drop it in next to search.list instead of burning 100 units a call.
Reference
How does search.list work?
search.list is a single GET endpoint. Authentication is an API key for public search (see how to get a YouTube API key) — no OAuth needed unless you're searching the authenticated user's own content.
GET https://www.googleapis.com/youtube/v3/searchKey parameters
| Parameter | Type | What it does |
|---|---|---|
| q | string | The search query. Supports - to exclude terms (e.g. boating -fishing) and | for OR. |
| part | string | Required. Set to snippet — the only part search.list supports. |
| type | string | Restrict results to video, channel, or playlist (comma-separated). Default returns all three. |
| maxResults | integer | Results per page, 0–50. Default is 5 — most people bump this to 50. |
| order | string | relevance (default), date, viewCount, rating, or title. |
| publishedAfter / publishedBefore | datetime | RFC 3339 timestamps (e.g. 2026-01-01T00:00:00Z) to bound the upload window. |
| channelId | string | Restrict the search to one channel's content. |
| videoDuration | string | short (<4 min), medium (4–20 min), long (>20 min). Requires type=video. |
| regionCode | string | ISO 3166-1 alpha-2 country code — return results viewable in that region. |
| relevanceLanguage | string | ISO 639-1 language code — prefer results most relevant to that language. |
| pageToken | string | Pass nextPageToken from the previous response to fetch the next page. |
Response shape
Each result is a search#result resource. For videos, the id you care about lives at id.videoId (channels use id.channelId, playlists id.playlistId). The snippet carries title, description, channel info, publish date, and thumbnails.
{
"kind": "youtube#searchListResponse",
"nextPageToken": "CDIQAA",
"pageInfo": { "totalResults": 1000000, "resultsPerPage": 50 },
"items": [
{
"kind": "youtube#searchResult",
"id": { "kind": "youtube#video", "videoId": "dQw4w9WgXcQ" },
"snippet": {
"publishedAt": "2026-03-14T10:00:00Z",
"channelId": "UC...",
"title": "Video title here",
"description": "Truncated description...",
"channelTitle": "Channel Name",
"thumbnails": { "default": {...}, "medium": {...}, "high": {...} }
}
}
]
}Pagination: pass nextPageToken back as pageToken until it disappears from the response. Every page is another 100-unit call.
Code
Working examples: curl, Python, JavaScript
The YouTube Data API v3 search endpoint works the same from any language: send a GET request with your API key and read the JSON response. The three examples below — curl, Python, and JavaScript — each run one search and then fetch view counts with a second videos.list call.
curl
curl "https://www.googleapis.com/youtube/v3/search\
?part=snippet\
&q=car%20restoration\
&type=video\
&maxResults=50\
&order=relevance\
&key=YOUR_API_KEY"Python
Using google-api-python-client — see our full YouTube API Python guide for setup.
from googleapiclient.discovery import build
youtube = build("youtube", "v3", developerKey="YOUR_API_KEY")
response = youtube.search().list(
part="snippet",
q="car restoration",
type="video",
maxResults=50,
order="relevance",
).execute() # costs 100 quota units
video_ids = [item["id"]["videoId"] for item in response["items"]]
# snippet has NO view counts — follow up with videos.list (1 more unit)
stats = youtube.videos().list(
part="statistics,contentDetails",
id=",".join(video_ids),
).execute()
for v in stats["items"]:
print(v["id"], v["statistics"]["viewCount"])JavaScript (fetch)
const KEY = process.env.YOUTUBE_API_KEY;
const params = new URLSearchParams({
part: "snippet",
q: "car restoration",
type: "video",
maxResults: "50",
key: KEY,
});
const res = await fetch(
`https://www.googleapis.com/youtube/v3/search?${params}`
); // 100 quota units
const data = await res.json();
const videoIds = data.items.map((i) => i.id.videoId).join(",");
// Second call for the stats search.list won't give you
const statsRes = await fetch(
`https://www.googleapis.com/youtube/v3/videos?part=statistics&id=${videoIds}&key=${KEY}`
); // 1 quota unit
const stats = await statsRes.json();part=snippet. No statistics, no duration, no likes. To get view counts you must collect the videoIds and make a second call to videos.list with part=statistics. That second call is cheap (1 unit), but it's a second round-trip on every single search.The Honest Part
The two problems with search.list
search.list is fine for building a video picker into an app. It falls apart the moment you try to use it for research. Two reasons.
Why does YouTube search cost 100 quota units?
Every search.list call costs 100 quota units. The default daily quota is 10,000 units. That's a hard ceiling of 100 searches per day — for your entire project, across all users and all jobs. (Full breakdown in our YouTube API quota guide.)
Here's the worked math for a modest niche-research script:
Goal: research 10 niches, top ~150 videos each, with view counts
10 niches × 3 pages of search.list (50 results/page)
= 30 search calls × 100 units = 3,000 units
30 follow-up videos.list calls (stats)
= 30 calls × 1 unit = 30 units
Total: 3,030 units — 30% of your ENTIRE daily quota
for ONE run of ONE small script.
Run it 4×/day, or for 35 niches? You're locked out
until midnight Pacific.You may have read about the playlistItems.list trick — fetching a channel's uploads playlist for 1 unit instead of searching for 100. It's real and you should use it, but it only works when you already know the channel. It enumerates one channel's uploads; it cannot search by topic. For discovery — the thing "search" actually means — there is no cheap path through the official API.
Quota increases exist, but they require a compliance audit from Google, take weeks, and are routinely denied for research-style use cases.
It searches keywords, not meaning — and knows nothing about performance
- ·No semantic matching. Search "budget car restoration" and a video titled "I rebuilt this wreck for $500" may never surface, because the words don't overlap. You end up running the same conceptual search five times with different phrasings — at 100 units each.
- ·No performance context. Results don't even include view counts, let alone anything relative. You cannot ask the question every researcher actually has: "show me videos overperforming their channel in this topic."
- ·Results skew to big channels. Relevance ranking favors authority, and
order=viewCountmakes it worse — absolute views just resurface MrBeast-scale channels and old viral hits. A 2M-view video from a 50k-sub channel (the actual signal in niche research) ranks below a 2M-view video from a 50M-sub channel (noise). - ·No channel baseline data. Even after the videos.list follow-up, you still need a third round of calls per channel to compute averages — and now you're building a data pipeline, not running a search.
Alternatives
What are the alternatives to search.list?
The alternatives to the official search.list method fall into two camps: scraper APIs that mirror YouTube's public results without quota limits, and purpose-built research APIs like OutlierKit that add semantic matching and performance context. The table compares all three.
| Official search.list | Scraper APIs | OutlierKit API | |
|---|---|---|---|
| Matching | Keyword-literal | Keyword-literal (mirrors YouTube's UI) | Semantic (embedding similarity) |
| Cost model | Free, but 100 units/call → ~100 searches/day | Pay per request; no quota, but ToS gray zone | 1 credit/search (cached); 5 credits for live refresh |
| View counts in results | No — second call required | Usually yes | Yes, plus relative outlier metrics |
| Performance context | None | Raw stats only — you compute baselines yourself | outlierMetrics + channel summary per result |
| Best for | In-app video pickers, ToS-clean products | Bulk raw-data extraction | Niche, competitor & ideation research at scale |
We cover the scraper route in depth — providers, pricing, and the legal gray zone — in the YouTube scraper API guide.
Semantic Search Alternative
OutlierKit: search by meaning, ranked by performance
The OutlierKit API is a YouTube competitive-intelligence API that returns outlier scores, semantic channel search and similarity, video transcripts, comments, and keyword search volumes as structured JSON — one bearer-token key, 1 credit per call, on OutlierKit Pro ($49/month) and Max ($199/month) plans.
The OutlierKit API (base URL https://outlierkit.com/api/v1, bearer-token auth) ships three search endpoints built for the research workflows search.list can't handle:
POST /outliers/search Cached · 1 credit
Semantic search over an index of outlier videos. Every result includes outlierMetrics (outlierMultiplier, channelOutlierRatio, viewsVsChannelAvg, viewsVsRecentAverage, highestValue) plus a channel summary. Cached — it does not call YouTube, so it returns fast and never touches your Google quota.
POST /channels/search Cached · 1 credit
Semantic channel search — something the official API barely supports at all. Each channel result comes with its top outlier videos embedded (videosPerChannel, default 10, up to 50), so one call tells you both who plays in a niche and what's working for them. Sort by similarity, subscribers, or recency.
POST /outliers/refresh Live · 5 credits
Deep Outlier Search — pulls live from YouTube when you need fresh or broader coverage than the index has (maxPages 1–5, default 3). Results are ranked by outlier score and saved back to the index in the background, so subsequent cached searches get richer.
Example: semantic outlier search
curl -X POST "https://outlierkit.com/api/v1/outliers/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "cars",
"limit": 5,
"threshold": 0.3,
"minOutlierScore": 0
}'Parameters: query (required), limit 1–100 (default 20), offset for pagination, threshold 0–1 similarity floor (default 0.35), minOutlierScore to filter by performance, and sortBy (similarity | recent | views). The response wraps results with searchText, totalFound, and hasMore — pagination without page tokens.
Pricing: Pro is $49/mo (500 credits), Max is $199/mo (2,000 credits), top-ups $10 per 100. Credits are shared with the OutlierKit web app. Full request/response schemas live in the live API docs.
For Pro and Max users
Searching YouTube for research? Do it semantically.
Replace five rephrased search.list calls (500 quota units, zero performance context) with one semantic /outliers/search call: 1 credit, outlier scores and channel context on every result, no daily quota ceiling.
Decision Guide
Which YouTube search API should you use?
Choosing between the official search.list method and the OutlierKit API is not either/or. Plenty of teams run both — official search.list inside the product, OutlierKit behind the research pipeline.
| You need to… | Use | Why |
|---|---|---|
| Build a video-picker UI inside your app (user types, picks a video) | Official search.list | You need YouTube's own relevance ranking and the full public catalog. 100 units per keystroke-debounced search is fine at UI scale. |
| Embed or play videos after search | Official search.list | Pair with the IFrame Player API. ToS-compliant end to end. |
| Niche or competitor research at scale (hundreds of queries) | OutlierKit API | Semantic matching plus outlier scores per result. No quota wall — 1 credit per cached search. |
| Find videos overperforming their channel baseline in a topic | OutlierKit API | search.list has no performance context at all. outlierMetrics is the whole point of /outliers/search. |
| Discover channels (not videos) in a topic, with proof they perform | OutlierKit API | /channels/search returns semantically matched channels with their top outlier videos embedded. |
| Fresh results straight from YouTube, ranked by performance | OutlierKit /outliers/refresh | Live Deep Outlier Search — 5 credits, ranks by outlier score, saves results back to the index. |
| Both a user-facing picker and a research pipeline | Both (common) | search.list for the UI, OutlierKit for the research jobs. They don't compete for the same budget. |
YouTube Search API: Frequently Asked Questions
Is there a YouTube search API?+
Yes — the official YouTube search API is the search.list method of the YouTube Data API v3, a GET request to https://www.googleapis.com/youtube/v3/search with a q parameter. The search.list method returns videos, channels, and playlists ranked by keyword relevance. The API is free to use, but each search.list call costs 100 quota units out of a default daily quota of 10,000 units.
How much does the YouTube search API cost?+
The YouTube Data API v3 is free — there's no per-call billing. The constraint is quota: every search.list call costs 100 quota units, and the default daily quota is 10,000 units per project. That works out to a hard ceiling of 100 searches per day unless you request a quota increase from Google, which requires an audit and is not guaranteed.
How many results can the YouTube search API return?+
The YouTube search API (search.list) returns up to 50 results per page (maxResults=50; the default is only 5). To get more, paginate: pass the nextPageToken from each response as pageToken on the next request. Every page is a fresh search.list call costing another 100 quota units, and YouTube caps the total accessible results for a query at roughly 500.
How do I search within a specific channel?+
To search within a specific channel using the YouTube Data API v3, add the channelId parameter to your search.list request along with q — that restricts results to the channel's content and still costs 100 quota units. If you just want all of a channel's uploads (no keyword filter), the playlistItems.list method on the channel's uploads playlist is far cheaper — 1 quota unit per call instead of 100.
Why don't YouTube search API results include view counts?+
search.list only supports part=snippet, which returns title, description, channel, thumbnails, and publish date — no statistics. To get view counts, likes, or duration, you must collect the videoIds from the search response and make a second call to videos.list with part=statistics,contentDetails. That second call costs 1 additional quota unit.
Can I sort YouTube search results by views?+
Yes — the YouTube search API sorts by views when you set order=viewCount on search.list. But search.list sorts by absolute view count, which heavily favors huge channels and old viral videos. There's no way to sort by performance relative to a channel's baseline, which is what most research workflows actually need. That relative-performance ranking is what OutlierKit's outlier scores provide, for 1 credit per search.
Is there a semantic YouTube search API?+
Google does not offer a semantic YouTube search API — search.list matches keywords, not meaning. The OutlierKit API offers semantic search over YouTube content: POST /outliers/search runs embedding-based similarity over an index of outlier videos for 1 credit per call, so a query like 'budget car restoration' also surfaces videos titled 'I rebuilt this wreck for $500'. Each result includes outlier metrics and channel context.
How does OutlierKit search differ from the official YouTube search API?+
The OutlierKit API differs from the official YouTube search API (search.list) in three ways. (1) Matching: OutlierKit is semantic — it matches intent, not literal keywords. (2) Context: every result ships with outlierMetrics (multiplier vs. channel average, channel outlier ratio, views vs. recent average) plus a channel summary, so you can rank by performance, not just relevance. (3) Economics: cached searches cost 1 credit with no 100-search daily ceiling; Pro is $49/mo for 500 credits. It searches an index of outlier videos rather than the entire YouTube catalog, with /outliers/refresh (5 credits) for live pulls when you need fresh coverage.
Stop burning 100 quota units per search
OutlierKit's semantic search returns outlier-scored videos and channel context in one call — 1 credit, cached, no daily ceiling. API access is included on Pro and Max plans.
View the API docs