YouTube Video Downloader and Metadata Extractor

Download a public YouTube video or its audio when the public watch page provides accessible media, save the file to the run's key-value store, and receive a dataset row with source metadata and properties measured from the saved file. Optional cloud-storage settings save additional copies. The actor accepts up to 100 video links per run.

The input form is prefilled with YouTube's public video Me at the zoo. The prefill is a convenient example link; it does not guarantee that a video will be available from every run's network.

Run the actor

1. Open Input and add one or more video links under Videos.
2. Choose a format and adjust the optional limits if needed.
3. Add proxy or cloud-storage settings only if you need them.
4. Select Save & Start. When the run finishes, open Storage → Dataset for saved video records and Key-value store → OUTPUT_SUMMARY for the run summary.

Input

videos is required and accepts one to 100 objects, each containing only a url field. Supported links are HTTPS YouTube watch, Shorts, embed, and youtu.be video links. The actor validates the video ID, converts accepted links to the canonical YouTube watch URL, and downloads duplicate video IDs only once, keeping their first position. It does not accept channel, playlist, or search pages.

Field	Type	Required?	Default	What it does
videos	Array of { "url": string } objects	Required; 1–100 items	One public video link is prefilled	Videos to download. Each URL must identify one video.
preferredQuality	String	Optional	720p	Maximum requested video height. Choices: 144p, 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p. Audio-only formats ignore this setting.
preferredFormat	String	Optional	mp4	Requested container or audio format. Choices: avi, flv, mkv, mov, mp4, webm, aac, aiff, alac, flac, m4a, mka, mp3, ogg, opus, vorbis, wav.
filenameTemplateParts	Array of strings	Optional; 1–3 unique values	["title"]	Adds selected title, uploader, or timestamp after the video ID in the saved filename. The final name is sanitized.
maxFileSizeMbytes	Integer	Optional; 1–512	128	Maximum file size in megabytes. Larger files are skipped.
maxDurationSeconds	Integer	Optional; 1–7200	900	Maximum duration for videos whose duration is available before download.

ALAC is saved in an .m4a container, Vorbis in .ogg, and MKA in a Matroska audio container. Audio conversions use FFmpeg when needed. The result's format reports the selected format or codec, while the filename uses the saved container's extension.

Proxy and cloud storage

Direct connections are used by default. proxyConfiguration uses the standard Apify proxy editor. Enable Use Apify Proxy to select managed proxy groups or a country, or supply custom HTTP(S) proxy URLs. Managed settings and custom URLs cannot be combined. The input is validated before the Actor uses it. Apify Proxy may incur charges under your account's current plan.

Proxy setting	Type	Default	What it does
useApifyProxy	Boolean	false	Uses an Apify-managed proxy when set to true.
apifyProxyGroups	Array of strings	None	Up to 10 managed proxy group names; requires useApifyProxy: true.
apifyProxyCountry	Two-letter string	None	Managed proxy country code; requires useApifyProxy: true.
proxyUrls	Array of HTTP(S) URLs	None	Up to 25 custom proxy origins, each up to 2,048 characters. Use an origin only, without a path, query, or fragment. Proxy URL credentials are accepted but are not returned in the dataset.

Field	Type	Required?	Default	What it does
proxyConfiguration	Object	Optional	{ "useApifyProxy": false }	Configures the standard Apify proxy editor. Managed groups and a country require useApifyProxy: true; custom proxy URLs are limited to 25 origin URLs.
s3AccessKeyId	Secret string	Optional; requires the other S3 fields	None	AWS access key ID.
s3SecretAccessKey	Secret string	Optional; requires the other S3 fields	None	AWS secret access key.
s3Bucket	String	Optional; requires the other S3 fields	None	Existing S3 bucket. Objects are uploaded with private access.
s3Region	String	Optional	us-east-1	AWS region. Use lowercase letters, numbers, and hyphens.
azureConnectionString	Secret string	Optional; requires azureContainerName	None	Azure Storage connection string.
azureContainerName	String	Optional; requires azureConnectionString	None	Azure Blob Storage container.
googleCloudServiceKey	Secret string	Optional; requires googleCloudBucketName	None	Google Cloud service-account JSON.
googleCloudBucketName	String	Optional; requires googleCloudServiceKey	None	Google Cloud Storage bucket.

For each provider, enter its complete set of settings. Every validated media file is saved in the run's default key-value store under its generated filename. Configured cloud providers receive additional copies, and successful uploads add their URLs to the dataset row. If one provider succeeds and another configured provider fails, the saved result can still include the successful link and the run can be marked partial. Keep credentials in secret input fields; do not put them in shared input files or examples. Cloud object access follows the permissions and policies in your storage account; S3 uploads are private.

Results

The dataset contains one row per video file that was successfully saved. Failed downloads do not create rows. Optional metadata is omitted when the source does not provide it.

An acknowledged run result is not yet available for a complete dataset example. The dataset example below therefore shows the correct empty-array form, not a sample video record.

[]

The result is mostly flat. categories, tags, subtitleLanguages, and thumbnails are arrays of strings; chapters is an array of objects with a title, start time, and optional end time. A saved row requires videoId, url, title, filename, format, mimeType, fileSizeBytes, and fileSha256. Other metadata and storage links are optional.

