Search

Query Parameters

query

string

required

Search keywords.

type

string

default:"all"

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

upload_date

string

Filter by upload recency: hour, today, week, month, or year.

duration

string

Filter by video length: short (< 4 min), medium (4-20 min), or long (> 20 min).

features

string

Comma-separated feature filters, e.g. hd,4k,subtitles,live,creative_commons.

string

default:"US"

Content region (ISO 3166-1 alpha-2 country code). Examples: US, GB, DE, JP.

string

default:"en"

UI / interface language (BCP-47). Examples: en, de, fr, ja.

continuation

string

Continuation token from a previous response to fetch the next page.

Response

query

string

The search query that was executed.

results

array

Array of matching results (polymorphic, keyed by type).

Show SearchResult object

type

string

Result type: video, channel, playlist, movie, or short.

position

integer

Position on the page (nullable).

video_id

string

Video id (video/short/movie results, nullable).

title

string

Result title (nullable).

url

string

Full URL to the result (nullable).

thumbnails

array

Thumbnail objects with url, width, height.

thumbnail

string

Best/primary thumbnail URL (nullable).

duration

string

Human-readable duration, e.g. 3:32 (nullable).

length_seconds

integer

Duration in seconds (nullable).

view_count

integer

View count (nullable).

view_count_text

string

View count as displayed, e.g. 1.6B views (nullable).

short_view_count_text

string

Abbreviated view count (nullable).

published_time_text

string

Relative publish time, e.g. 13 years ago (nullable).

published_at

string

ISO 8601 publish timestamp (nullable).

published_utc

number

Unix publish timestamp (nullable).

description_snippet

string

Short description snippet (nullable).

badges

array

Result badges, e.g. 4K, CC.

extensions

array

Extra metadata strings.

is_live

boolean

Whether the video is live (nullable).

is_short

boolean

Whether the result is a Short (nullable).

is_members_only

boolean

Whether the video is members-only (nullable).

channel_id

string

Associated channel id (nullable).

channel_name

string

Channel name (nullable).

channel_url

string

Channel URL (nullable).

channel_thumbnail

string

Channel avatar URL (nullable).

channel_is_verified

boolean

Whether the channel is verified (nullable).

subscriber_count_text

string

Subscriber count text (channel results, nullable).

number_of_subscribers

integer

Subscriber count (channel results, nullable).

video_count_text

string

Video count text (channel results, nullable).

channel_username

string

Channel @handle (channel results, nullable).

is_verified

boolean

Whether the channel is verified (channel results, nullable).

playlist_id

string

Playlist id (playlist results, nullable).

video_count

integer

Number of videos (playlist results, nullable).

first_video_id

string

First video id (playlist results, nullable).

total_results

integer

Reported total result count (nullable).

estimated_results

integer

Estimated result count (nullable).

chips

array

Filter chips / refinements with title, is_selected, continuation.

did_you_mean

string

Spelling suggestion, if any (nullable).

showing_results_for

string

Corrected query actually searched (nullable).

Suggested query refinements.

Related search objects.

continuation

string

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.

Overview

Search & Discovery

Videos & Shorts

Channels

Playlists & Community

Query Parameters

Response

Example Response

​Query Parameters

​Response

​Example Response

Query Parameters

Response

Example Response