Pinterest Video Downloader API 🎬

Turn public Pinterest video Pins into direct, download-ready video URLs, MP4/HLS formats, and structured metadata for APIs and automation.

Paste one or more Pinterest Pin URLs, pin.it short links, or numeric Pin IDs. The Actor resolves the Pin, checks the recommended media URL, and returns a progressive MP4 when available, plus HLS variants, thumbnail, duration, dimensions, audio information, and optional Pin metadata.

• Direct video URLs: Use the returned URL in your app, automation, media pipeline, or download workflow.
• MP4-first selection: The recommended URL favors an accessible progressive MP4 over a less convenient HLS stream.
• No unnecessary file copying: Videos are not automatically copied into Apify storage, reducing storage overhead.
• One result per input: Successful, non-video, and failed inputs all produce a Dataset item in the original order.
• Simple result-based pricing: Each processed canonical Pin produces one billable result, while duplicate inputs are not charged again. Standard pricing is $2.90 per 1,000 results, or as low as $2.00 per 1,000 with eligible Apify Store discounts.

This Actor processes public Pin detail URLs only. It does not crawl boards or profiles, perform keyword search, transcribe audio, or bypass private content.

✨ Key features

Download-ready Pinterest video URLs

Get media.bestVideoUrl as the recommended URL for normal downloading or programmatic use. The Actor verifies that the selected media URL is reachable before returning a successful video result.

MP4 and HLS format discovery

When includeFormats is enabled, the output includes every detected video variant with its Pinterest quality identifier, format, MIME type, dimensions, duration, bitrate when available, thumbnail, and URL.

Useful media information

Receive the video thumbnail, duration in milliseconds, width, height, and hasAudio. Audio is reported only when it can be inferred reliably from the exposed HLS manifest; otherwise, hasAudio is null rather than a guess.

Optional Pin context

Keep includeMetadata enabled to receive the Pin title, description, creator, board, and available engagement signals. Disable it when you only need a compact video response. Top-level source, title, and description remain available for convenient Dataset and API use.

Batch processing with canonical de-duplication

Process up to 100 inputs per run. Duplicate inputs still receive their own Dataset records, while the same canonical Pin is processed and billed only once.

Native caption metadata

When includeCaptions is enabled, the Actor checks Pinterest-provided caption metadata and HLS subtitle declarations. It returns native track URLs when present. It does not generate transcripts or run speech recognition.

🚀 Quick input example

In Apify Console:

1. Open the Actor and click Try for free.
2. Keep the prefilled public video Pin or paste your own public Pinterest video Pin URL.
3. Click Start.
4. Open the run's Dataset tab and use media.bestVideoUrl.

{
  "urls": [
    "https://www.pinterest.com/pin/29695678789181460/"
  ]
}

The default settings include metadata, all detected video formats, and native caption checks.

Short output example

{
  "inputUrl": "https://www.pinterest.com/pin/29695678789181460/",
  "pinId": "29695678789181460",
  "source": "Pinterest",
  "title": "The most amazing places on earth",
  "description": null,
  "success": true,
  "status": "success",
  "media": {
    "type": "video",
    "bestVideoUrl": "https://v1.pinimg.com/videos/iht/expMp4/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d_720w.mp4",
    "thumbnailUrl": "https://i.pinimg.com/videos/thumbnails/originals/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d.0000000.jpg",
    "durationMs": 12100,
    "width": 720,
    "height": 1280,
    "hasAudio": true
  }
}

Input

Field	Type	Required	Default	Limits	What it does
urls	array of strings	Yes	One tested public video Pin	1–100 items	Accepts public Pinterest Pin URLs, supported regional Pinterest domains, pin.it short links, and numeric Pin IDs.
includeMetadata	boolean	No	true	—	Includes the full pin, creator, board, and engagement groups. Turn it off for a smaller video-focused response.
includeFormats	boolean	No	true	—	Includes all detected MP4 and HLS variants. Turn it off when you only need media.bestVideoUrl.
includeCaptions	boolean	No	true	—	Checks for native Pinterest caption or subtitle tracks and inspects HLS audio evidence. Turn it off to skip this optional enrichment.

At least one urls item is required. Empty strings and unsupported URLs return an individual error item rather than silently disappearing from the batch.

Duplicate inputs

