video-data

Oxylabs Video Data

YouTube data extraction via API and high-bandwidth proxies for video/audio downloading.

Two Approaches

Method	Use Case
Video Data API	Metadata, subtitles, search results (structured data)
High-Bandwidth Proxies	Video/audio downloads with yt-dlp

Video Data API

Uses the same endpoint as Web Scraper API with YouTube-specific sources.

Endpoint

POST https://realtime.oxylabs.io/v1/queries   # immediate metadata/search/subtitle responses
POST https://data.oxylabs.io/v1/queries       # Push-Pull downloads, callbacks, storage
Content-Type: application/json

Authentication

curl -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" ...

Available Sources

Source	Description
`youtube_search`	Search results up to 20 items (videos, channels, playlists)
`youtube_search_max`	Search results up to 700 items
`youtube_metadata`	Video metadata (title, views, likes, description)
`youtube_subtitles`	Closed captions/subtitles
`youtube_channel`	Channel data and video lists
`youtube_autocomplete`	Keyword suggestions
`youtube_video_trainability`	AI training permission status
`youtube_download`	Push-Pull video/audio download to cloud storage

Source Parameters

Source	Required	Common optional parameters
`youtube_search`, `youtube_search_max`	`query`	`upload_date`, `type`, `duration`, `sort_by`, `360`, `3d`, `4k`, `creative_commons`, `hd`, `hdr`, `live`, `location`, `purchased`, `subtitles`, `vr180`
`youtube_metadata`	`query`, `parse: true`	`callback_url`; do not use `render`
`youtube_channel`	`channel_handle`, `parse: true`	`limit`, `callback_url`
`youtube_subtitles`	`query`, `context.language_code`	`context.subtitle_origin`: `auto_generated` or `uploader_provided`; `callback_url`
`youtube_autocomplete`	`query`	`location` country code, `language`, `callback_url`
`youtube_video_trainability`	`video_id`	`callback_url`
`youtube_download`	`query`, `storage_type`, `storage_url`	`callback_url`, `context.download_type`, `context.video_quality`, `context.start_at`, `context.end_at`

For youtube_download, use Push-Pull and cloud storage. storage_type is gcs, s3, or s3_compatible; download_type is audio, video, or audio_video; video_quality is best, worst, or 144, 360, 480, 720, 1080, 1440, 2160, 4320.

Downloads default to 720p when available and are limited to 1 hour. start_at/end_at use hh:mm:ss; end_at must be later than start_at. For batch downloads, use /v1/queries/batch with a query array only; keep all other parameters singular.

Quick Start

Video metadata:

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "youtube_metadata",
    "query": "dQw4w9WgXcQ",
    "parse": true
  }'

YouTube search:

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "youtube_search",
    "query": "python tutorial"
  }'

Channel data:

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "youtube_channel",
    "channel_handle": "@channelhandle",
    "parse": true,
    "limit": 10
  }'

High-Bandwidth Proxies (Video Downloads)

For actual video/audio file downloads using yt-dlp.

Setup

Contact Oxylabs sales team to get a dedicated high-bandwidth endpoint.

Default configuration:

Port: 60000
Endpoint: Provided after purchase

Use OXY_HB_ENDPOINT; if absent, check OXYLABS_HB_ENDPOINT.

Connection Test

curl -x "http://USERNAME-test:PASSWORD@YOUR_ENDPOINT:60000" \
  "https://ip.oxylabs.io/location"

yt-dlp Integration

With session rotation (different IP per download):

yt-dlp --proxy "http://USERNAME-Random1Session2ID:PASSWORD@YOUR_ENDPOINT:60000" \
  "https://www.youtube.com/watch?v=VIDEO_ID"

Change the session ID for each download to get a fresh IP.

Python with yt-dlp

import yt_dlp
import os
import uuid

username = os.environ["OXY_WSA_USERNAME"]
password = os.environ["OXY_WSA_PASSWORD"]
endpoint = os.environ["OXY_HB_ENDPOINT"]  # Your dedicated endpoint

# Random session for unique IP
session_id = str(uuid.uuid4()).replace("-", "")

ydl_opts = {
    "proxy": f"http://{username}-{session_id}:{password}@{endpoint}:60000",
    "format": "best",
    "outtmpl": "%(title)s.%(ext)s"
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(["https://www.youtube.com/watch?v=VIDEO_ID"])

Choosing the Right Method

Need	Method
Video metadata (title, views, likes)	Video Data API
Search results	Video Data API
Subtitles	Video Data API
Channel information	Video Data API
Download video files	High-Bandwidth Proxies + yt-dlp
Download audio files	High-Bandwidth Proxies + yt-dlp

For more examples, see examples.md.