Query Parameters
Restrict results to a single result type.| Value | Description |
|---|
all | All result types (default) |
video | Videos only |
channel | Channels only |
playlist | Playlists only |
movie | Movies only |
sort_by
string
default:"relevance"
Sort order for results.| Value | Description |
|---|
relevance | Best match (default) |
date | Most recently uploaded |
views | Most viewed |
rating | Highest rated |
Filter by upload recency: hour, today, week, month, or year.
Filter by video length: short (< 4 min), medium (4-20 min), or long (> 20 min).
Comma-separated feature filters, e.g. hd,4k,subtitles,live,creative_commons.
Content region (ISO 3166-1 alpha-2 country code). Examples: US, GB, DE, JP.
UI / interface language (BCP-47). Examples: en, de, fr, ja.
Continuation token from a previous response to fetch the next page.
Response
The search query that was executed.
Array of matching results (polymorphic, keyed by type).
Result type: video, channel, playlist, movie, or short.
Position on the page (nullable).
Video id (video/short/movie results, nullable).
Full URL to the result (nullable).
Thumbnail objects with url, width, height.
Best/primary thumbnail URL (nullable).
Human-readable duration, e.g. 3:32 (nullable).
Duration in seconds (nullable).
View count as displayed, e.g. 1.6B views (nullable).
Abbreviated view count (nullable).
Relative publish time, e.g. 13 years ago (nullable).
ISO 8601 publish timestamp (nullable).
Unix publish timestamp (nullable).
Short description snippet (nullable).
Result badges, e.g. 4K, CC.
Whether the video is live (nullable).
Whether the result is a Short (nullable).
Whether the video is members-only (nullable).
Associated channel id (nullable).
Channel avatar URL (nullable).
Whether the channel is verified (nullable).
Subscriber count text (channel results, nullable).
Subscriber count (channel results, nullable).
Video count text (channel results, nullable).
Channel @handle (channel results, nullable).
Whether the channel is verified (channel results, nullable).
Playlist id (playlist results, nullable).
Number of videos (playlist results, nullable).
First video id (playlist results, nullable).
Reported total result count (nullable).
Estimated result count (nullable).
Filter chips / refinements with title, is_selected, continuation.
Spelling suggestion, if any (nullable).
Corrected query actually searched (nullable).
Suggested query refinements.
Token to fetch the next page (nullable when no more pages).
Example Response
{
"query": "lofi hip hop",
"results": [
{
"type": "video",
"position": 1,
"video_id": "jfKfPfyJRdk",
"title": "lofi hip hop radio - beats to relax/study to",
"url": "https://www.youtube.com/watch?v=jfKfPfyJRdk",
"thumbnail": "https://i.ytimg.com/vi/jfKfPfyJRdk/hqdefault.jpg",
"duration": null,
"view_count_text": "Live · 42K watching",
"published_time_text": "Streamed 2 years ago",
"channel_id": "UCSJ4gkVC6NrvII8umztf0Ow",
"channel_name": "Lofi Girl",
"channel_is_verified": true,
"is_live": true,
"is_short": false
}
],
"estimated_results": 1240000,
"chips": [
{ "title": "All", "is_selected": true, "continuation": null },
{ "title": "Videos", "is_selected": false, "continuation": "EgIQAQ..." }
],
"continuation": "EpcDEgxsb2ZpIGhpcCBob3A..."
}
Each search request costs 5 credits. Failed requests are not charged.