The Actor canonicalizes supported Pinterest URLs and numeric IDs. Duplicate inputs remain separate Dataset items so input-to-output mapping stays clear, but equivalent inputs that resolve to the same canonical Pin generate only one result charge.

Input examples

One Pinterest video Pin

{
  "urls": [
    "https://www.pinterest.com/pin/29695678789181460/"
  ]
}

Numeric Pin ID and compact output

{
  "urls": [
    "29695678789181460"
  ],
  "includeMetadata": false,
  "includeFormats": false,
  "includeCaptions": false
}

Batch input

{
  "urls": [
    "https://www.pinterest.com/pin/29695678789181460/",
    "https://www.pinterest.com/pin/70437489674621/",
    "https://www.pinterest.com/pin/424605071126047814/"
  ],
  "includeMetadata": true,
  "includeFormats": true,
  "includeCaptions": true
}

🔌 API usage

The examples below start the Actor, wait for the run to finish, and read all items from its default Dataset. Store your token in the APIFY_TOKEN environment variable; never put a real token directly in source code.

JavaScript

import { ApifyClient } from 'apify-client';

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

const input = {
    urls: ['https://www.pinterest.com/pin/29695678789181460/'],
    includeMetadata: true,
    includeFormats: true,
    includeCaptions: true,
};

const run = await client.actor('lance_api/pinterest-video-downloader-api').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(items[0].media.bestVideoUrl);

Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])

run = client.actor('lance_api/pinterest-video-downloader-api').call(run_input={
    'urls': ['https://www.pinterest.com/pin/29695678789181460/'],
    'includeMetadata': True,
    'includeFormats': True,
    'includeCaptions': True,
})

items = list(client.dataset(run['defaultDatasetId']).iterate_items())
print(items[0]['media']['bestVideoUrl'])

Output

Every input produces one Dataset item. The most important fields are:

• success: whether a usable Pinterest video URL was resolved.
• status: the processing outcome, such as success, no_video, or invalid_input.
• media.bestVideoUrl: the recommended accessible video URL.
• media.formats: every detected video variant when requested.
• title and description: convenient top-level Pin text fields.
• error: a stable public error object for unsuccessful inputs.

Optional groups are omitted when their matching input toggle is disabled. Nullable fields use null when Pinterest does not expose a value or the Actor cannot establish it reliably.

Complete output field reference

Core result fields

Field	Type	Nullable	Meaning
inputUrl	string	No	The original input string after surrounding whitespace is removed.
normalizedUrl	string	Yes	Canonical Pinterest Pin URL when normalization or short-link resolution succeeds.
pinId	string	Yes	Numeric Pinterest Pin ID.
source	string	No	Always Pinterest; this Actor has no other source values.
title	string	Yes	Pin title exposed by Pinterest. Returned at the top level even when includeMetadata is false.
description	string	Yes	Pin description exposed by Pinterest. Returned at the top level even when includeMetadata is false.
success	boolean	No	true only when an accessible video result is returned.
status	string	No	Stable processing status described in the next section.
scrapedAt	string	No	ISO 8601 UTC timestamp showing when the result was created.

media

Field	Type	Nullable	Meaning
media.type	string	No	Detected media type, normally video; a valid image Pin returns image with no_video.
media.bestVideoUrl	string	Yes	Recommended accessible video URL. Progressive MP4 is preferred before resolution and bitrate comparisons; HLS is a fallback.
media.thumbnailUrl	string	Yes	Pinterest-provided video thumbnail or best available Pin image.
media.durationMs	number	Yes	Video duration in milliseconds.
media.width	number	Yes	Selected video width in pixels.
media.height	number	Yes	Selected video height in pixels.
media.hasAudio	boolean	Yes	Audio evidence derived from Pinterest's exposed HLS manifest. null means not reliably determined.
media.formats	array	—	All detected video variants. Omitted when includeFormats is false.

Each media.formats item can contain:

Field	Type	Nullable	Meaning
quality	string	No	Pinterest's quality identifier, such as V_720P or V_HLSV4.
format	string	No	mp4, hls, or unknown.
mimeType	string	Yes	Detected MIME type, such as video/mp4 or application/vnd.apple.mpegurl.
width	number	Yes	Variant width in pixels.
height	number	Yes	Variant height in pixels.
durationMs	number	Yes	Variant duration in milliseconds.
bitrate	number	Yes	Bitrate when Pinterest exposes it.
thumbnailUrl	string	Yes	Thumbnail associated with the variant.
url	string	No	Direct MP4 or HLS URL.

