YouTube Video Downloader - Videos, Audio and Metadata

This Apify Actor is for teams, developers, and AI-agent workflows that already have one or more specific YouTube video URLs and want a structured result for each submitted URL. It accepts full YouTube video URLs in youtube.com/watch, youtu.be, Shorts, and embed formats, and one record means one processed YouTube URL in the dataset. The most useful returned fields are title, channel, durationSeconds, viewCount, thumbnail, fileKey, metadataKey, status, and scrapedAt, so you can both understand the video and fetch saved files from Apify storage. The outcome is a predictable dataset plus key-value store entries for downloaded media and optional raw metadata JSON.

Best fit and connected workflows

This Actor fits URL-based YouTube workflows where you already know which video to process and the next step needs either a saved media asset or a compact metadata row.

Use it when you want to:

• Save a permitted YouTube video file to the default Apify key-value store.
• Save audio only from a known YouTube URL for downstream media handling.
• Probe a URL in metadataOnly mode when the next step needs video details without saving media.
• Keep file scope aligned with automation by setting maxDurationMinutes and maxFileSizeMb.
• Add stable storage references such as fileKey and metadataKey to an internal workflow.

A natural connected workflow is to first discover candidate videos at the channel level with YouTube Channel Videos Scraper - Metadata & Metrics, then pass selected video URLs into this downloader when your next YouTube step is saving media or probing a specific video URL.

Practical scenario

Maya manages a training content archive. She already has permission to reuse a specific YouTube training video and starts with the watch URL.

She runs this Actor with downloadMode set to video, videoQuality set to 720p, and maxDurationMinutes set to the expected training length. The returned dataset row includes title, channel, durationSeconds, thumbnail, fileKey, fileName, fileExtension, fileSizeBytes, metadataKey, status, and scrapedAt. Maya reviews the metadata, uses fileKey to fetch the saved media from the default key-value store, and then passes the file plus metadata into her internal cataloging step.

Input

Field	Type	Required	Description
videoUrls	array of objects	yes	One or more YouTube video URLs, each as { "url": "..." }
authorizationConfirmed	boolean	yes	Confirms you have permission or another lawful basis to download the submitted videos
downloadMode	string	no	video, audio, or metadataOnly
videoQuality	string	no	Maximum video height for video downloads: 360p, 480p, 720p, 1080p, or suitable
preferredContainer	string	no	Preferred video container: mp4, webm, or any
audioFormat	string	no	Audio output format: m4a, mp3, or suitable
maxDurationMinutes	integer	no	Duration cap from 1 to 720 minutes
maxFileSizeMb	integer	no	File-size cap from 1 to 1000 MB
includeMetadataJson	boolean	no	Saves raw yt-dlp metadata JSON to the default key-value store
cookiesTxt	string or null	no	Optional Netscape cookies.txt content for your own logged-in YouTube session
proxyConfiguration	object	no	Apify proxy settings, prefilled with residential proxy configuration

Focused input example:

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

Output

This Actor writes one dataset row per submitted URL and stores downloaded media and optional metadata JSON in the default key-value store.

Field	Type	Meaning
videoUrl	string	Original YouTube URL submitted
canonicalUrl	string or null	Canonical webpage URL returned by yt-dlp
videoId	string or null	YouTube video ID
title	string or null	Video title
channel	string or null	Uploader or channel name
channelUrl	string or null	Uploader or channel URL
durationSeconds	number or null	Video duration in seconds
viewCount	number or null	View count at extraction time
uploadDate	string or null	Upload date in YYYYMMDD format
thumbnail	string or null	Thumbnail URL
downloadMode	string	video, audio, or metadataOnly
fileKey	string or null	Key-value store key for the saved media file
fileName	string or null	Saved media file name
fileExtension	string or null	Saved media file extension
fileSizeBytes	number or null	Saved media file size in bytes
contentType	string or null	Content type used for the saved media file
metadataKey	string or null	Key-value store key for raw yt-dlp metadata JSON
status	string	success, skipped, or failed
error	string or null	Actionable message for that URL when present
scrapedAt	string	ISO 8601 timestamp when the row was produced

Illustrative output record:

{
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "canonicalUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoId": "dQw4w9WgXcQ",
  "title": "Example video title",
  "channel": "Example Channel",
  "channelUrl": "https://www.youtube.com/@example",
  "durationSeconds": 213,
  "viewCount": 1000000,
  "uploadDate": "20260611",
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "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"
}

Top-level output references:

• downloadRows: default dataset items endpoint for structured rows
• downloadedFiles: default key-value store keys endpoint for media and metadata files

How it works

This Actor uses yt-dlp to probe each submitted YouTube URL and extract metadata. For media runs, it downloads the selected video or audio and saves the resulting file to the default Apify key-value store. When includeMetadataJson is enabled, it also saves the raw yt-dlp metadata JSON for each successful URL.

The download contract is controlled by the input:

• downloadMode chooses video, audio, or metadata-only processing
• videoQuality and preferredContainer shape video downloads
• audioFormat shapes audio output
• maxDurationMinutes applies a duration cap before download
• maxFileSizeMb applies a final file-size cap
• cookiesTxt supports your permitted logged-in YouTube session
• proxyConfiguration is prefilled with residential Apify proxy settings

Implementation facts visible in the live contract:

