Media Scrapers
Reference for dedicated Web API media scraper endpoints, parameters and delivery modes for every endpoint.
General
POST /v1/async/scrape/media
Downloads a video from a URL (TikTok, BiliBili, etc.) and uploads it to your storage bucket. Max video length – 12 hours. Maximum download time – 1 hour.
Modes: async, batch
url
string
yes
Video URL.
TikTok: tiktok.com/@{user}/video/{id}, tiktok.com/embed/{id}, vm.tiktok.com/{id}, vt.tiktok.com/{id}.
BiliBili: bilibili.com/video/{id}, bilibili.com/bangumi/play/{id}.
http://, https://, www. prefixes and query strings are accepted
storage
object
yes
Delivers the result to a storage bucket: {"type": string, "url": string}. type is s3, s3_gzip, s3_compatible, gcs, or tos. Async only. url is not validated
video_quality
string
no
best, worst, or a resolution: 144, 360, 480, 720, 1080, 1440, 2160 (4K), 4320 (8K).
Default: TikTok – 720, BiliBili – 480.
callback_url
string
no
Webhook URL for the finished job. Malformed URLs are rejected with 400
YouTube
POST /v1/scrape/media/youtube/metadata
Returns a video’s title, channel, description, duration, view, like and comment counts, upload date, categories, tags, chapters, thumbnails and available subtitle languages.
Modes: sync, async, batch
query
string
yes
Video ID, e.g. tIgIF5lve8U. Not a URL. In batch, an array of IDs
output
array of strings
no
["json"] (default) returns the parsed metadata. ["json", "html"] also returns the page source
callback_url
string
no
Async only. Webhook URL the finished job is posted to. Malformed URLs are rejected with 400
storage
object
no
Delivers the result to a bucket instead of the response: {"type": string, "url": string}. type is s3, s3_gzip, s3_compatible, gcs, or tos. Async only. url is not validated
A deleted, private or restricted video returns state: "done" with empty results. The reason is in results[0].metadata.statuses.video_download, e.g. 11202 (unavailable) or 11206 (age-restricted).
POST /v1/scrape/media/youtube/subtitles
Returns a video’s subtitle tracks with text and timings, grouped by origin and language.
Modes: sync, async, batch
query
string
yes
Video ID, e.g. c4P_YuNnZ7U. Not a URL. In batch, an array of IDs
language_code
string
no
Subtitle language, e.g. en. Lowercase; unknown codes are rejected with 400. Omit to get all languages
subtitle_origin
string
no
uploader_provided or auto_generated. Omit to get both
json
object
no
Custom extraction: {"prompt": string} or {"schema": object}, never both. Without it, the subtitle tracks are returned as YouTube serves them
callback_url
string
no
Async only. Webhook URL the finished job is posted to. Malformed URLs are rejected with 400
storage
object
no
Delivers the result to a bucket instead of the response: {"type": string, "url": string}. type is s3, s3_gzip, s3_compatible, gcs, or tos. Async only. url is not validated
A valid language_code with no matching track returns an empty result ({}), not an error.
POST /v1/async/scrape/media/youtube/download
Downloads a video, its audio, or a clip of either, to your cloud storage.
Modes: sync, async
query
string
yes
Video ID, e.g. 9cQBNYsCqQs. Not a URL. In batch, an array of IDs
storage
object
yes
{"type": string, "url": string}. type is s3, gcs, s3_compatible or tos. url is the bucket and folder, e.g. bucket-name/folder/; the API names the file
output
array of strings
no
One of ["audio_video"] (default), ["audio"] or ["video"]
video_quality
string
no
best, worst, 144, 360, 480, 720, 1080, 1440, 2160 or 4320. Default 720; if 720p is not available, the best quality below it
audio_language
string
no
default (default) or original, the video’s original audio track when it has dubs
start_at
string
no
Start of a clip, as hh:mm:ss, e.g. 00:01:30. Omit to start from the beginning
end_at
string
no
End of a clip, as hh:mm:ss, e.g. 00:05:45. Must be later than start_at
callback_url
string
no
Webhook URL the finished job is posted to
The finished job returns the file name in results[0].filename. An age-restricted video returns state: "done" with no file and status 11206 in results[0].metadata.statuses.video_download.
POST /v1/scrape/media/youtube/channel
Returns a channel’s details (name, ID, subscriber, video and view counts, country, join date, links) and its latest videos.
Modes: sync, async
query
string
yes
Channel handle, e.g. @Oxylabs (the @ is optional). Channel IDs (UC…) are not supported
limit
integer
no
Number of videos to return. Default 20; 0 returns channel details only
output
array of strings
no
["json"] returns the parsed channel data. ["html"] (default) returns the page source. Use json: ["markdown"] returns little more than the page footer
callback_url
string
no
Async only. Webhook URL the finished job is posted to. Malformed URLs are rejected with 400
storage
object
no
Delivers the result to a bucket instead of the response: {"type": string, "url": string}. type is s3, s3_gzip, s3_compatible, gcs, or tos. Async only. url is not validated
POST /v1/scrape/media/youtube/search
Returns up to 20 YouTube search results.
Modes: sync, async
query
string
yes
Search phrase
upload_date
string
no
last_hour, today, this_week, this_month or this_year
type
string
no
video, channel, playlist or movie
duration
string
no
<4 (under 4 minutes), 4-20 (4 to 20 minutes) or >20 (over 20 minutes)
sort_by
string
no
relevance (default), upload_date, view_count or rating
360
boolean
no
Only 360° videos
3d
boolean
no
Only 3D videos
4k
boolean
no
Only 4K videos
creative_commons
boolean
no
Only Creative Commons-licensed videos
hd
boolean
no
Only HD videos
hdr
boolean
no
Only HDR videos
live
boolean
no
Only live streams
location_tag
boolean
no
Only videos that carry a location tag. Returns an empty list when none match
purchased
boolean
no
Only purchased content
subtitles
boolean
no
Only videos with subtitles or closed captions
vr180
boolean
no
Only VR180 videos
location
string
no
Country to get results for, as a two-letter ISO code, e.g. IN
callback_url
string
no
Async only. Webhook URL the finished job is posted to. Malformed URLs are rejected with 400
storage
object
no
Delivers the result to a bucket instead of the response: {"type": string, "url": string}. type is s3, s3_gzip, s3_compatible, gcs, or tos. Async only. url is not validated
POST /v1/scrape/media/youtube/search/max
Returns up to 700 search results for the same parameters as /search, at higher cost and latency.
Modes: sync, async
query
string
yes
Search phrase
upload_date
string
no
last_hour, today, this_week, this_month or this_year
type
string
no
video, channel, playlist or movie
duration
string
no
<4 (under 4 minutes), 4-20 (4 to 20 minutes) or >20 (over 20 minutes)
sort_by
string
no
relevance (default), upload_date, view_count or rating
360
boolean
no
Only 360° videos
3d
boolean
no
Only 3D videos
4k
boolean
no
Only 4K videos
creative_commons
boolean
no
Only Creative Commons-licensed videos
hd
boolean
no
Only HD videos
hdr
boolean
no
Only HDR videos
live
boolean
no
Only live streams
location_tag
boolean
no
Only videos that carry a location tag. Returns an empty list when none match
purchased
boolean
no
Only purchased content
subtitles
boolean
no
Only videos with subtitles or closed captions
vr180
boolean
no
Only VR180 videos
location
string
no
Country to get results for, as a two-letter ISO code, e.g. IN
callback_url
string
no
Async only. Webhook URL the finished job is posted to. Malformed URLs are rejected with 400
storage
object
no
Delivers the result to a bucket instead of the response: {"type": string, "url": string}. type is s3, s3_gzip, s3_compatible, gcs, or tos. Async only. url is not validated
POST /v1/scrape/media/youtube/autocomplete
Returns YouTube’s search suggestions for a partial phrase.
Modes: sync, async
query
string
yes
Partial phrase to complete, e.g. how to make
location_tag
string
no
Country the suggestions are for, as a lowercase two-letter code, e.g. de
language
string
no
Suggestion language, e.g. en
callback_url
string
no
Async only. Webhook URL the finished job is posted to. Malformed URLs are rejected with 400
storage
object
no
Delivers the result to a bucket instead of the response: {"type": string, "url": string}. type is s3, s3_gzip, s3_compatible, gcs, or tos. Async only. url is not validated
POST /v1/scrape/media/youtube/video/trainability
Returns a video’s declared AI-training permission: permitted is ["all"], ["None"], or a list of the parties allowed to train on it.
Modes: sync, async
query
string
yes
Video ID, e.g. rFNDylrjn_w. Not a URL
callback_url
string
no
Async only. Webhook URL the finished job is posted to. Malformed URLs are rejected with 400
storage
object
no
Delivers the result to a bucket instead of the response: {"type": string, "url": string}. type is s3, s3_gzip, s3_compatible, gcs, or tos. Async only. url is not validated
The signal is declared by the rights holder. It is not a legal clearance.
Last updated
Was this helpful?