Optional Pin metadata

The following groups are included when includeMetadata is true.

• pin: id, type, canonical url, title, description, Pinterest-provided createdAt, sourceUrl, outboundUrl, domain, and extracted hashtags.
• creator: nullable id, username, fullName, profileUrl, avatarUrl, and followerCount.
• board: nullable id, name, and canonical url.
• engagement: nullable saves, repins, comments, shares, total reactions, and reactionCounts by Pinterest reaction identifier.

pin.createdAt is the date string provided by Pinterest and may not be normalized. scrapedAt is always an ISO 8601 timestamp generated by the Actor.

Native captions

The captions object is included when includeCaptions is true:

• captions.available: true when at least one native track is found.
• captions.tracks: array of tracks containing nullable language, nullable label, detected format, and direct url.

These are Pinterest-provided caption references. They are not ASR-generated transcripts.

Errors

Unsuccessful items include:

• error.code: stable machine-readable error code.
• error.message: plain-English explanation intended for API users.

Internal exception messages, proxy credentials, cookies, and authentication headers are not returned.

Status values

Status	Meaning	Main result	result event*
success	An accessible video URL was resolved.	media.bestVideoUrl is present.	Yes
no_video	The Pin is accessible but contains image or other non-video media.	media.type and NO_VIDEO_FOUND error.	Yes
no_media	The Pin is accessible but no supported media was found.	NO_MEDIA error.	Yes
invalid_input	The input is empty or not a supported Pinterest Pin URL/ID.	INVALID_INPUT or INVALID_PIN_URL.	No
not_found	Pinterest reports that the Pin cannot be found.	PIN_NOT_FOUND error.	Yes
private	The Pin requires authentication or is private.	PRIVATE_PIN error.	Yes
rate_limited	Pinterest temporarily rate-limited the request.	RATE_LIMITED error.	Yes
blocked	Pinterest blocked the request from the current network path.	BLOCKED error.	Yes
timeout	Pinterest did not respond before the request timeout.	TIMEOUT error.	Yes
error	The Pin or media was unavailable, unsupported, or could not be parsed.	A matching stable error.code.	Yes

*A processed canonical Pin is billed only on its first occurrence in the run. Canonical duplicates do not generate an additional event.

A failed item does not stop the rest of the batch. It is saved to the Dataset in its original position.

Complete output example

{
  "inputUrl": "https://www.pinterest.com/pin/29695678789181460/",
  "normalizedUrl": "https://www.pinterest.com/pin/29695678789181460/",
  "pinId": "29695678789181460",
  "source": "Pinterest",
  "title": "The most amazing places on earth",
  "description": null,
  "success": true,
  "status": "success",
  "media": {
    "type": "video",
    "bestVideoUrl": "https://v1.pinimg.com/videos/iht/expMp4/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d_720w.mp4",
    "thumbnailUrl": "https://i.pinimg.com/videos/thumbnails/originals/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d.0000000.jpg",
    "durationMs": 12100,
    "width": 720,
    "height": 1280,
    "hasAudio": true,
    "formats": [
      {
        "quality": "V_720P",
        "format": "mp4",
        "mimeType": "video/mp4",
        "width": 720,
        "height": 1280,
        "durationMs": 12100,
        "bitrate": null,
        "thumbnailUrl": "https://i.pinimg.com/videos/thumbnails/originals/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d.0000000.jpg",
        "url": "https://v1.pinimg.com/videos/iht/expMp4/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d_720w.mp4"
      },
      {
        "quality": "V_HLSV4",
        "format": "hls",
        "mimeType": "application/vnd.apple.mpegurl",
        "width": 720,
        "height": 1280,
        "durationMs": 12100,
        "bitrate": null,
        "thumbnailUrl": "https://i.pinimg.com/videos/thumbnails/originals/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d.0000000.jpg",
        "url": "https://v1.pinimg.com/videos/iht/hls/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d.m3u8"
      },
      {
        "quality": "V_HLSV3_MOBILE",
        "format": "hls",
        "mimeType": "application/vnd.apple.mpegurl",
        "width": 720,
        "height": 1280,
        "durationMs": 12100,
        "bitrate": null,
        "thumbnailUrl": "https://i.pinimg.com/videos/thumbnails/originals/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d.0000000.jpg",
        "url": "https://v1.pinimg.com/videos/iht/hls/1b/e9/90/1be990e86e2a4964ef1e9b8778fe935d.m3u8"
      }
    ]
  },
  "pin": {
    "id": "29695678789181460",
    "type": "video",
    "url": "https://www.pinterest.com/pin/29695678789181460/",
    "title": "The most amazing places on earth",
    "description": null,
    "createdAt": "Mon, 01 Jun 2026 19:45:49 +0000",
    "sourceUrl": null,
    "outboundUrl": null,
    "domain": "Uploaded by user",
    "hashtags": []
  },
  "creator": {
    "id": "1113022632816738989",
    "username": "Naturetravel2027",
    "fullName": "Nature Travel",
    "profileUrl": "https://www.pinterest.com/Naturetravel2027/",
    "avatarUrl": "https://i.pinimg.com/75x75_RS/36/ff/36/36ff36a8f412b9f09968647822a8f7bd.jpg",
    "followerCount": 1762
  },
  "board": {
    "id": "29695747482373777",
    "name": "Roads I have walked",
    "url": "https://www.pinterest.com/fluorescence9/roads-i-have-walked/"
  },
  "engagement": {
    "saves": 2348,
    "repins": 116,
    "comments": 25,
    "shares": 853,
    "reactions": 903,
    "reactionCounts": {
      "1": 903
    }
  },
  "captions": {
    "available": false,
    "tracks": []
  },
  "scrapedAt": "2026-08-24T14:37:06.390Z"
}

