# Vimeo Public Video Downloader (`automation-lab/vimeo-public-video-downloader`) Actor

Download authorized public Vimeo videos as stored MP4 files and export provenance, quality, size, and retrieval metadata.

- **URL**: https://apify.com/automation-lab/vimeo-public-video-downloader.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## 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

## Vimeo Public Video Downloader

Download authorized, anonymously playable public Vimeo videos and export stored MP4 files with provenance metadata.
This **Vimeo video downloader** resolves owner-enabled progressive MP4 renditions, stores selected files in Apify, and returns video ID, title, creator, duration, format, resolution, byte size, source URL, and retrieval status.

No Vimeo login, cookies, browser, proxy, or user API key is required.
Private, login-only, Vimeo On Demand, adaptive-only, and DRM-protected Vimeo videos are outside scope.

### What can the Vimeo Public Video Downloader do?

- Process exact public `vimeo.com` and `player.vimeo.com` video URLs.
- Resolve owner-enabled progressive MP4 renditions from public Vimeo player data.
- Select the best, lowest, or nearest rendition at or below a requested height.
- Stream a selected MP4 into the run key-value store with a byte limit.
- Export metadata and an expiring source media URL without storing video bytes.
- Preserve title, creator, duration, dimensions, thumbnail, and source provenance.
- Deduplicate repeated Vimeo video IDs within one run.
- Continue after an individual bad URL and fail clearly if every URL fails.
- Process up to 100 supplied Vimeo videos per run.

This is a supplied-URL archiver. It does not search Vimeo, crawl creators, download private showcases, or bypass access controls.

### Who is this Actor for?

**Creators and rights holders** can preserve their own anonymously playable Vimeo videos with source context.

**Production and editorial teams** can archive approved campaign or portfolio assets in repeatable runs.

**Researchers and journalists** can build a documented inventory of public videos they are permitted to retain.

**Developers and data engineers** can convert reviewed Vimeo URLs into JSON records plus stored MP4 files.

**Compliance and records teams** can schedule bounded archives and track retrieval outcomes over time.

### Why use this Vimeo video downloader?

A manual download provides a file but usually not a stable machine-readable record connecting the file to its source, creator, quality, and retrieval time.
This Actor keeps the selected media and its provenance together.

The implementation uses Vimeo's anonymous player configuration and public CDN renditions.
It does not launch a browser or automatically enable paid proxy traffic.
Use `saveVideos: false` when you need a low-transfer inventory instead of copied media.

### Supported Vimeo URLs and videos

Supported URL shapes include:

```text
https://vimeo.com/<video-id>
https://vimeo.com/<video-id>/<unlisted-hash>
https://player.vimeo.com/video/<video-id>
https://player.vimeo.com/video/<video-id>?h=<unlisted-hash>
```

The video must be anonymously playable and expose at least one owner-enabled progressive MP4.
The Actor intentionally rejects private, password-protected, login-only, On Demand, DRM-only, and adaptive-only media.
It does not decrypt HLS/DASH streams or solve human-verification challenges.

### Extracted Vimeo video data

| Field | Meaning |
| --- | --- |
| `videoId` | Stable Vimeo video identifier |
| `title` | Public video title |
| `creator` | Public Vimeo creator or owner name |
| `durationSeconds` | Video duration in seconds |
| `width`, `height` | Selected MP4 rendition dimensions |
| `quality` | Vimeo quality label for the selected rendition |
| `format` | Selected media container, currently `mp4` |
| `sourceUrl` | Canonical public Vimeo page URL |
| `sourceMediaUrl` | Expiring Vimeo CDN URL resolved during the run |
| `thumbnailUrl` | Public Vimeo thumbnail URL |
| `videoFileKey` | Key of the stored MP4, or `null` in resolve-only mode |
| `videoFileUrl` | Apify key-value store record URL |
| `videoSizeBytes` | Number of bytes copied to storage |
| `retrievalStatus` | `downloaded`, `resolved`, or `failed` |
| `error` | Concise per-URL failure reason, otherwise `null` |
| `retrievedAt` | ISO 8601 retrieval timestamp |

Missing upstream values are returned as `null`, never guessed.

### How to download a public Vimeo video

1. Confirm the video opens while logged out and that you may download it.
2. Copy the exact Vimeo video URL.
3. Open this Actor in Apify Console.
4. Add the URL under **Public Vimeo video URLs**.
5. Keep **Save video files** enabled.
6. Choose a preferred quality and safe file-size limit.
7. Click **Start**.
8. Open **Vimeo video archives** for the metadata record.
9. Open **Downloaded Vimeo videos** for the stored MP4.

The prefilled URL is a real public sample suitable for a first run, but public source availability can change.

### Input parameters

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `startUrls` | array | required | One or more exact HTTPS Vimeo video URLs |
| `saveVideos` | boolean | `true` | Store selected MP4 files; disable for metadata/link resolution |
| `preferredQuality` | string | `best` | `best`, `lowest`, or up to 360p, 540p, 720p, or 1080p |
| `maxItems` | integer | `10` | Maximum unique supplied videos processed, 1–100 |
| `maxVideoSizeMb` | integer | `250` | Maximum stored file size, 1–500 MB |
| `maxRequestRetries` | integer | `2` | Bounded transient request retries, 0–5 |

