YouTube Video Downloader and Metadata Extractor

Download YouTube videos or audio with yt-dlp, enrich each result with public metadata, and store the file in an external cloud provider or the run's default Apify key-value store.

The Python actor supports video qualities from 144p through 2160p, common video containers, and audio-only formats when ffmpeg is available. It creates one dataset result for every submitted URL: a success record with file and metadata details, or a failure record with the input rank and error.

Input

videos is required and accepts one to 100 YouTube URLs. Each item can be a URL string or an object with a url field.

Other options:

• preferredQuality — 144p, 240p, 360p, 480p, 720p, 1080p, 1440p, or 2160p; default 720p.
• preferredFormat — video formats such as mp4 or webm, or audio formats such as mp3, m4a, opus, and wav; default mp4.
• filenameTemplateParts — one to three unique values from title, uploader, and timestamp; default title.
• maxFileSizeMbytes — hard output-size limit from 1 to 512 MB; default 128 MB.
• maxDurationSeconds — duration limit from 1 to 7200 seconds; default 900 seconds.
• proxyConfiguration — optional Apify proxy configuration; direct access is the default.
• S3 fields — s3AccessKeyId, s3SecretAccessKey, s3Bucket, and s3Region.
• Azure fields — azureConnectionString and azureContainerName.
• Google Cloud fields — googleCloudServiceKey and googleCloudBucketName.

When a complete cloud configuration produces a URL, the actor records that provider and does not also write the file to KVS. If no cloud URL is available, the file is written to the default key-value store.

Example input

{
  "videos": [
    { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
  ],
  "preferredQuality": "1080p",
  "preferredFormat": "mp4",
  "filenameTemplateParts": ["title", "uploader"],
  "maxFileSizeMbytes": 128,
  "maxDurationSeconds": 900,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}

Output

Every row has recordType youtube_video_download, inputRank, inputUrl, url, and success.

Successful rows additionally contain:

• filename, format, quality, mimeType, fileSizeBytes, and fileSha256.
• videoId, title, channel and uploader identity, duration, upload date, views, likes, comments, tags, categories, language, availability, and live state when yt-dlp exposes them.
• storageProviders plus s3Url, azureUrl, googleCloudUrl, or keyValueStoreUrl for the actual destination.
• requestProfile, userAgent, proxyUsed, and downloadedAt.

Failed rows contain error and the submitted input identity. The failure view makes partial runs easy to audit.

Example output

{
  "recordType": "youtube_video_download",
  "inputRank": 1,
  "inputUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "success": true,
  "filename": "dQw4w9WgXcQ_Example_Title.mp4",
  "videoId": "dQw4w9WgXcQ",
  "title": "Example title",
  "format": "mp4",
  "quality": "1080p",
  "mimeType": "video/mp4",
  "fileSizeBytes": 12345678,
  "fileSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "storageProviders": ["apify-key-value-store"],
  "keyValueStoreKey": "dQw4w9WgXcQ_Example_Title.mp4",
  "keyValueStoreUrl": "https://api.apify.com/v2/key-value-stores/<store-id>/records/dQw4w9WgXcQ_Example_Title.mp4",
  "downloadedAt": "2026-08-16T00:00:00.000Z"
}

Cost and limitations

Cost depends on media size, requested quality, ffmpeg conversion time, proxy traffic, and cloud-upload traffic. Direct access is attempted unless you explicitly enable a proxy. Higher resolutions and audio transcoding require more time and disk. YouTube availability, age restrictions, region restrictions, bot checks, removed videos, and expiring formats can cause individual failures. S3 and Azure URLs returned by the actor may point to private objects and can require provider credentials.

Use only URLs and content you are permitted to download. Respect YouTube's terms and the terms of any external storage provider.