# YouTube Video Downloader PRO (`xtech/youtube-video-downloader`) Actor

Save authorized YouTube videos in batches with searchable metadata, resolution control, per-URL results, and clear retry diagnostics. Optional cookies and proxy recovery are available for content you are allowed to access.

- **URL**: https://apify.com/xtech/youtube-video-downloader.md
- **Developed by:** [Xtech](https://apify.com/xtech) (community)
- **Categories:** Automation, E-commerce, Social media
- **Stats:** 362 total users, 0 monthly users, 48.4% runs succeeded, 14 bookmarks
- **User rating**: 2.60 out of 5 stars

## Pricing

$20.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period. You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#rental-actors

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## YouTube Video Downloader

Save videos you own or are authorized to download, together with searchable metadata and a temporary direct download link.

### What it does

- Process one or many YouTube video URLs in a single run
- Choose a maximum video resolution from 360p up to 4K
- Receive the title, channel, duration, description, view count, thumbnail, and download result
- Save each successful video to the run’s key-value storage and return a direct retrieval link
- Use optional cookies for content you are authorized to access, such as your own age-restricted videos
- Use a proxy when regional availability or rate limits require it

### Best for

- Create an offline copy of videos you own or have permission to archive
- Build a metadata catalog before sending videos to a transcript, caption, or analysis workflow
- Download a small batch of approved videos with one consistent resolution limit

This Actor does not bypass paywalls, private access controls, or YouTube’s policies. Use it only for content you are allowed to save.

### Get started

Add one or more direct video URLs, choose the largest resolution you want, then run the Actor. The input form includes a public test video so you can verify the output before using your own URLs.

```json
{
  "urls": [
    { "url": "https://www.youtube.com/shorts/vVoMLnsbQqE" }
  ],
  "resolution": "720p"
}
```

For age-restricted videos you own or are authorized to access, paste a Netscape-format `cookies.txt` value into the secret `cookies` field. The input form and reliable preset below enable Residential proxy because YouTube currently blocks Apify datacenter extraction. The Actor tries the signed media transfer directly first and falls back to proxy transfer only when YouTube rejects it; proxy transfer can materially increase run cost.

### Pricing

The Actor is **$20 per month** with a **24-hour trial**. Proxy traffic and Apify platform usage are separate, so start with the bundled 25-second sample before processing longer videos.

### Ready-to-run presets

Reliable single-video cloud check:

```json
{
  "urls": [{ "url": "https://www.youtube.com/shorts/vVoMLnsbQqE" }],
  "resolution": "360p",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

Approved batch at a consistent quality:

```json
{
  "urls": [
    { "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ" },
    { "url": "https://www.youtube.com/watch?v=G56v017spr0" }
  ],
  "resolution": "720p"
}
```

Authorized recovery for a region-limited source:

```json
{
  "urls": [{ "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ" }],
  "resolution": "720p",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

Add authorized cookies only in the secret `cookies` input; never place them in a task description or shared preset.

### Results

Each input video produces one dataset item. Successful items include the video details and a link to the saved file. Failed items keep the original URL and include a sanitized `error` message so you can adjust the URL, cookies, access settings, resolution, or proxy choice. A run can contain both successful and failed items; inspect `error` per row before treating a batch as complete. If every valid input fails, the Actor marks the run **FAILED after writing the error rows** instead of reporting a misleading successful batch. Each run also writes a `RUN_SUMMARY` key-value record with requested, successful, failed, resolution, and proxy-enabled counts.

Malformed or non-YouTube URLs are retained as `Invalid YouTube URL` error rows and
are not sent through yt-dlp retries. This keeps a typo from consuming runtime or
proxy traffic while preserving a clear correction path in the dataset.

Example successful row:

```json
{
  "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
  "video_id": "aqz-KE-bpKQ",
  "title": "Big Buck Bunny 60fps 4K - Official Blender Foundation Short Film",
  "channel": "Blender",
  "duration": 120,
  "download_url": "https://api.apify.com/v2/key-value-stores/%3Cstore-id%3E/records/aqz-KE-bpKQ",
  "error": null
}
```

The download link points to the Actor run’s key-value store and is subject to your Apify data-retention period. Download or copy the file while the run storage is retained.

### Good to know

Only download content that you own or have permission to save. Availability, formats, and access rules are determined by YouTube and the video owner.

### Troubleshooting

- YouTube JavaScript challenge: the Actor bundles yt-dlp's EJS challenge solver and enables the bundled Deno runtime automatically. If YouTube still asks for sign-in, use authorized cookies or retry with the Residential proxy path below.
- `yt-dlp failed`: confirm the URL is a direct YouTube video URL, then retry with a lower resolution.
- Age-restricted or private video: provide authorized Netscape cookies; do not paste cookies into the public input or README.
- Region or rate-limit error: enable Apify Proxy and retry with a small batch.
- Bot-check or `403 Forbidden`: use Apify Proxy with the `RESIDENTIAL` group. The Store example enables this because the no-proxy cloud check is currently blocked. The Actor attempts direct media transfer after proxied extraction to reduce proxy bandwidth, but if YouTube binds the signed URL to the extraction IP, media transfer also uses the proxy and can materially increase run cost.
- Proxy cost: a 10-minute 360p canary used about `$0.324` when YouTube required proxied media transfer. The bundled first-run sample is only 25 seconds to keep validation bandwidth substantially lower; your cost scales with the selected video and format size.
- Memory: the default 1 GB run size is designed for ordinary downloads. Very large files may need a larger run memory setting; the Actor rejects files above 800 MB.
- Missing `download_url`: the video metadata was returned with an error; inspect the row’s `error` field and run status rather than retrying blindly.

### Related Actors

- [YouTube Transcript Scraper Pro](https://apify.com/xtech/youtube-transcript-scraper-pro) — turn approved videos into searchable transcripts.
- [YouTube Shorts Downloader Pro](https://apify.com/xtech/youtube-shorts-downloader-pro) — handle short-form videos in the same workflow.

# Actor input Schema

## `urls` (type: `array`):

Required. Add one or more public YouTube video URLs you own or are authorized to save.

## `resolution` (type: `string`):

Downloads the best quality not exceeding this height.

## `cookies` (type: `string`):

Paste Netscape-format cookies.txt content only for videos you are authorized to access. This value is stored as a secret.

## `proxyConfiguration` (type: `object`):

Residential proxy is prefilled for reliable cloud extraction. The Actor tries direct media transfer first and uses proxy transfer only when YouTube rejects that route. Proxy transfer can materially increase run cost.

## Actor input object example

```json
{
  "urls": [
    {
      "url": "https://www.youtube.com/shorts/vVoMLnsbQqE"
    }
  ],
  "resolution": "480p",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Items stored in the default dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        {
            "url": "https://www.youtube.com/shorts/vVoMLnsbQqE"
        }
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("xtech/youtube-video-downloader").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "urls": [{ "url": "https://www.youtube.com/shorts/vVoMLnsbQqE" }],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("xtech/youtube-video-downloader").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    {
      "url": "https://www.youtube.com/shorts/vVoMLnsbQqE"
    }
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call xtech/youtube-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xtech/youtube-video-downloader"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/QrdkHOap2H2LvbyZk/builds/rQXf7d14P4F6wvQah/openapi.json