For the complete documentation index, see llms.txt. This page is also available as Markdown.

Media Scrapers

Reference for dedicated Web API media scraper endpoints, parameters and delivery modes for every endpoint.

Scraper
Endpoints

/media

/media/youtube/metadata, /media/youtube/subtitles, /media/youtube/download, /media/youtube/channel, /media/youtube/search, /media/youtube/search/max, /media/youtube/autocomplete, /media/youtube/video/trainability

Videos that can't be downloaded fail with a media-specific error code (11201–11304). See Media error codes.

Storage URLs are validated for s3, s3_gzip, s3_compatible, and tos. An invalid value returns 400 before the request is created.

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

Name
Type
Required
Description

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

Name
Type
Required
Description

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

Name
Type
Required
Description

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

Name
Type
Required
Description

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

Name
Type
Required
Description

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

Name
Type
Required
Description

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

Name
Type
Required
Description

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

Name
Type
Required
Description

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

Name
Type
Required
Description

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?