Example:

```json
{
  "startUrls": [
    { "url": "https://vimeo.com/143603739" }
  ],
  "maxItems": 1,
  "saveVideos": true,
  "preferredQuality": "lowest",
  "maxVideoSizeMb": 100
}
```

### Output example

This abbreviated example reflects a real resolved public video:

```json
{
  "videoId": "143603739",
  "title": "The Shoes - Submarine Feat. Blaine Harrison",
  "creator": "Karim Huu Do",
  "durationSeconds": 336,
  "width": 480,
  "height": 270,
  "quality": "240p",
  "format": "mp4",
  "sourceUrl": "https://vimeo.com/143603739",
  "sourceMediaUrl": "https://vod-progressive-ak.vimeocdn.com/.../432085185.mp4",
  "thumbnailUrl": "https://i.vimeocdn.com/video/...",
  "videoFileKey": "video-143603739-240p.mp4",
  "videoFileUrl": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/video-143603739-240p.mp4",
  "videoSizeBytes": 17059259,
  "retrievalStatus": "downloaded",
  "error": null,
  "retrievedAt": "2026-08-19T14:52:23.267Z"
}
```

Default run storage is private.
Authenticate when opening API file URLs, or copy files to storage you control.

### Where are downloaded Vimeo videos stored?

Successful files use this key pattern in the default key-value store:

```text
video-<video-id>-<quality>.mp4
```

The Actor preserves Vimeo's progressive MP4 without re-encoding, watermarking, or modifying it.
The source media URL can expire; the run-owned key-value store record is the durable output for that run's retention period.

### How much does it cost to download Vimeo videos?

The Actor uses pay-per-event pricing: one **$0.005** start event and one `item` event for each successfully resolved public Vimeo video.
Failed and duplicate URLs have no item charge.
Saving a video does not create a second event, although normal platform transfer and storage usage increase with file size.

The current per-item tiers are:

| Tier | Successful video record |
| --- | ---: |
| FREE | $0.0027508 |
| BRONZE | $0.002392 |
| SILVER | $0.0018658 |
| GOLD | $0.0014352 |
| PLATINUM | $0.0009568 |
| DIAMOND | $0.00066976 |

At BRONZE, one successful video is about **$0.007392**, 10 are about **$0.02892**, and 100 are about **$0.2442**, before ordinary Apify storage and transfer usage.
Final cost is the start event plus successful records at your account tier.

### Resolve Vimeo videos without copying media

Set `saveVideos: false` to export metadata and the currently resolved CDN URL without copying video bytes.
This is useful for inventories, validation, downstream download systems, and workflows where lower transfer matters.

The CDN URL is temporary.
Do not treat it as permanent storage.
The `item` event is unchanged because the Actor still resolves and emits the complete typed video record.

### Batch and scheduled archival workflows

Supply a bounded list of approved public video URLs and save the input as an Apify Task.
Schedule that Task when recurring archive snapshots are required.

Use `videoId` as the stable deduplication key in your destination.
Copy files before your Apify storage retention expires.
A later `failed` status can indicate removal, a privacy change, loss of a progressive rendition, or a temporary source error; the Actor does not infer legal or editorial meaning.

The Actor does not discover new creator uploads or compare prior runs automatically.

### Integrations and export workflows

Send dataset records and authorized files to:

- Amazon S3, Google Cloud Storage, or Azure Blob Storage;
- Airtable, Notion, or Google Sheets for an archive index;
- a webhook for transcription, cataloging, or review;
- a database keyed by `videoId`;
- an approved media asset management system.

Pass authenticated storage access or copy the bytes when a destination cannot read private Apify run storage.

### Run with the Apify API

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~vimeo-public-video-downloader/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls":[{"url":"https://vimeo.com/143603739"}],"maxItems":1,"saveVideos":true,"preferredQuality":"lowest","maxVideoSizeMb":100}'
```

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/vimeo-public-video-downloader').call({
  startUrls: [{ url: 'https://vimeo.com/143603739' }],
  maxItems: 1,
  saveVideos: true,
  preferredQuality: 'lowest',
  maxVideoSizeMb: 100,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("automation-lab/vimeo-public-video-downloader").call(run_input={
    "startUrls": [{"url": "https://vimeo.com/143603739"}],
    "maxItems": 1,
    "saveVideos": True,
    "preferredQuality": "lowest",
    "maxVideoSizeMb": 100,
})
print(client.dataset(run["defaultDatasetId"]).list_items().items)
```

Keep API tokens in environment variables or a secret manager.

### Use with Apify MCP

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/vimeo-public-video-downloader"
```

#### Claude Desktop setup

Add this configuration to Claude Desktop:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/vimeo-public-video-downloader"
    }
  }
}
```

#### Cursor setup

Add the same MCP server URL in **Cursor Settings → MCP**.

#### VS Code setup

