InsightSocial
GET /v1/youtube/search/advanced

YouTube Search Advanced API

Returns video search results with the full filter set: sort order, length, live status, license, category, country, language, and publish date window.

10–110 credits, metered · cursor pagination · failed calls free

curl "https://api.insightsocial.app/v1/youtube/search/advanced?query=lofi+hip+hop" \
-H "x-api-key: $INSIGHTSOCIAL_API_KEY"
200 OKJSON
{
"success": true,
"platform": "youtube",
"endpoint": "/v1/youtube/search/advanced",
"schema_version": "2",
"data": {
"items": [
{
"post": {
"id": "<string>",
"url": "<string | null>",
"kind": "<string | null>",
"content": {
"text": "<string | null>",
"media_urls": "<array | null>",
"thumbnail_url": "<string | null>",
"duration_seconds": "<number | null>"
},
"author": {
"id": "<string | null>",
"username": "<string | null>",
"display_name": "<string | null>",
"avatar_url": "<string | null>",
"verified": "<boolean | null>"
},
"engagement": {
"views": "<integer | null>",
"likes": "<integer | null>",
"comments": "<integer | null>",
"shares": "<integer | null>",
"saves": "<integer | null>"
},
"flags": {
"nsfw": "<boolean | null>",
"spoiler": "<boolean | null>",
"pinned": "<boolean | null>",
"deleted": "<boolean>",
"likes_hidden": "<boolean | null>",
"comments_hidden": "<boolean | null>",
"shares_hidden": "<boolean | null>",
"views_hidden": "<boolean | null>",
"saves_hidden": "<boolean | null>"
},
"published_at": "<string | null>",
"language": "<string | null>",
"ext": "<object | null>"
}
}
]
},
"pagination": {
"next_cursor": "<string | null>",
"has_more": "<boolean>"
},
"unavailable": [],
"credits_used": "<integer>"
}

When to use it

Use it when a plain keyword search is too blunt; results are always videos, so use search when you also want channels or playlists back.

Parameters

Query parameters for GET /v1/youtube/search/advanced. Send your key in the x-api-key header.

