YouTube Video Downloader - Videos, Audio and Metadata

Download permitted YouTube videos or audio files into Apify key-value storage and get a clean dataset row for every URL. This actor is built for workflows where you own the video, have permission from the rights holder, or have another lawful basis to download it.

It accepts one or more YouTube video URLs, probes each video with yt-dlp, enforces duration and file-size caps, saves the media file to the default key-value store, and returns metadata plus storage keys in the dataset. It is perfect for SEO and AI agents, and MCP optimized.

What you get

• Video downloads up to a selected maximum quality: 360p, 480p, 720p, 1080p or best available.
• Audio-only downloads as M4A, MP3 or best source audio.
• Metadata-only mode for cheap URL checks without media download.
• Apify key-value store files with predictable keys.
• Structured dataset rows with title, channel, duration, views, thumbnail, file key, metadata key and errors.
• Residential proxy support and optional cookies.txt for videos that require your own logged-in session.

Input

Field	Type	Default	Notes
videoUrls	URL list	required	YouTube video URLs only
authorizationConfirmed	boolean	false	Must be true before downloads run
downloadMode	enum	video	video, audio, or metadataOnly
videoQuality	enum	720p	Max video quality
preferredContainer	enum	mp4	mp4, webm, or any
audioFormat	enum	m4a	m4a, mp3, or best
maxDurationMinutes	integer	60	Skip longer videos
maxFileSizeMb	integer	250	Delete and skip files above this cap
includeMetadataJson	boolean	true	Save raw yt-dlp metadata JSON
cookiesTxt	string	empty	Optional Netscape cookies.txt content

Example input

{
  "videoUrls": [
    { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }
  ],
  "authorizationConfirmed": true,
  "downloadMode": "video",
  "videoQuality": "720p",
  "preferredContainer": "mp4",
  "maxDurationMinutes": 10,
  "maxFileSizeMb": 100
}

Output

One dataset row is returned per URL:

{
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "canonicalUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoId": "dQw4w9WgXcQ",
  "title": "Example video",
  "channel": "Example Channel",
  "durationSeconds": 213,
  "viewCount": 1000000,
  "downloadMode": "video",
  "fileKey": "video-dqw4w9wgxcq-example-video.mp4",
  "fileName": "dQw4w9WgXcQ.mp4",
  "fileExtension": "mp4",
  "fileSizeBytes": 12345678,
  "contentType": "video/mp4",
  "metadataKey": "metadata-dqw4w9wgxcq.json",
  "status": "success",
  "error": null,
  "scrapedAt": "2026-06-11T12:00:00Z"
}

Downloaded files are stored in the default key-value store. Use the fileKey and metadataKey fields to fetch the exact records.

Pricing

Pay per event, no rental:

• $0.00005 actor start.
• $0.015 per video or audio file saved to key-value storage.
• $0.003 per metadata-only URL successfully probed.

Failed and skipped downloads are not charged for media events.

MCP and AI agent use

Tool description draft:

Download authorized YouTube videos or audio to Apify storage. Use when the user owns the video or has permission and needs a reusable media file plus metadata. Do not use for transcripts or search. Returns one row per URL with title, channel, duration, fileKey, metadataKey, status and error. Charged $0.015 per media file.

The output stays flat and predictable so agents can reason over it without reading raw yt-dlp metadata unless they need to fetch the metadata JSON file.

Legal

Only download videos you own, videos you have permission to download, or videos you are otherwise legally allowed to copy. You are responsible for complying with YouTube's Terms of Service, copyright law, privacy law and any other rules that apply to your use case. This actor is not affiliated with, endorsed by, or sponsored by YouTube or Google.