Search YouTube
Search YouTube.
Operation
/v1/youtube/searchHeaders
API key (`sfk_...`)
Parameters
Search query text for YouTube content.
min 1 chars · max 512 chars
Optional upload date filter for video results.
one of: today, this_week, this_month, this_year
Optional sort order for search results.
one of: relevance, popular
Optional content type filter for search results.
one of: videos, shorts, channels, playlists
Optional duration filter for video results. Applies to videos, not shorts.
one of: under_3_min, between_3_and_20_min, over_20_min
Optional two-letter region code for localized search results.
min 2 chars · max 2 chars
Opaque pagination cursor returned by a previous response.
min 1 chars
When true, returns richer per-video metadata when available. May increase response time.
Response fields
Endpoint-specific response payload.
Search query string evaluated for this response.
Matching YouTube videos.
YouTube content identifier.
min 1 chars
Normalized media kind for this row.
one of: video, short, live
Canonical public URL for this item when available.
Title shown for this item.
Thumbnail image URL when available.
Channel metadata when available.
Channel identifier when available.
Channel title when available.
Channel handle when available.
Channel thumbnail URL when available.
View count when available.
≥ 0
Human-readable view count label when available.
ISO-8601 publish timestamp when available. May be null for some live items.
Human-readable relative publish time when available.
Duration in seconds when available.
≥ 0
Human-readable duration label when available.
Display badges such as New, Live, or 4K when present.
Description text when extras are requested and available.
Like count when extras are requested and available.
≥ 0
Human-readable like count when extras are requested.
Comment count when extras are requested and available.
≥ 0
Human-readable comment count when extras are requested.
Matching YouTube Shorts.
YouTube content identifier.
min 1 chars
Normalized media kind for this row.
one of: video, short, live
Canonical public URL for this item when available.
Title shown for this item.
Thumbnail image URL when available.
Channel metadata when available.
Channel identifier when available.
Channel title when available.
Channel handle when available.
Channel thumbnail URL when available.
View count when available.
≥ 0
Human-readable view count label when available.
ISO-8601 publish timestamp when available. May be null for some live items.
Human-readable relative publish time when available.
Duration in seconds when available.
≥ 0
Human-readable duration label when available.
Display badges such as New, Live, or 4K when present.
Description text when extras are requested and available.
Like count when extras are requested and available.
≥ 0
Human-readable like count when extras are requested.
Comment count when extras are requested and available.
≥ 0
Human-readable comment count when extras are requested.
Matching YouTube channels.
YouTube channel identifier.
min 1 chars
Channel display name.
Channel handle when available.
Channel description snippet when available.
Channel avatar or banner thumbnail when available.
Subscriber count when available.
≥ 0
Human-readable subscriber count when available.
Display badges such as Verified when present.
Matching YouTube playlists.
YouTube playlist identifier.
min 1 chars
Playlist title.
Canonical playlist URL when available.
Playlist thumbnail URL when available.
Number of videos in the playlist when available.
≥ 0
Representative video id shown for the playlist when available.
Representative video URL when available.
Playlist owner channel when available.
Playlist owner channel id when available.
Playlist owner channel title.
Playlist owner handle when available.
Playlist owner channel URL when available.
Grouped shelf rows when returned.
Shelf type label when available.
Shelf title when available.
Media items grouped in this shelf.
YouTube content identifier.
min 1 chars
Normalized media kind for this row.
one of: video, short, live
Canonical public URL for this item when available.
Title shown for this item.
Thumbnail image URL when available.
Channel metadata when available.
Channel identifier when available.
Channel title when available.
Channel handle when available.
Channel thumbnail URL when available.
View count when available.
≥ 0
Human-readable view count label when available.
ISO-8601 publish timestamp when available. May be null for some live items.
Human-readable relative publish time when available.
Duration in seconds when available.
≥ 0
Human-readable duration label when available.
Display badges such as New, Live, or 4K when present.
Description text when extras are requested and available.
Like count when extras are requested and available.
≥ 0
Human-readable like count when extras are requested.
Comment count when extras are requested and available.
≥ 0
Human-readable comment count when extras are requested.
Matching YouTube live streams.
YouTube content identifier.
min 1 chars
Normalized media kind for this row.
one of: video, short, live
Canonical public URL for this item when available.
Title shown for this item.
Thumbnail image URL when available.
Channel metadata when available.
Channel identifier when available.
Channel title when available.
Channel handle when available.
Channel thumbnail URL when available.
View count when available.
≥ 0
Human-readable view count label when available.
ISO-8601 publish timestamp when available. May be null for some live items.
Human-readable relative publish time when available.
Duration in seconds when available.
≥ 0
Human-readable duration label when available.
Display badges such as New, Live, or 4K when present.
Description text when extras are requested and available.
Like count when extras are requested and available.
≥ 0
Human-readable like count when extras are requested.
Comment count when extras are requested and available.
≥ 0
Human-readable comment count when extras are requested.
Count of top-level result rows returned in this response across all buckets.
≥ 0
Pagination information for the current response.
Cursor to pass in the next request when another page exists.
Whether another page of results is available.
Metadata describing the request and billing outcome.
Unique request identifier for tracing this API call.
min 1 chars
Credits charged for this request.
≥ 0
Public API version that served the response.
one of: v1
Code example
Responses
Search results for the requested query.
Error codes