Search

Query Parameters

string

required

Search keywords.

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

string

default:"relevance"

Sort order for results.

Value	Description
`relevance`	Best match (default)
`date`	Most recently uploaded
`views`	Most viewed
`rating`	Highest rated

string

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

string

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

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.

string

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

Response

string

The search query that was executed.

array

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

Show SearchResult object

string

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

integer

Position on the page (nullable).

string

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

string

Result title (nullable).

string

Full URL to the result (nullable).

array

Thumbnail objects with url, width, height.

string

Best/primary thumbnail URL (nullable).

string

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

integer

Duration in seconds (nullable).

integer

View count (nullable).

string

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

string

Abbreviated view count (nullable).

string

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

string

ISO 8601 publish timestamp (nullable).

number

Unix publish timestamp (nullable).

string

Short description snippet (nullable).

array

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

array

Extra metadata strings.

boolean

Whether the video is live (nullable).

boolean

Whether the result is a Short (nullable).

boolean

Whether the video is members-only (nullable).

string

Associated channel id (nullable).

string

Channel name (nullable).

string

Channel URL (nullable).

string

Channel avatar URL (nullable).

boolean

Whether the channel is verified (nullable).

string

Subscriber count text (channel results, nullable).

integer

Subscriber count (channel results, nullable).

string

Video count text (channel results, nullable).

string

Channel @handle (channel results, nullable).

boolean

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

string

Playlist id (playlist results, nullable).

integer

Number of videos (playlist results, nullable).

string

First video id (playlist results, nullable).

integer

Reported total result count (nullable).

integer

Estimated result count (nullable).

array

Filter chips / refinements with title, is_selected, continuation.

string

Spelling suggestion, if any (nullable).

string

Corrected query actually searched (nullable).

Suggested query refinements.

Related search objects.

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