YouTube Search¶
Search YouTube without a YouTube Data API key and get back structured video results — video ID, title, thumbnail, channel, duration, view count, and a description snippet — ready to feed into transcript or metadata endpoints.
| Method | Endpoint | Returns |
|---|---|---|
GET |
/v1/youtube/search |
{query, results[], nextPageToken} |
Base URL: https://youtube.toolkitapi.io
Every request needs an X-API-Key header.
Related pages: YouTube Playlist · YouTube Playlist Videos
Request parameters¶
| Parameter | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
query |
query | string | yes | — | Search terms, as you'd type them into youtube.com. Missing → 422. |
limit |
query | integer | no | 20 |
Maximum number of results, 1–50. Out-of-range → 422. |
URL-encode the query (curl -G --data-urlencode, params= in Python, URLSearchParams in JS). Multi-word queries become +/%20 separated automatically by those helpers.
Response¶
{
"query": "python tutorial",
"results": [
{
"id": "rfscVS0vtbw",
"type": "video",
"title": "Learn Python - Full Course for Beginners [Tutorial]",
"url": "https://www.youtube.com/watch?v=rfscVS0vtbw",
"thumbnailUrl": "https://i.ytimg.com/vi/rfscVS0vtbw/hqdefault.jpg",
"description": "This course will give you a full introduction into all of the core concepts in python.",
"channelName": "freeCodeCamp.org",
"duration": 16194,
"viewCount": 45000000
}
],
"nextPageToken": null
}
| Field | Type | Notes |
|---|---|---|
query |
string | Echo of your query |
results |
array | Up to limit items |
results[].id |
string | 11-character video ID |
results[].type |
string | Currently always "video" |
results[].title |
string | Video title |
results[].url |
string | Canonical https://www.youtube.com/watch?v=<id> |
results[].thumbnailUrl |
string | https://i.ytimg.com/vi/<id>/hqdefault.jpg |
results[].description |
string | null | Snippet from the result's metadata, when YouTube provides one |
results[].channelName |
string | null | Uploading channel's display name |
results[].duration |
integer | null | Duration in seconds |
results[].viewCount |
integer | null | View count as displayed (abbreviated values are approximated) |
results[].publishedAt |
string | null | Schema field; not currently populated |
nextPageToken |
string | null | Schema field; always null today — see pagination below |
What is and isn't returned¶
The service scrapes youtube.com/results and parses the initialData payload, walking only videoRenderer entries. Practical consequences:
- Videos only. Channels and playlists that YouTube shows in search results are skipped, even though
typeis typed asvideo | channel | playlistin the schema. - No pagination. To get more than one page, vary
limit(max 50) or issue narrower queries. - Abbreviated counts.
viewCountderives from display text ("1.2M views"→1200000), so it is approximate for large numbers. - Tolerates upstream failures. Scrape or parse errors are logged and return
200withresults: []. An empty list for an obvious query means retry, not "zero results".
Discovery → processing pipeline
Search for candidate videos, take results[].id, then call /v1/youtube/video for full metadata or /v1/youtube/transcript for captions. IDs from search need no further parsing.
Examples¶
curl¶
curl -G "https://youtube.toolkitapi.io/v1/youtube/search" \
--data-urlencode "query=python tutorial" \
--data-urlencode "limit=5" \
-H "X-API-Key: $YOUTUBE_API_KEY"
Python¶
import httpx
API = "https://youtube.toolkitapi.io"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
def search_videos(query: str, limit: int = 10) -> list[dict]:
resp = httpx.get(
f"{API}/v1/youtube/search",
params={"query": query, "limit": limit},
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
return resp.json()["results"]
for hit in search_videos("fastapi tutorial", limit=5):
mins = (hit["duration"] or 0) // 60
print(f'{hit["id"]} {mins:>3}m {hit["title"][:60]}')
JavaScript¶
const API = "https://youtube.toolkitapi.io";
const HEADERS = { "X-API-Key": "YOUR_API_KEY" };
async function searchVideos(query, limit = 10) {
const qs = new URLSearchParams({ query, limit: String(limit) });
const res = await fetch(`${API}/v1/youtube/search?${qs}`, { headers: HEADERS });
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
return (await res.json()).results;
}
const hits = await searchVideos("fastapi tutorial", 5);
hits.forEach((h) => console.log(h.id, h.title, h.channelName));
Errors¶
| Status | When |
|---|---|
401 |
Missing or invalid X-API-Key |
422 |
query missing, or limit outside 1–50 |
429 |
Rate limit exceeded |
5xx |
Upstream failure |
A 200 with an empty results array is also possible on scrape failure — retry with backoff before treating it as "no matches".