YouTube Video Description Extractor

Extract complete public descriptions and source-provided metadata from the player response embedded in YouTube watch pages. The Actor uses bounded HTTP requests and does not launch a browser, rotate fingerprints, spoof a user agent, click “Show more,” or call YouTube's private youtubei endpoints.

Input

{
  "videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
  "maxItems": 1
}

• videoUrls: 1–20 watch, Shorts, live, embed, youtu.be URLs, or bare 11-character IDs.
• maxItems: process at most 1–20 unique video IDs after deduplication; default 20.
• proxyConfiguration: optional explicit Apify Proxy settings. Direct HTTP is the default. Invalid requested proxy setup fails instead of silently reverting to direct traffic.

Inputs are normalized to canonical watch URLs. Credentialed URLs, custom ports, non-YouTube hosts, malformed IDs, unknown fields, and out-of-range limits are rejected before network work.

Dataset

One row is written only when YouTube's embedded player response matches the requested ID and exposes a non-empty title, description, channel identity, and HTTPS thumbnail.

{
  "recordType": "youtube_video_description",
  "recordId": "29f68fa62380b07a43e72b3d",
  "videoId": "dQw4w9WgXcQ",
  "originalUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Example title",
  "description": "The complete public description text.",
  "descriptionLength": 37,
  "descriptionLineCount": 1,
  "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "channelName": "Example channel",
  "channelUrl": "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw",
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "sourceHttpStatus": 200,
  "extractionMethod": "youtube-watch-player-response",
  "connectionMode": "direct",
  "proxyConfigured": false,
  "fingerprintApplied": false,
  "scrapedAt": "2026-08-31T10:00:00.000Z"
}

Optional source fields include description links and hashtags, public keywords, thumbnail dimensions, view count, duration, published date, category, family-safe flag, and live/upcoming flags. Missing optional values are omitted rather than written as null. Description URLs are restricted to public HTTP(S) targets; local, private, and credentialed URLs are discarded.

recordId is a deterministic 24-character SHA-256 prefix derived from the YouTube video ID.

Run summary and failure behavior

OUTPUT contains status, item/failure counts, connection provenance, timing, and bounded per-video diagnostics. Diagnostics never enter the paid dataset.

The Actor succeeds if at least one complete public description is saved. A mixed batch completes with SUCCEEDED_WITH_WARNINGS in OUTPUT. If every video is unavailable, challenged, mismatched, malformed, or has no public description, the Actor writes zero dataset rows, saves diagnostics to OUTPUT, and fails explicitly.

Operational limits

Requests are sequential, have a 20-second timeout and 5 MB response cap, and retry once only for timeouts, HTTP 429, or server errors. YouTube can independently return consent/challenge pages, restrict videos, or change the embedded page format. Private, deleted, age-gated, region-restricted, or genuinely blank-description videos may produce no dataset row.

Use collected data only where you have a lawful basis, and respect YouTube's terms, copyright, privacy rules, and applicable law.

Development

npm ci
npm test
npm run lint
npm run validate:schemas
npm audit --omit=dev