YouTube Search

Search YouTube videos, channels, playlists and Shorts.

GET/api/v1/youtube/search

Costs 1 credit per request; failed requests are refunded. Authentication, the search_metadata envelope and error codes are the same as for every endpoint (see the API reference). Try it in the playground.

Parameters

Search

Parameter	Type	Description
`q`	string	Search query. Required for the first page; omit with page_token.Up to 2,048 characters.Required on the first page.
`hl`	string	YouTube interface language, such as en or pt-BR. Defaults to en. Omit with page_token.
`gl`	string	Two-letter country code. Defaults to US. Omit with page_token.

Filters

Combine named filters, or supply an advanced sp token.

Parameter	Type	Description
`type`	"video" \| "shorts" \| "channel" \| "playlist" \| "movie"	Result type. Omit for mixed results. Movies appear in video_results.Channels and playlists cannot use upload_date, duration or features. Shorts cannot use duration. Movies cannot use live, subtitles, creative_commons or 3d features.
`upload_date`	"today" \| "this_week" \| "this_month" \| "this_year"	Limit results by upload date.
`duration`	"under_3_min" \| "between_3_and_20_min" \| "over_20_min"	Video duration: under 3 minutes, 3–20 minutes, or over 20 minutes.
`features`	string	Comma-separated features: live, 4k, hd, subtitles, creative_commons, 360, vr180, 3d, hdr, location. Combined features must all match.Up to 160 characters.
`sort_by`	"relevance" \| "popularity"	YouTube ranking: relevance (default) or popularity. Popularity is not a strict numerical view-count sort.Uses YouTube's current ranking choices. The removed upload-date/rating sorts and last-hour upload filter are not supported named values.
`sp`	string	Advanced YouTube filter token from a results URL. Use either sp or named filters, never both. Omit with page_token.Up to 2,048 characters.Use either sp or named filters, never both. Raw or once-URL-encoded values from a YouTube results URL are accepted.

Pagination

Parameter	Type	Description
`page_token`	string	Opaque next_page_token from the preceding response. Send it alone to continue the same search; tokens expire after one hour.Up to 32,768 characters.Send page_token alone, without query, locale or filter parameters. It preserves all filters. Use POST for long tokens. Pagination ends when pagination.next_page_token is absent.

Response

A JSON object with search_metadata (request id, credits used and remaining) and the result data: video_results, channel_results, playlist_results, shorts_results and pagination. Groups and fields depend on the content of each page, so treat every field as optional.

Examples

cURL

curl "https://serpfast.com/api/v1/youtube/search?q=python+tutorial&type=video" \
  -H "Authorization: Bearer $SERPFAST_KEY"

Node.js 18+

const params = new URLSearchParams({
  "q": "python tutorial",
  "type": "video"
});
const res = await fetch(`https://serpfast.com/api/v1/youtube/search?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SERPFAST_KEY}` },
});
const data = await res.json();
console.log(data);

Python

import os, requests

params = {
  "q": "python tutorial",
  "type": "video"
}
res = requests.get(
    "https://serpfast.com/api/v1/youtube/search",
    params=params,
    headers={"Authorization": f"Bearer {os.environ['SERPFAST_KEY']}"},
    timeout=120,
)
print(res.json())