Field	Type	Required?	Meaning
videoId	String	Required	Native YouTube video ID, checked against the video link.
url	URL string	Required	Canonical YouTube watch URL for this video.
title	String	Required	Video title.
filename	String	Required	Actual saved filename and key-value-store file key.
uploader	String	Optional	Uploader name published by YouTube.
uploaderId	String	Optional	Uploader identifier.
uploaderUrl	URL string	Optional	Public uploader page.
channel	String	Optional	Channel name published by YouTube.
channelId	String	Optional	Native YouTube channel ID.
channelUrl	URL string	Optional	Public channel page.
channelFollowerCount	Integer	Optional	Channel follower count when available.
channelIsVerified	Boolean	Optional	Whether YouTube marks the channel as verified.
duration	Number	Optional	Duration reported in video metadata, in seconds.
durationFormatted	String	Optional	Source duration as a readable time string.
mediaDuration	Number	Optional	Duration measured from the downloaded file, in seconds.
uploadDate	Date string	Optional	Upload date reported by YouTube.
timestamp	Integer	Optional	Upload time as Unix seconds.
releaseDate	Date string	Optional	Release date reported by the source.
releaseTimestamp	Integer	Optional	Release time as Unix seconds.
viewCount	Integer	Optional	Video view count.
likeCount	Integer	Optional	Video like count.
commentCount	Integer	Optional	Video comment count.
description	String	Optional	Full video description, including source-published chapter text when present.
categories	Array of strings	Optional	Video categories published by YouTube.
tags	Array of strings	Optional	Video tags or keywords published by YouTube.
tagCount	Integer	Optional	Number of source-published tags retained in tags.
language	String	Optional	Video language.
availability	String	Optional	Availability status reported by the source.
ageLimit	Integer	Optional	Age restriction when provided.
license	String	Optional	Video license reported by the source.
liveStatus	String	Optional	Live-stream status reported for the video.
wasLive	Boolean	Optional	Whether YouTube identifies the video as a past live stream.
thumbnailUrl	URL string	Optional	Primary public thumbnail image.
thumbnails	Array of URL strings	Optional	Public thumbnail image URLs.
thumbnailCount	Integer	Optional	Number of thumbnail URLs retained in thumbnails.
subtitleLanguages	Array of strings	Optional	Subtitle language labels. Caption URLs are not included.
chapters	Array of objects	Optional	Source-published chapters in order. Each has required title (string) and startTime (number of seconds), plus optional endTime (number of seconds).
format	String	Required	Format verified for the saved file.
mimeType	String	Required	MIME type matching the saved format.
fileSizeBytes	Integer	Required	Positive size measured from the saved file, in bytes.
fileSha256	String	Required	SHA-256 checksum of the saved file.
width	Integer	Optional	Video width measured from the saved file, in pixels.
height	Integer	Optional	Video height measured from the saved file, in pixels.
fps	Number	Optional	Frame rate measured from the saved file.
videoCodec	String	Optional	Video codec measured from the saved file.
audioCodec	String	Optional	Audio codec measured from the saved file.
audioChannels	Integer	Optional	Audio channel count measured from the saved file.
audioSampleRate	Integer	Optional	Audio sample rate measured from the saved file, in hertz.
bitRate	Integer	Optional	Overall media bit rate measured from the saved file, in bits per second.
s3Url	URL string	Optional	S3 object locator when upload succeeds; it may require credentials to read.
azureUrl	URL string	Optional	Azure blob locator when upload succeeds; it may require credentials to read.
googleCloudUrl	URL string	Optional	Google Cloud Storage locator when upload succeeds; it may require credentials to read.
keyValueStoreUrl	URL string	Optional	Link to the file saved under its filename in the run's key-value store, when a real store ID is available.

You can download the dataset in formats such as JSON, CSV, or Excel.

Run summary

The run summary is stored separately from video rows under the exact key OUTPUT_SUMMARY in the default key-value store. It contains only these three fields:

{
  "status": "FAILED",
  "itemsStored": 0,
  "isPartial": false
}

This shows the summary shape for a run with no saved rows; it is not a report of a particular Actor run.

Field	Type	Meaning
status	String	SUCCEEDED when at least one dataset row is saved; otherwise FAILED.
itemsStored	Nonnegative integer	Number of successful dataset writes acknowledged during the run.
isPartial	Boolean	true when some work fails after at least one row has been saved.

Access and cost

• A video must be reachable from the run's network location. Private, removed, age-restricted, region-restricted, or otherwise unavailable videos may fail.
• YouTube may change its access requirements. A valid link does not guarantee a download. The actor uses public watch-page data and stops internal player API fallbacks that YouTube disallows in its robots guidance; it does not use account cookies or verification workarounds.
• Each download has a 120-second processing limit, including conversion and media checks. Optional provider copies have a 90-second limit each. A cloud run also stops early enough to save its results and summary before its configured timeout.
• Use only videos and content you are allowed to download, and follow YouTube's terms and your storage provider's terms.
• Costs depend on runtime, file size, selected quality, any FFmpeg conversion, proxy use, and cloud storage or transfer. Check current pricing in your Apify account and with your storage provider.