Engagement values and CDN URLs can change over time. The example shows the structure of a real tested response, not fixed future values.

Non-video result example

{
  "inputUrl": "https://pin.it/3AxJbLdcH",
  "normalizedUrl": "https://www.pinterest.com/pin/1053701644052468385/",
  "pinId": "1053701644052468385",
  "source": "Pinterest",
  "title": null,
  "description": null,
  "success": false,
  "status": "no_video",
  "media": {
    "type": "image"
  },
  "error": {
    "code": "NO_VIDEO_FOUND",
    "message": "The Pinterest Pin is accessible but does not contain video media."
  },
  "scrapedAt": "2026-08-24T14:45:43.417Z"
}

Invalid input example

{
  "inputUrl": "https://example.com/not-a-pinterest-pin",
  "normalizedUrl": null,
  "pinId": null,
  "source": "Pinterest",
  "title": null,
  "description": null,
  "success": false,
  "status": "invalid_input",
  "error": {
    "code": "INVALID_PIN_URL",
    "message": "The input is not a supported Pinterest Pin URL or numeric Pin ID."
  },
  "scrapedAt": "2026-08-24T14:37:05.365Z"
}

💳 Pricing

Billing is based on processed results, not only successful video URLs. Each unique canonical Pinterest Pin that enters processing produces one result billing event. Duplicate inputs can still produce separate Dataset records, but they are not charged again.

Standard pricing is $0.0029 per result — $2.90 per 1,000 results. Eligible Apify Store discounts can reduce this to $0.0020 per result — $2.00 per 1,000 results.

• One processed unique canonical Pin: one result event.
• Canonical duplicate: no additional charge, even though it keeps its own Dataset record.
• Successful video, image Pin, no-media result, unavailable Pin, or processing failure: one event when it is the first processed occurrence of that canonical input.
• Input rejected before Pinterest Pin processing: no event. This includes malformed inputs and unsupported domains.
• Multiple video formats: still one event, not one event per format.
• includeMetadata, includeFormats, and includeCaptions: these options do not multiply result billing.

Check the Actor's Pricing tab for the current rate available to your Apify plan. You can control event cost by limiting the number of unique canonical Pins submitted in a run.

💡 Use cases

Media workflow automation

Pass media.bestVideoUrl into a publishing queue, asset review system, media converter, or another API without first copying the entire file into Apify storage.

Content research

Collect public video URLs, thumbnails, titles, dimensions, and durations for organized research datasets while retaining a direct link to the original Pin.

Creator and campaign analysis

Use optional creator, board, and engagement context to understand where a public video appeared and how Pinterest exposes its surrounding metadata.

Video format inspection

Compare available MP4 and HLS variants, resolutions, and Pinterest quality identifiers before choosing a downstream processing format.

AI and data pipelines

