# Pinterest Video Downloader (`agentx/pinterest-video-downloader`) Actor

Process one publicly accessible Pinterest Pin containing video for structured metadata and an optional stored video file.

- **URL**: https://apify.com/agentx/pinterest-video-downloader.md
- **Developed by:** [AgentX](https://apify.com/agentx) (community)
- **Categories:** Videos, E-commerce, Automation
- **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

Pinterest Video Downloader processes one accessible video Pin into normalized metadata and can optionally store the available media file in Apify.

- Two public inputs cover one Pin URL and an optional download preference.
- Four quality values provide metadata-only, low, medium, and high modes.
- Successful output follows a 39-field Dataset contract with thumbnail-first review.
- Comment retrieval is not exposed; the reserved `comments` array is normally empty.

**[Run one video Pin test](https://apify.com/agentx/pinterest-video-downloader)**

**[View the Apify API](https://apify.com/agentx/pinterest-video-downloader/api)**

Publish the Actor, replace the illustrative Pin, and test metadata before downloading.

### Why Choose This API

Pinterest Video Downloader defines a one-Pin workflow for video media. It maps available information to consistent fields for Pin identity, title or description, thumbnail, creator, publication time, counters, dimensions, audio labels, and processing provenance.

Metadata mode avoids file transfer. A download preference requests an available rendition, but the Pin determines the real resolution and format. The Actor cannot turn an image Pin into video or create an unavailable quality.

This is not a Pinterest board, profile, search, visual-search, shopping, Idea collection, or comments scraper. Those discovery and entity surfaces need separate tools.

### Quick Start Guide

The examples use an explicit URL-shaped placeholder:

```json
{
  "video_url": "https://www.pinterest.com/pin/476607573084562101/",
  "video_quality": "metadata"
}
```

Replace the zero identifier with a current public video Pin you may process. Open the URL in a private browser, confirm it contains playable video, and run metadata mode. Compare the returned ID, thumbnail, author, and description with the Pin.

An image Pin, board, profile, search page, or removed Pin is not a successful video test. Request a file only when metadata identifies the intended media. Process multiple Pins through separate runs.

### Input Parameters

| Parameter | Type | Required | Purpose |
|---|---|---:|---|
| `video_url` | string | Yes | One publicly accessible Pinterest Pin containing video. |
| `video_quality` | string | No | `metadata`, `low`, `medium`, or `high`; metadata skips storage. |

The required URL has matching prefill and example values. The optional quality field has no prefill or example and uses metadata when omitted.

There is no board, profile, query, date, country, login, cookie, batch, product, image, or comment control. Additional properties are rejected.

### Output Data Schema

The Dataset contains 39 possible fields:

| Area | Fields |
|---|---|
| Pin media | `thumbnail`, `id`, `platform`, `title`, `description`, `duration`, `published_at` |
| Creator | `author`, `author_id`, `author_url` |
| Labels and counters | `categories`, `tags`, `view_count`, `like_count`, `shares_count`, `dislike_count`, `comment_count` |
| Media properties | `width`, `height`, `fps`, `audio_title`, `audio_artist`, `video` |
| Reserved and provenance | `comments`, `processed_at`, `processor` |

Abbreviated shape for the same placeholder:

```json
{
  "id": "000000000000000000",
  "platform": "Pinterest",
  "title": "Example Pinterest video Pin",
  "author": "Example creator",
  "thumbnail": "https://example.com/pinterest-thumbnail.jpg",
  "comments": [],
  "video": ""
}
```

This illustrates the schema, not a live response. Pinterest may omit cross-platform fields. Metadata mode returns no stored file. The public input does not retrieve comments.

Source-dependent fields also present in every item:

| Field | Meaning |
|---|---|
| `source_url` | Canonical page URL of the item on its own platform |
| `media_type` | Kind of media the source reports, such as video or audio |
| `live_status` | Whether the item is a recording, currently live, or a finished stream |
| `availability` | Source visibility, such as public, unlisted, or needs\_auth |
| `age_limit` | Minimum viewer age the source enforces; zero means no restriction |
| `language` | Primary language of the item as reported by the source |
| `followers` | Follower or subscriber count of the author at processing time |
| `is_verified` | Whether the author's account carries a verified badge |
| `saves_count` | Times viewers saved the item, on sources that expose it |
| `file_ext` | Container extension of the selected media, such as mp4 or webm |
| `file_size` | Size of the selected media in bytes, exact or approximate |
| `subtitles` | Language codes of published subtitle tracks; auto-captions excluded |
| `chapters` | Chapter markers with title and start and end time in seconds |

### Integration Examples

The intended reference is `agentx/pinterest-video-downloader`.submit the same scenario over HTTP:

```bash
curl -X POST "https://api.apify.com/v2/acts/agentx~pinterest-video-downloader/runs?token=$APIFY_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"video_url":"https://www.pinterest.com/pin/476607573084562101/","video_quality":"metadata"}'
```

Matching hosted MCP setup:

```json
{
  "mcpServers": {
    "apify-pinterest-video": {
      "url": "https://mcp.apify.com?tools=agentx/pinterest-video-downloader",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  },
  "exampleToolArguments": {
    "video_url": "https://www.pinterest.com/pin/476607573084562101/",
    "video_quality": "metadata"
  }
}
```

Publication is required for discovery. Keep tokens private and follow the [Apify MCP documentation](https://docs.apify.com/integrations/mcp).

### Pricing & Cost Calculator

Local metadata declares these events, not a verified Store offer:

| Event | Billing unit | Local price |
|---|---|---:|
| `actor_usage` | Metered runtime, proxy, and storage usage | $0.00001 |
| `metadata` | One successfully processed metadata result | $0.07 |
| `download` | One successfully processed result with stored video | $0.16 |

The smallest metadata result declares $0.07 plus metered usage. A download declares $0.16 plus metered usage.

### Use Cases & Applications

Creative teams can preserve an authorized video Pin and its source metadata for review. Researchers can document one cited public Pin. Developers can send the Dataset item to a webhook or catalog. AI teams can pass a permitted stored file to a transcript or classification workflow.

Repeated metadata runs can observe currently exposed values, but the Actor does not monitor a board or calculate changes. Keep the Pin URL and returned ID with every observation.

### Limits & Troubleshooting

Removed Pins, private boards, login gates, age or region restrictions, image-only content, unavailable renditions, rate limits, and platform changes can block processing. No Pinterest credential or country selector exists.

If no result appears, replace open the exact Pin privately, and confirm it contains video. Retry metadata. If download mode has no `video`, inspect logs and storage and verify metadata still succeeds.

Before release, test a public video Pin, image Pin, board URL, private/removed Pin, placeholder, and one download. Record extractor, ID, thumbnail, requested mode, terminal status, and file outcome.

### FAQ

#### Can it download an entire Pinterest board?

No. One video Pin is accepted per run.

#### Does it process image Pins?

No. The documented output is video metadata and optional video storage.

#### Does it retrieve comments?

No comment input exists; the reserved list is normally empty.

#### Can it access private boards?

No login or cookie field is exposed.

#### Does high guarantee a resolution?

No. The Pin’s available renditions determine the result.

#### Why are fields null?

Pinterest did not expose those values. Null is not zero.

#### Can I schedule it?

Yes, but each run reprocesses one Pin.

#### How do I tell a video Pin from an image Pin?

Open the Pin and check whether it plays. Only Pins whose primary media is a video produce a Dataset item; an image Pin has no media manifest, so the run ends without a record and charges no result event. Submit the canonical `pinterest.com/pin/<id>/` address rather than a board or search URL.

### Legal & Responsible Use

Process only Pins you are authorized to access, download, and retain. The caller is responsible for Pinterest terms, copyright, privacy, applicable law, and retention policy.

### Related Tools

- [Video to Social Post](https://apify.com/agentx/video-to-social-post) helps repurpose authorized media.
- [Video Transcript](https://apify.com/agentx/video-transcript) converts authorized speech to text.
- [Video Captions Downloader](https://apify.com/agentx/video-captions-downloader) retrieves available captions.
- [All Video Scraper](https://apify.com/agentx/all-video-scraper) accepts supported URLs from multiple hosts.

### Support & Community

- [AgentX community](https://t.me/Apify_Actor)
- [Contact the AgentX team](https://t.me/AiAgentApi)
- [Apify Actor dashboard](https://apify.com/agentx/pinterest-video-downloader)
- [Apify API reference](https://apify.com/agentx/pinterest-video-downloader/api)
- [Apify MCP documentation](https://docs.apify.com/integrations/mcp)

Include the stable ID, redacted Pin URL, input, and run ID in support requests.

**[Run one video Pin test](https://apify.com/agentx/pinterest-video-downloader)**

**[View the Apify API](https://apify.com/agentx/pinterest-video-downloader/api)**

# Actor input Schema

## `video_url` (type: `string`):

Publicly accessible Pinterest Pin URL containing video.

## `video_quality` (type: `string`):

Preferred download quality, or metadata-only mode without a video file.

## Actor input object example

```json
{
  "video_url": "https://www.pinterest.com/pin/476607573084562101/"
}
```

# Actor output Schema

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

All video details and optional download links with full engagement stats and comments

# 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 = {
    "video_url": "https://www.pinterest.com/pin/476607573084562101/"
};

// Run the Actor and wait for it to finish
const run = await client.actor("agentx/pinterest-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 = { "video_url": "https://www.pinterest.com/pin/476607573084562101/" }

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

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

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

```

## CLI example

```bash
echo '{
  "video_url": "https://www.pinterest.com/pin/476607573084562101/"
}' |
apify call agentx/pinterest-video-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=agentx/pinterest-video-downloader",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/lwJLdjKYiHYlZOn17/builds/0l9ijRmHiI0H8E5ls/openapi.json