• Built as a Python Actor
• Uses yt-dlp and ffmpeg
• Default memory is 2048 MB
• Default timeout is 1800 seconds
• Results are returned through the default dataset and default key-value store

Pricing

This Actor uses Pay per event plus Apify platform usage. See the live Pricing tab on the Actor page for the current source of truth.

The charging model includes event-based billing for:

• Actor start
• Media file saved
• Metadata only

A simple example in words: if one run saves three media files, that execution includes one Actor start event and three Media file saved events, plus standard Apify platform usage. If a run probes two URLs in metadataOnly mode, that corresponds to one Actor start event and two Metadata only events, plus platform usage.

Use with AI agents (MCP)

This Apify Actor is usable through Apify MCP as a tool for processing known YouTube video URLs and returning structured metadata plus storage references.

Exact Actor identity: khadinakbar/youtube-video-downloader

Precise tool description: Use this tool when the user already has one or more specific YouTube video URLs and wants either a saved video file, a saved audio file, or metadata-only probing. It returns one dataset row per submitted URL, with fields such as title, channel, durationSeconds, fileKey, metadataKey, status, and scrapedAt.

Download these permitted YouTube URLs with khadinakbar/youtube-video-downloader. Use metadataOnly for quick URL checks, or save media when I need a reusable file in Apify storage. Return one row per URL with title, channel, durationSeconds, fileKey, metadataKey, status, and scrapedAt.

How to interpret the output:

• Read the default dataset first because it is the structured index of the run.
• Use status to understand the per-URL outcome.
• Use fileKey to fetch the saved media file from the default key-value store when media was saved.
• Use metadataKey to fetch raw yt-dlp metadata JSON when it was requested.
• Use scrapedAt for traceability.

Provenance and scope:

• Every row comes from a submitted YouTube video URL.
• The Actor processes one or more URLs per run.
• The output remains one row per URL, which is helpful for agent planning and deterministic reconciliation.

Pagination and cost guidance:

• Read dataset items from the default dataset endpoint when you need all rows.
• Larger URL lists produce more rows, so agents can batch related URLs in one run and then page through dataset items as needed.
• Costs follow the event model, so metadataOnly is useful when the task only needs structured video details.

Apify API example

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const actorClient = client.actor('khadinakbar/youtube-video-downloader');

const run = await actorClient.call({
  videoUrls: [
    { url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' }
  ],
  authorizationConfirmed: true,
  downloadMode: 'metadataOnly',
  includeMetadataJson: true
});

const { items } = await client
  .dataset(run.defaultDatasetId)
  .listItems();

console.log('Run status:', run.status);
console.log('Dataset rows:', items);
console.log('Key-value store ID:', run.defaultKeyValueStoreId);

Best results and outcome guidance

Start with exact video URLs rather than broader YouTube surfaces. This Actor is specifically designed for individual video URLs, including watch URLs, short URLs, Shorts, and embed URLs.

Choose downloadMode based on the next step:

• video when a downstream step needs a playable video file
• audio when a downstream step needs audio only
• metadataOnly when routing decisions depend on metadata rather than a saved media asset

Use videoQuality, preferredContainer, and audioFormat to match the destination system. For example, mp4 is a practical choice when broad playback compatibility matters, while m4a is a compact option for many audio workflows.

Set maxDurationMinutes and maxFileSizeMb to keep each run aligned with your storage and automation envelope. If your workflow begins with channel discovery rather than known URLs, start with YouTube Channel Videos Scraper - Metadata & Metrics and then send selected video URLs into this Actor for download or metadata probing.

Design note

I found that the dataset contract always requires videoUrl, downloadMode, status, and scrapedAt, while media-related fields such as fileKey, fileName, fileExtension, and fileSizeBytes remain nullable. That makes the row shape stable across video, audio, and metadataOnly workflows, which is especially useful for agents that first reason over the dataset and only fetch stored files when a key is present.

FAQ

Which YouTube URL formats work with this Actor?

The input contract accepts full video URLs in youtube.com/watch, youtu.be, Shorts, and embed formats.

What does one record mean in the dataset?

One record represents one processed YouTube video URL from your submitted videoUrls array.

Where are downloaded files stored?

Saved media files and optional raw metadata JSON are stored in the default key-value store. The dataset row provides the storage references through fileKey and metadataKey.

When should I use metadataOnly?

Use metadataOnly when you want the Actor to probe the URL and return structured fields such as title, channel, durationSeconds, viewCount, and thumbnail without saving a media file.

How does this connect to a channel-based workflow?

A common pattern is to discover candidate videos with YouTube Channel Videos Scraper - Metadata & Metrics, review the returned video URLs, and then run this downloader on the selected URLs.

What controls output size and workflow scope?

maxDurationMinutes and maxFileSizeMb are the main scope controls. videoQuality, preferredContainer, and audioFormat then shape the saved output format.

Related Actors

• Then use YouTube Channel Videos Scraper - Metadata & Metrics - Useful when your workflow starts with channel-level discovery and the next step is selecting specific video URLs to download or probe with this Actor.

Responsible use

Use this Actor for videos you own, videos you have permission to copy, or videos you are otherwise legally allowed to download. Review the applicable YouTube terms, copyright rules, privacy requirements, and your internal usage policies before running it. This Actor is intended for permitted media handling within those rules.