NAV

Datasets API
YouTube

shell json

Introduction

The YouTube Datasets API allows you to find Youtube videos that match your criteria and create and manage datasets of YouTube video metadata. The API returns clean, structured JSON data that can be downloaded directly or uploaded to your cloud storage (AWS or Google Cloud Storage).

Key features: - Create filtered datasets of YouTube video details - Apply multiple filter criteria to narrow down your data (e.g. category, view count, tags, duration, etc.) - Download data or upload to cloud storage (S3, GCS) - Standardized data schema for consistent results

Datasets API

POST /api/v2/datasets

curl -X POST "https://api.datasets.oxylabs.io/api/v2/datasets" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "name": "Popular Gaming Videos",
  "webType": "multimedia",
  "target": {
    "name": "youtube",
    "countries": ["US"]
  },
  "dataType": "video_details",
  "filters": [
    {
      "field": "statistics.views",
      "operator": "GREATER_THAN",
      "value": "1000000"
    },
    {
      "field": "categories",
      "operator": "CONTAINS",
      "value": "Gaming"
    }
  ]
}'

After you create a dataset that contains video IDs, you can use the Oxylabs Scraper API to download the videos or video transcripts.

Request Parameters

Parameter Description Required
name Name for your dataset Yes
webType Must be "multimedia" for YouTube Yes
target Target configuration object Yes
     name Must be "youtube" Yes
     countries Array of country codes (e.g., ["US"]) Yes
dataType Must be "video_details" Yes
filters Array of filter objects (optional) No
     field Field to filter on Yes (if filters used)
     operator Filter operator Yes (if filters used)
     value Filter value Yes (if filters used)

GET /api/v2/datasets

curl "https://api.datasets.oxylabs.io/api/v2/datasets" \
  -H "X-API-Key: YOUR_API_KEY"

Lists all your created datasets.

GET /api/v2/datasets/{datasetId}

curl "https://api.datasets.oxylabs.io/api/v2/datasets/166ed70e-3d53-4f0e-bbca-bdf6d33b3492" \
  -H "X-API-Key: YOUR_API_KEY"

Get details of a specific dataset by ID.

PATCH /api/v2/datasets/{datasetId}

curl -X PATCH "https://api.datasets.oxylabs.io/api/v2/datasets/166ed70e-3d53-4f0e-bbca-bdf6d33b3492" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "filters": [
    {
      "field": "statistics.views",
      "operator": "GREATER_THAN", 
      "value": "5000000"
    }
  ]
}'

Update an existing dataset's configuration.

DELETE /api/v2/datasets/{datasetId}

curl -X DELETE "https://api.datasets.oxylabs.io/api/v2/datasets/166ed70e-3d53-4f0e-bbca-bdf6d33b3492" \
  -H "X-API-Key: YOUR_API_KEY"

Delete a dataset.

Dataset Executions

POST /api/v2/datasets/{datasetId}/executions

curl -X POST "https://api.datasets.oxylabs.io/api/v2/datasets/166ed70e-3d53-4f0e-bbca-bdf6d33b3492/executions" \
  -H "X-API-Key: YOUR_API_KEY"

Execute a dataset to generate fresh data. This way you don't have to create a new dataset every time you want to get the latest data for specific set of filters.

GET /api/v2/datasets/{datasetId}/executions/{executionNumber}/results

curl "https://api.datasets.oxylabs.io/api/v2/datasets/166ed70e-3d53-4f0e-bbca-bdf6d33b3492/executions/1/results?page=1&pageSize=50" \
  -H "X-API-Key: YOUR_API_KEY"

Browse paginated results from a dataset execution.

Query Parameters

Parameter Description Required
page Page number (default: 1) No
pageSize Items per page (default: 25) No

Available Filters

The following fields are available for filtering YouTube video metadata:

Field Allowed Operators Description Example Values
id EQUAL NOT_EQUAL IN NOT_IN Video ID "dQw4w9WgXcQ"
title EQUAL NOT_EQUAL IN NOT_IN Video title "Never Gonna Give You Up"
description EQUAL NOT_EQUAL IN NOT_IN Video description "Official video"
url EQUAL NOT_EQUAL IN NOT_IN Video URL "https://youtube.com/watch?v=dQw4w9WgXcQ"
duration EQUAL NOT_EQUAL LESS_THAN LESS_THAN_OR_EQUAL GREATER_THAN GREATER_THAN_OR_EQUAL IN NOT_IN Duration in seconds 212
publishedOn EQUAL NOT_EQUAL IN NOT_IN Video publication date "2009-10-25"
license EQUAL NOT_EQUAL IN NOT_IN Video license type "Standard YouTube License"
contentRating EQUAL NOT_EQUAL LESS_THAN LESS_THAN_OR_EQUAL GREATER_THAN GREATER_THAN_OR_EQUAL IN NOT_IN Content rating "none"
tags CONTAINS NOT_CONTAINS Video tags "music"
categories CONTAINS NOT_CONTAINS Video categories "Music"
discoveredIn CONTAINS NOT_CONTAINS Where the video was discovered "trending"
statistics.views EQUAL NOT_EQUAL LESS_THAN LESS_THAN_OR_EQUAL GREATER_THAN GREATER_THAN_OR_EQUAL IN NOT_IN View count 1000000
statistics.likes EQUAL NOT_EQUAL LESS_THAN LESS_THAN_OR_EQUAL GREATER_THAN GREATER_THAN_OR_EQUAL IN NOT_IN Like count 50000
statistics.dislikes EQUAL NOT_EQUAL LESS_THAN LESS_THAN_OR_EQUAL GREATER_THAN GREATER_THAN_OR_EQUAL IN NOT_IN Dislike count 1000
statistics.comments EQUAL NOT_EQUAL LESS_THAN LESS_THAN_OR_EQUAL GREATER_THAN GREATER_THAN_OR_EQUAL IN NOT_IN Comment count 25000
statistics.shares EQUAL NOT_EQUAL LESS_THAN LESS_THAN_OR_EQUAL GREATER_THAN GREATER_THAN_OR_EQUAL IN NOT_IN Share count 5000
statistics.favorites EQUAL NOT_EQUAL LESS_THAN LESS_THAN_OR_EQUAL GREATER_THAN GREATER_THAN_OR_EQUAL IN NOT_IN Favorite count 10000
channel.id EQUAL NOT_EQUAL IN NOT_IN Channel ID "UCuAXFkgsw1L7xaCfnd5JJOw"
channel.name EQUAL NOT_EQUAL IN NOT_IN Channel name "@MrBeast"
channel.url EQUAL NOT_EQUAL IN NOT_IN Channel URL "https://youtube.com/@MrBeast"
author.id EQUAL NOT_EQUAL IN NOT_IN Author ID "UCuAXFkgsw1L7xaCfnd5JJOw"
author.name EQUAL NOT_EQUAL IN NOT_IN Author name "MrBeast"
author.url EQUAL NOT_EQUAL IN NOT_IN Author URL "https://youtube.com/@MrBeast"
languages.audio CONTAINS NOT_CONTAINS Audio language "en"
languages.subtitles CONTAINS NOT_CONTAINS Subtitle languages "en"
shell json