Skip to content
Gridlode
Docs · Reference

YouTube Search

GET /v1/youtube/search1 credit / pagecache 60 min

YouTube search results exactly as a signed-out visitor sees them: videos (title, link, channel, published date, views, duration, thumbnail, description snippet, badges), Shorts, channels and playlists or courses, with filters for result type, upload date, duration and sort order. Fetches as many result pages as your limit needs and hands back a next_page_token to continue later. Billed per results page fetched (up to about 20 results each; pages heavy with Shorts shelves hold fewer, and type=video gives the densest pages); verification pages, blocks and failures are free.

Query parameters

q
string · required
Search query, as typed into YouTube's search box.
type
string
Only return this kind of result (YouTube's own type filter).
Default: "all"
Allowed: all, video, short, channel, playlist
sort
string
Result order.
Default: "relevance"
Allowed: relevance, popularity
upload_date
string
Only videos uploaded within this period.
Default: "any"
Allowed: any, today, week, month, year
duration
string
Only videos of this length.
Default: "any"
Allowed: any, under_3_min, 3_to_20_min, over_20_min
limit
integer
Maximum results of the requested type (videos, channels and playlists for type=all; Shorts shelves come along, capped at the same number). Each results page fetched holds up to about 20 and costs 1 credit.
Default: 20
hl
string
Interface language, e.g. en, de, pt-BR.
Default: "en"
gl
string
Two-letter country code whose results to show.
Default: "us"
page_token
string
next_page_token from a previous response, to continue the same search where it stopped.
Default: null
max_age
integer
Accept a cached answer up to this many seconds old, billed at 50%.

Response data fields

    Example

    curl "https://api.gridlode.com/v1/youtube/search?q=python%20tutorial&limit=10" \
  -H "Authorization: Bearer $GRIDLODE_KEY"

    Try it without code on the YouTube Search API page.