Feed structured video metadata and URLs into your own classification, moderation, indexing, or analysis workflow. The Actor itself does not perform AI analysis or transcription.

API integration

Add Pinterest video resolution to an internal tool, backend service, no-code automation, or scheduled Apify workflow with predictable JSON output.

How it works

1. The Actor validates and normalizes each Pin URL or numeric ID.
2. It follows supported pin.it redirects to the canonical Pin.
3. It requests the public Pin detail data over HTTP with bounded retries and timeouts.
4. It extracts normalized Pin and media information without returning Pinterest's raw internal response.
5. It ranks video candidates with accessible progressive MP4 first and HLS as fallback.
6. It validates the recommended media URL and optionally inspects native captions and HLS audio evidence.
7. It writes one clean Dataset item for every input.

The Actor uses HTTP requests rather than a full browser, keeping the workflow focused on Pin detail and media resolution.

Public data and responsible use

This Actor is designed for publicly accessible Pinterest Pin data. Use the results in accordance with Pinterest's terms, Apify's terms, applicable privacy laws, and copyright rules.

Do not use the Actor to access private information, harass people, send spam, create unlawful profiles, or redistribute copyrighted media without the necessary rights or permission. You are responsible for your inputs and downstream use of returned URLs and metadata.

FAQ

Does this Pinterest video downloader save videos into Apify storage?

No. It returns direct Pinterest media URLs. This avoids automatically copying every video and lets you decide whether, where, and when to download it.

Which URL should I use to download the video?

Use media.bestVideoUrl. The Actor favors an accessible progressive MP4 because it is generally easier to download and process. HLS remains available in media.formats when Pinterest exposes it.

Does it support pin.it links?

Yes. The Actor follows supported public pin.it redirects and returns the canonical normalizedUrl and pinId.

Can I process multiple Pinterest videos at once?

Yes. Add up to 100 items to urls. Every input produces one Dataset item, including duplicates and failures.

What happens if I submit an image Pin?

The Actor returns success: false, status: "no_video", media.type: "image", and error.code: "NO_VIDEO_FOUND". The input is recognized as a valid Pin, not mislabeled as an invalid URL.

Is hasAudio always available?

No. It is a detection field based on reliable audio evidence in Pinterest's exposed HLS manifest. It can be true, false, or null. null means the Actor could not determine audio reliably.

Does includeCaptions create a transcript?

No. It only returns native caption or subtitle track metadata when Pinterest exposes it. The Actor does not perform ASR, translation, SRT generation, or transcript generation.

What does source mean?

source is always Pinterest. It is provided as a convenient top-level field for users combining results from multiple downstream data sources. This Actor does not accept or return other source platforms.

How are duplicate URLs handled and charged?

Duplicate inputs are preserved as separate Dataset records so input-to-output mapping remains clear. If multiple inputs resolve to the same canonical Pin, that canonical Pin is billed only once in the run.

Do image Pins or failed results count toward billing?

Yes, when a valid Pinterest Pin URL, pin.it link, or numeric Pin ID enters processing for the first time in the run. Billing is based on processed canonical Pins, not only successful video downloads. Inputs rejected before Pinterest processing, such as malformed values and unsupported domains, do not generate a result charge.

Why can a direct video URL stop working later?

Pinterest controls its CDN URLs and may rotate, restrict, or expire them. Use returned media URLs soon after the run and rerun the Actor when a fresh URL is needed.

Limitations

• Only public Pinterest Pin detail URLs, supported pin.it links, and numeric Pin IDs are accepted.
• Private, deleted, login-required, region-restricted, or unavailable Pins may fail or return limited data.
• Pinterest controls which formats, metadata, captions, and engagement values are exposed; nullable fields may be null.
• A URL that works in one region or network can be blocked or rate-limited elsewhere.
• Direct media URLs can expire or become unavailable after the run.
• Audio information is detected from exposed manifest evidence and is null when it cannot be established reliably.
• The Actor does not perform keyword search, full board crawling, full profile crawling, related-Pin discovery, or comment pagination.
• The Actor does not copy videos into storage, transcribe speech, translate captions, scan outbound websites, or bypass access controls.

Support

For help, email lanceapi2026@hotmail.com or open an issue on the Actor's Issues page.

Include the Run ID, a non-sensitive example input, the returned status, and error.code when available. Do not send your Apify token, cookies, proxy credentials, session IDs, or other secrets.