Add the same MCP server URL through your VS Code MCP extension or workspace MCP configuration.

Example prompts:

- "Download this authorized public Vimeo video at the lowest available quality and return its stored file metadata."
- "Resolve these approved Vimeo URLs without copying media and export an archive inventory."
- "Archive this bounded Vimeo video list with a 100 MB file limit."

### Reliability, limits, and failure behavior

The Actor first tries Vimeo's structured player config route, then extracts the same configuration from bounded public player HTML when the config endpoint is challenged.
It validates the returned video ID and accepts only HTTPS progressive media hosted by Vimeo's CDN.

Transient network, rate-limit, and server failures are retried a bounded number of times.
No proxy or browser fallback is enabled.

A bad URL produces an uncharged `failed` record and a concise log message.
Successful URLs remain available when another URL fails.
The run exits with failure when no URL succeeds.

### Troubleshooting

#### Why was my Vimeo video rejected?

Open it in a logged-out browser.
Confirm it is one exact video URL and that the owner exposes a progressive MP4.
Private, password-protected, login-only, On Demand, adaptive-only, and DRM-only videos are unsupported.

#### Why is the file URL unauthorized?

Run storage is private by default.
Open it while authenticated in Apify Console or make an authorized API request with your token.

#### Why did an oversized video fail?

It exceeded `maxVideoSizeMb`.
Raise the limit only when you have budgeted the additional transfer, memory for local runs, and storage.

#### Why is `videoFileUrl` null?

`saveVideos` was disabled, or retrieval failed.
A successful resolve-only item has `retrievalStatus: "resolved"` and still includes `sourceMediaUrl`.

### Responsible and legal use

Use this Actor only for public Vimeo media you are legally allowed to access, download, retain, and process.
Respect copyright, privacy, publicity rights, contractual restrictions, Vimeo's terms, and applicable law.

Do not use it to bypass passwords, login requirements, payment, geographic controls, DRM, or human-verification challenges.
Do not redistribute media without permission.
Minimize retained personal data, restrict file access, choose an appropriate retention period, and honor valid deletion requests.
This tool does not grant rights to third-party content.

### Related automation-lab Actors

- [Vimeo Transcript Scraper](https://apify.com/automation-lab/vimeo-transcript-scraper) — export available Vimeo captions as text, SRT, or VTT instead of saving video media.
- [Video to Text Transcriber](https://apify.com/automation-lab/video-to-text-transcriber) — transcribe an authorized saved video in a separate workflow.
- [M3U8 Playlist Downloader](https://apify.com/automation-lab/m3u8-playlist-downloader) — process an authorized direct public HLS playlist when you already have the playlist URL.

These products do not replace this Actor's exact Vimeo URL-to-progressive-MP4 archival workflow.

### FAQ

#### Does this Actor require a Vimeo account?

No.
It supports only anonymously reachable public Vimeo player data and owner-enabled progressive MP4s.

#### Can it search Vimeo or crawl a creator profile?

No.
Supply exact video URLs.
Use a separate Vimeo discovery Actor before this one when your workflow starts from a creator or keyword.

#### Does it bypass Vimeo On Demand or DRM?

No.
Paid, login-only, encrypted, and adaptive-only video is intentionally rejected.

#### Are failed or duplicate URLs charged as items?

No.
Only successfully resolved public video records create the `item` event.
The one-time start event still applies once per run.

#### Can I keep downloaded files permanently?

Apify storage retention depends on your plan.
Copy files to durable storage you control when you need longer retention.

# Actor input Schema

## `startUrls` (type: `array`):

HTTPS vimeo.com video or player URLs. Private, login-only, Vimeo On Demand, and DRM-only videos are rejected.

## `saveVideos` (type: `boolean`):

Store selected MP4 files in the run key-value store. Disable to resolve metadata and expiring media URLs only.

## `preferredQuality` (type: `string`):

Select the best, lowest, or nearest available MP4 resolution at or below a requested height.

## `maxItems` (type: `integer`):

Maximum number of unique supplied videos to process.

## `maxVideoSizeMb` (type: `integer`):

Stop a stored-file download if it exceeds this size.

## `maxRequestRetries` (type: `integer`):

Retries for temporary network, rate-limit, and Vimeo server failures.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://vimeo.com/143603739"
    }
  ],
  "saveVideos": true,
  "preferredQuality": "best",
  "maxItems": 10,
  "maxVideoSizeMb": 250,
  "maxRequestRetries": 2
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing retrieval status and provenance metadata.

## `files` (type: `string`):

Key-value store containing successfully downloaded MP4 files.

# 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 = {
    "startUrls": [
        {
            "url": "https://vimeo.com/143603739"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/vimeo-public-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 = { "startUrls": [{ "url": "https://vimeo.com/143603739" }] }

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/vimeo-public-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 '{
  "startUrls": [
    {
      "url": "https://vimeo.com/143603739"
    }
  ]
}' |
apify call automation-lab/vimeo-public-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/vimeo-public-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/vfePMzaXp75CbVZOR/builds/H0JJdein7JdbyV0VD/openapi.json