NameRequiredDescription
queryYesSearch query.
orderNoSort order: date, rating, relevance (default), title, videoCount, viewCount. order=date is exact (measured: zero inversions against the timestamps). order=viewCount is YouTube's popularity-weighted ranking: the top result is the true maximum but mid-list order is approximate, so for exact ranking add includeExtras=true and sort the page on engagement.views client-side. Both are far more faithful than /v1/youtube/search's sortBy=popular, which is not view-ordered at all.
durationNoVideo length: short (<4m), medium (4-20m), long (>20m), any. Genuinely applied (unlike /v1/youtube/search's duration, which the platform ignores). short plus a client-side post.content.duration_seconds <= 180 filter is the documented Shorts approximation: see the endpoint description for why it is an approximation and not a Shorts filter.
event_typeNoBroadcast type: live, upcoming, completed.
licenseNoLicense filter: creativeCommon, youtube, any.
categoryNoYouTube video category id (e.g. 10 = Music).
regionNoISO 3166-1 alpha-2 country code.
languageNoPreferred result language (ISO 639-1).
published_afterNoRFC-3339 datetime lower bound (e.g. 2026-01-01T00:00:00Z). Exact and genuinely applied. This is the endpoint to use for date-window work.
published_beforeNoRFC-3339 datetime upper bound. Exact and genuinely applied.
channel_idNoRestrict results to a single channel id.
max_resultsNoMaximum number of videos to return (1-50). Honored exactly: a page of 50 returns 50.
cursorNoPagination cursor from a previous response: fetches the next page.
safe_searchNoSafe-search filter: none, moderate, strict.
video_captionNoCaption filter: any, closedCaption, none.
video_definitionNoQuality filter: any, high, standard.
video_dimensionNoDimension filter: 2d, 3d, any.
video_embeddableNoRestrict to embeddable videos: true, any.
video_typeNoType filter: any, episode, movie.
topic_idNoRestrict to a Freebase topic id (e.g. /m/04rlf for music).
locationNoLatitude,longitude center for a geo search (e.g. 37.42307,-122.08427). Must be used together with location_radius.
location_radiusNoRadius around location with a unit suffix (e.g. 50km, 10mi). Must be used together with location.
includeExtrasNoSet to true to add the view, like and comment counts (post.engagement.views / .likes / .comments) and the video length (post.content.duration_seconds) to every result. Left off, those four are null. YouTube's search index returns snippets only, so the counts come from a second lookup.
includeNoSet to channel (one token only) to add each row's channel stats in this one call. channel puts the channel's subscriber count on post.ext.author_followers (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's post.author.display_name, .avatar_url and .username where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on post.ext.author_country (null when the channel sets none). Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds).
exact_datesNoDates are exact on this endpoint either way. Set to false to skip both lookups and get the snippet-only rows. The subscriber count stays include=channel.
sinceNoOnly rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off the page, and the page that reaches one ends the walk: next_cursor is not returned and pagination.stopped_at is since. Sending it sets the newest-first sort shown in this endpoint's sort parameter (any other sort value is a free 400). The page still costs what a page costs, so you pay for the pages you walk and no more. A row with no date is kept.
untilNoOnly rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept.
min_viewsNoKeep only rows with at least this many views (post.engagement.views). A row whose view count is unknown is discarded, so every returned row meets the floor.
max_age_daysNoKeep only rows published within this many days (post.published_at), 1 to 3650. A row with no date is discarded.
sort_rowsNoviews: orders the kept rows by view count, highest first. Rows without a view count go last. newest: orders the kept rows by publish date, newest first. Rows without a date go last. The sort covers only the rows this call collected over the pages it walked, not the whole feed. Every collected row is returned. A call that resumes from pagination.next_cursor sorts its own rows and does not merge them with the earlier ones.
max_pagesNo1 to 50 (default 1). Walk up to this many pages in one call and return the rows from all of them (after any filter).
max_age_sNoThe oldest cached copy you accept, in seconds. A copy that old or younger is served, with its age in age_s and the X-Cache-Age header. Without it a copy up to 120 seconds old is served. A lower value fetches fresh (billed) when the copy is older, and 0 always fetches live, like Cache-Control: no-cache.

Response fields

The same unified schema every typed endpoint returns, so code written for YouTube reads the other platforms too. A field the platform did not provide is null and listed in unavailable.

FieldTypeNotes
idstringAn identifier, always a string. Never parse it as a number: several platforms use ids above 2^53.
urlstring | null
kindstring | nullThe format of the post. Format words only, never a platform name. short = short-form vertical video (a reel, a TikTok, a YouTube Short).
content.textstring | null
content.media_urlsarray | null
content.thumbnail_urlstring | null
content.duration_secondsnumber | null
author.idstring | null
author.usernamestring | null
author.display_namestring | null
author.avatar_urlstring | null
author.verifiedboolean | null
engagement.viewsinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
engagement.likesinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
engagement.commentsinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
engagement.sharesinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
engagement.savesinteger | nullA count. null when the platform does not expose it; 0 only when it is really zero.
flags.nsfwboolean | null
flags.spoilerboolean | null
flags.pinnedboolean | null
flags.deletedboolean
flags.likes_hiddenboolean | null
flags.comments_hiddenboolean | null
flags.shares_hiddenboolean | null
flags.views_hiddenboolean | null
flags.saves_hiddenboolean | null
published_atstring | nullISO-8601 timestamp in UTC, ending in Z.
languagestring | nullThe content's language as the platform states it, e.g. en, pt-BR. Detected languages come later (§7.1).
extobject | nullPlatform-specific fields, snake_case.

Every field, error and example is in the YouTube Search Advanced API reference.

How much does the YouTube Search Advanced API cost?

Metered: 10–110 credits a call. The ceiling is reserved when the call starts and you are charged what it actually read.

  • Failed calls are free

    A call that errors or finds nothing costs 0 credits.

  • Know the price first

    Add dry_run=1 and the response quotes the call without making it. Nothing is charged.

  • One balance

    API calls and Chrome extension exports share the same credits, on the free plan too.

YouTube Search Advanced API: frequently asked questions

Send GET /v1/youtube/search/advanced with the query parameter and your key in the x-api-key header. Returns video search results with the full filter set: sort order, length, live status, license, category, country, language, and publish date window.