YouTube Video Scraper

Collect public YouTube video metadata from video URLs, channel handles or URLs, and search queries. Export your results as JSON, CSV, or Excel. The Actor reads public HTML pages and does not call paid data APIs, model APIs, YouTube source APIs, or other Actors.

Input

In Apify Console, run the prefilled example to collect one video from @OpenAI. Replace the channel handle with your own. Clear Channels when switching to video URLs or search queries.

{
  "channels": ["@OpenAI"],
  "maxItems": 1,
  "useApifyProxyFallback": false
}

For individual videos:

{
  "startUrls": [{"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"}],
  "maxItems": 1
}

For a search:

{
  "searchQueries": ["OpenAI"],
  "maxItems": 5
}

Field	Meaning	Default
startUrls	Public video or channel URLs. Supports youtu.be, Shorts, and live video links.	Empty
channels	Handles such as @OpenAI, channel IDs, or channel URLs.	Prefilled @OpenAI in Console
searchQueries	Search phrases; keywords remains a compatible alias.	Empty
maxItems	Maximum delivered videos; for uploaded records, maximum scanned records.	1
maxVideosPerChannel / maxVideosPerKeyword	Maximum delivered videos from each initial channel/search page.	10 each
maxTotalVideos	Additional total cap; zero uses maxItems.	0
maxPublicPages	Maximum HTTP requests across sources, redirects, and retries.	3
requestTimeoutSecs	Total download timeout per attempt, including redirects and streaming.	12
deduplicateVideos	Return one result per video ID across sources.	true
useApifyProxyFallback	Explicitly enable potentially paid proxy retries.	false
proxyConfiguration	Proxy settings used only when proxy fallback is explicitly true.	Residential proxy for enabled retries
analysisQuery	Literal phrase to find in delivered records.	Empty

With no source fields supplied to the API, the Actor uses the same one-video @OpenAI example. Channel and search modes collect the initial public page; they do not paginate through a complete archive or all search results. Limits are maximums, not guaranteed result counts.

Output

Each default-dataset row includes a video ID, canonical URL, title, source, and collection time. Channel details, thumbnails, durations, publication text, descriptions, and view counts are included when exposed on the public page.

An output excerpt from a previously collected public video:

{
  "record_type": "video",
  "video_id": "6ep8Vvm4Bdw",
  "url": "https://www.youtube.com/watch?v=6ep8Vvm4Bdw",
  "title": "Why Merge CEO Shensi Ding stays hands-on with Codex",
  "query": "@OpenAI",
  "query_type": "channel",
  "dataInputSource": "web",
  "sourceVerified": true,
  "metadataCoverage": "initial_page"
}

Actual rows also include collection and processing timestamps and a processing hash. Metadata varies by source and layout. Exact observed counts preserve real zeros. Abbreviated values such as 147K views remain in view_count_text; unavailable metrics, including likes, stay unknown. No guessed counts or placeholder videos are produced.

Results are saved after each source. OUTPUT and PUBLIC_COLLECTION_SUMMARY in the run key-value store report requested, attempted, and skipped source counts, HTTP attempts, proxy usage, delivered records, and stop reasons. status is succeeded, partial, or failed. Stop reasons distinguish result limits, request limits, deadlines, charging limits, exhausted sources, and a zero-result limit. A later source failure preserves earlier delivered records and returns partial results. A run with no meaningful metadata fails clearly, except when an explicit zero-result or charging limit prevents collection.

EVIDENCE_ANALYSIS contains deterministic analysis and literal phrase matches from confirmed delivered records. sourceRecordHash identifies a processed row; it is not a YouTube-issued identifier. Metadata does not establish playback availability.

Use cases

Collect titles and descriptions for content research, inspect a channel's visible videos, find videos through public search, or save metadata snapshots for later comparison.

Uploaded records

Existing workflows can use providedRecords or providedDatasetId with maxItems. Clear all YouTube source fields when supplying records. Uploaded records are validated and deduplicated, labeled dataInputSource: "provided" and sourceVerified: false, and are not fetched from YouTube. Actual observation timestamps are required for meaningful snapshot comparisons. PROVIDED_DATA_SUMMARY reports validation and delivery counts.

Costs and public-data limits

No paid data API is used. Apify hosting, storage, result pricing, and explicitly enabled proxy usage can still incur charges; consult the Store pricing panel.

Direct collection is the default. Proxy settings and environment proxy variables do not silently enable a proxy. If YouTube blocks a public page, the Actor returns a clear source failure or partial results. To allow up to two proxy retries within your request budget, explicitly set:

{
  "startUrls": [{"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"}],
  "maxItems": 1,
  "useApifyProxyFallback": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Changing from earlier releases: omitting useApifyProxyFallback now means false. Supplying proxyConfiguration alone does not enable it and produces a warning in the run summary.

Collection has a 150-second deadline, a four-megabyte decompressed HTML limit per document, and the configured request/result budgets. TLS verification remains enabled. Collection uses public HTML only. Private, age-restricted, login-only, consent-wall, and otherwise restricted pages are skipped without bypass attempts. No video files, comments, transcripts, or continuation API responses are collected. Older includeLikeCount, useYtDlpFallback, and maxConcurrency settings remain accepted for compatibility and do not enable additional collection services.

Python API example

This example uses Apify Client for Python 3.x.

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("nRTzbCmODVqCn10lZ").call(run_input={
    "channels": ["@OpenAI"],
    "maxItems": 1,
    "useApifyProxyFallback": False,
})
if run is None:
    raise RuntimeError("The Actor did not return a completed run.")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

For support, share a run ID and sanitized input through the Actor Issues tab.