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](examples.md).