YouTube Video search
Search YouTube for videos matching a query
Endpoint
One endpoint for every offer below. Omit provider and the router picks with automatic failover — the response's served_by tells you which one ran.
https://api.socialrouter.io/v1/extract/youtube/video.searchOffers
Every offer below returns the same normalized output, in failover order — the first one serves unless you pin another with the provider field.
apify/streamersvia Apifydefault routeUp to 50 queries per request
$0.0055per record
Parameters
JSON body of the request. Unknown fields and unknown options are rejected with the valid list, so a wrong guess costs nothing.
| Parameter | Type | Description |
|---|---|---|
queriesRequired | string[] | Search queries to process. Accepted shape:Free-text search query, as you would type it in the YouTube search barExample: machine learning tutorialA single query string is accepted too. |
providerOptional | string | Pin one offer, e.g. apify/streamers. Omit it and the router picks with failover. |
limitOptional | integer | Max records to return per query. |
optionsOptional | object | Service-specific options, listed below. |
options.sortingOrderOptional | string | Result ordering, as the YouTube UI names it (e.g. relevance, date, views). |
options.videoTypeOptional | string | Restrict to a video type (e.g. video, movie). |
options.lengthFilterOptional | string | Video length filter (e.g. under4, between420, over20). |
options.isHDOptional | boolean | Only HD videos. |
options.hasSubtitlesOptional | boolean | Only videos with subtitles. |
options.hasCCOptional | boolean | Only Creative Commons videos. |
options.is3DOptional | boolean | Only 3D videos. |
options.isLiveOptional | boolean | Only live streams. |
options.is4KOptional | boolean | Only 4K videos. |
options.is360Optional | boolean | Only 360° videos. |
options.hasLocationOptional | boolean | Only geotagged videos. |
options.isHDROptional | boolean | Only HDR videos. |
options.isVR180Optional | boolean | Only VR180 videos. |
options.dateFilterOptional | string | Upload date filter (e.g. hour, today, week, month, year). |
Output
Each record has the fields below, whichever offer serves the request. Offers may include additional platform-specific fields on top.
titlestringVideo title
video_idstringPlatform video ID
profile_urlurlCanonical video URL
descriptionstringVideo description / caption
durationstringLength of the video
thumbnailurlThumbnail image URL
viewsnumberView count
likesnumberLike count
num_commentsnumberComment count
date_postedstringWhen the video was published (raw platform string)
channel_namestringChannel name
channel_urlurlChannel URL
source_ordernumberRank in the result list (1 = top)
sourcestringPlatform the record was extracted from (e.g. "linkedin")
extracted_atiso8601UTC timestamp when the record was produced
Going further
Auth, error semantics, and every other endpoint live in the API reference — including the machine-readable OpenAPI spec at /v1/openapi.json.
Frequently asked questions
How much does YouTube video search cost?
Prices start at $0.0055 per record, depending on the offer that serves the request. You are only charged for records actually returned.
Which offers serve youtube/video.search?
apify/streamers — 1 offer is available behind the same endpoint. Pin one with the optional "provider" field, or omit it and the router picks with automatic failover. The response's "served_by" field names the offer that ran.
What input does it need?
The "queries" field of the JSON body, as an array of strings: Free-text search query, as you would type it in the YouTube search bar. For example: machine learning tutorial
Is the output format the same for every offer?
Yes. Every offer returns the normalized record schema documented on this page; some add extra platform-specific fields on top, but the documented fields are always present.
How many queries can I send per request?
Up to 50 queries in a single request, depending on the offer.
What happens if an offer fails?
SocialRouter automatically fails over to the next offer serving the same service, so a single upstream outage doesn't break your integration.
What options does it take?
sortingOrder (string): Result ordering, as the YouTube UI names it (e.g. relevance, date, views). videoType (string): Restrict to a video type (e.g. video, movie). lengthFilter (string): Video length filter (e.g. under4, between420, over20). isHD (boolean): Only HD videos. hasSubtitles (boolean): Only videos with subtitles. hasCC (boolean): Only Creative Commons videos. is3D (boolean): Only 3D videos. isLive (boolean): Only live streams. is4K (boolean): Only 4K videos. is360 (boolean): Only 360° videos. hasLocation (boolean): Only geotagged videos. isHDR (boolean): Only HDR videos. isVR180 (boolean): Only VR180 videos. dateFilter (string): Upload date filter (e.g. hour, today, week, month, year).