Prospect demo — Supadata (unofficial)
GET/youtube/search

Search YouTube for videos, channels, and playlists

Searches YouTube for videos, channels, and playlists. Use query with optional filters such as type, uploadDate, duration, sortBy, and features to refine results. Use nextPageToken to fetch another page; when you provide limit, the API paginates automatically.

8 parameters
querystringrequired
The search query string. Must contain at least one character.
uploadDatestringoptional
Filter by upload date: all, hour, today, week, month, or year. Applies only to videos and movies. Defaults to all when omitted.
Allowed:allhourtodayweekmonthyearDefault:all
typestringoptional
Filter by content type: all, video, channel, playlist, or movie. Defaults to all when omitted.
Allowed:allvideochannelplaylistmovieDefault:all
durationstringoptional
Filter video duration: all, short (under 4 minutes), medium (4–20 minutes), or long (over 20 minutes). Applies only to videos and movies. Defaults to all when omitted.
Allowed:allshortmediumlongDefault:all
sortBystringoptional
Sort search results by relevance, rating, date, or views. Defaults to relevance when omitted.
Allowed:relevanceratingdateviewsDefault:relevance
featuresarray<string>optional
Filter videos and movies by special features: hd, subtitles, creative-commons, 3d, live, 4k, 360, location, hdr, or vr180. Repeat the parameter to select multiple features.
limitnumberoptional
Maximum number of results to return. Must be between 1 and 5000; when omitted, the response contains one page and a `nextPageToken` for manual pagination.
nextPageTokenstringoptional
Token from a previous response to fetch the next page. When provided, other filter parameters are ignored.

3 status codes
200Returns the executed query, an array of search results, and an estimated total result count. Includes `nextPageToken` only when `limit` is not provided.
querystringrequired
The search query that was executed
resultsarray<object>required
Array of search results
totalResultsnumberoptional
Estimated total number of results
nextPageTokenstringoptional
Token for fetching the next page of results. Only returned when limit parameter is not provided.
400Returned when the search request is invalid.
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation
500Returned when an internal error occurs.
errorstringrequired
Error code identifying the type of error
Allowed:invalid-requestinternal-errorforbiddenunauthorizedupgrade-requiredtranscript-unavailablenot-foundlimit-exceeded
messagestringrequired
Human readable error message
detailsstringrequired
Detailed error description
documentationUrlstringoptional
URL to error documentation

Error handling

A 400 is returned when the request is invalid, and a 500 indicates an internal error. query must contain at least one character, and limit, when supplied, must be between 1 and 5000.