# Pinterest Ads Library Scraper (`scrapeai/pinterest-ads-library-scraper`) Actor

Scrape live ad campaigns from the Pinterest Ads Transparency Repository by keyword, brand, advertiser, country, or category. Extracts advertiser profile, ad creatives (HD image & video), targeting parameters, EU reach estimates, engagement metrics, and campaign timelines.

- **URL**: https://apify.com/scrapeai/pinterest-ads-library-scraper.md
- **Developed by:** [ScrapeAI](https://apify.com/scrapeai) (community)
- **Categories:** Social media, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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 Ads Library Scraper

Scrape live ad campaigns, visual creatives, targeting data, and advertiser transparency metrics from the **Pinterest Ads Library (Transparency Repository)**.

Extract advertiser profiles, high-resolution creative media (images & HD videos), destination landing pages, audience targeting demographics (countries, age buckets, genders), EU reach estimations, and campaign duration.

***

### 🌟 Key Features

- **Live Ad Discovery** — Real-time extraction directly from the official Pinterest Ads Transparency Repository.
- **Dynamic Filtering** — Search by advertiser/brand name, country, category vertical, gender, and age group.
- **Rich Media Extraction** — Captures highest-resolution original image creatives and direct MP4/HLS video URLs.
- **Comprehensive Advertiser Profiles** — Extracts brand name, Pinterest profile URL, account ID, verified merchant status, and domain link.
- **Granular Targeting & Transparency** — Extracts target countries, genders, age buckets, interests, and EU recipient reach estimates.
- **Engagement & Timelines** — Captures campaign start/end dates, saves/repins, comment counts, share counts, and dominant creative colors.
- **Apify Integration** — Ready for scheduled runs, webhook triggers, cloud datasets, and direct API export (JSON, CSV, Excel).

***

### 🎯 Use Cases

- **Competitor Ad Monitoring**: Track what ads competitors and industry leaders are running across Pinterest.
- **Creative & Visual Benchmarking**: Discover top-performing image & video formats, color palettes, and copy hooks.
- **Audience Targeting Intelligence**: Analyze how brands target specific demographics, age groups, and EU countries.
- **E-Commerce & DTC Research**: Discover trending products, discount offers, and conversion landing pages.

***

### 📥 Input Parameters

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `query` | `string` | `—` | Optional advertiser/brand search text. Pinterest's live repository exposes advertiser-name search rather than a general keyword search. |
| `advertiserName` | `string` | `—` | Optional: specific Pinterest advertiser name to filter ads directly. |
| `country` | `string` | `"FR"` | Country code for the Ads Transparency Repository (e.g. `FR`, `DE`, `ES`, `IT`, `GB`, `US`, `NL`, `BE`, `AT`, `BR`, `PL`, `SE`). |
| `adVertical` | `string` | `"ALL"` | Category vertical (e.g. `WOMENS_FASHION`, `BEAUTY`, `HOME_DECOR`, `SPORT`, `TRAVEL`, `FOOD_AND_DRINKS`). |
| `gender` | `string` | `"ALL"` | Target audience gender filter (`ALL`, `FEMALE`, `MALE`, `UNSPECIFIED`). |
| `ageBucket` | `string` | `"ALL"` | Target audience age group (`ALL`, `AGE_18_24`, `AGE_25_34`, `AGE_35_44`, `AGE_45_49`, etc.). |
| `maxItems` | `integer` | `50` | Maximum number of ads to scrape (1 – 500). |
| `proxyConfiguration` | `object` | `{ "useApifyProxy": true }` | Proxy settings. Residential proxies recommended for high-volume jobs. |

***

### 📤 Output Fields

Each dataset item contains rich structured data:

| Field | Type | Description |
|-------|------|-------------|
| `adId` | `string` | Unique identifier for the Pinterest ad / pin. |
| `pinUrl` | `string` | Direct web URL to the pin on Pinterest. |
| `advertiserName` | `string` | Name of the advertiser or brand. |
| `advertiserId` | `string` | Pinterest advertiser user ID. |
| `advertiserUsername` | `string` | Official Pinterest username / handle. |
| `advertiserUrl` | `string` | Advertiser website / official domain URL. |
| `isVerifiedMerchant` | `boolean` | Indicates if the advertiser is a verified merchant on Pinterest. |
| `adTitle` | `string` | Ad headline / creative title. |
| `adDescription` | `string` | Full ad copy text or pin description. |
| `destinationUrl` | `string` | Landing page URL where users are directed upon clicking. |
| `adImageUrl` | `string` | Full-resolution creative image URL. |
| `videoUrl` | `string` | Direct MP4 / HLS video stream URL for video ads. |
| `adType` | `string` | Creative format (`image`, `video`, `carousel`). |
| `targetingCountries` | `array` | List of countries targeted by the campaign. |
| `targetingGenders` | `array` | Targeted genders (`FEMALE`, `MALE`, `UNSPECIFIED`). |
| `targetingAgeBuckets` | `array` | Targeted age groups (e.g. `["18+"]`). |
| `targetingInterests` | `array` | Targeted interest categories. |
| `userCountEU` | `string` | Estimated EU audience reach range. |
| `userCountByCountry` | `object` | Breakdown of estimated recipient reach per country. |
| `startDate` | `string` | Campaign start or first observed date. |
| `endDate` | `string` | Campaign end date (if applicable). |
| `commercialContent` | `boolean` | Flag indicating commercial advertisement status. |
| `repinCount` | `integer` | Total saves / repins on the ad creative. |
| `commentCount` | `integer` | Total comments on the ad pin. |
| `shareCount` | `integer` | Total shares on the ad creative. |
| `dominantColor` | `string` | Primary hex color code of the creative image. |
| `searchQuery` | `string` | Advertiser/brand search text used for the scrape, when supplied. |
| `country` | `string` | Country code filter used during the run. |
| `scrapedAt` | `string` | ISO timestamp of the scrape. |

***

#### 📋 Sample Output JSON

```json
{
  "adId": "4593812444480190592",
  "pinUrl": "https://www.pinterest.com/pin/4593812444480190592/",
  "advertiserName": "Agapée | Jewelry",
  "advertiserId": "726205646072101387",
  "advertiserUsername": "agapee_official",
  "advertiserUrl": "https://agapee.com",
  "isVerifiedMerchant": true,
  "adTitle": "Lysia Blue Earrings",
  "adDescription": "The Lysia earrings feature drop-shaped pendants on small hoops, each with a blue stone hand-set in textured gold.",
  "destinationUrl": "https://agapee.com/products/lysia-blue-earrings?variant=50575005548870",
  "adImageUrl": "https://i.pinimg.com/originals/4d/04/7b/4d047b724360dcdb0f6f4eb231e84d56.jpg",
  "videoUrl": "https://v1.pinimg.com/videos/iht/expMp4/37/d8/af/37d8af2c7254b36fadaf7a483792deb8_720w.mp4",
  "adType": "video",
  "targetingCountries": [
    "France",
    "Germany",
    "Spain",
    "Italy",
    "Belgium",
    "Netherlands"
  ],
  "targetingGenders": [
    "FEMALE",
    "MALE",
    "UNSPECIFIED"
  ],
  "targetingAgeBuckets": [
    "18+"
  ],
  "targetingInterests": [],
  "userCountEU": "0 - 10000",
  "userCountByCountry": {
    "France": "0 - 10000",
    "Germany": "0 - 10000",
    "Spain": "0 - 10000"
  },
  "startDate": "2026-04-04",
  "endDate": "2026-08-25",
  "commercialContent": true,
  "repinCount": 12,
  "commentCount": 0,
  "shareCount": 1,
  "dominantColor": "#c27d5a",
  "searchQuery": "shoes",
  "country": "FR",
  "scrapedAt": "2026-08-25T12:00:00.000Z"
}
```

***

### 💡 Best Practices

1. **Proxy Settings**: For large batch extractions on the Apify platform, enable Apify residential proxies for best reliability.
2. **Category & Advertiser Filters**: Combine `advertiserName` or `adVertical` with `country` to zoom into specific market segments.
3. **Automate & Schedule**: Set up recurring runs (e.g., daily or weekly) to track newly launched campaigns and seasonal promotions automatically.

# Actor input Schema

## `query` (type: `string`):

Optional advertiser or brand text. Pinterest's live Ads Repository exposes advertiser-name search rather than a general keyword search.

## `advertiserName` (type: `string`):

Optional: exact or partial advertiser name to filter ads directly (e.g. Nike, ASOS, La Redoute, AliExpress).

## `country` (type: `string`):

Target country for the Pinterest Ads Library (EU Transparency Repository & Brazil).

## `adVertical` (type: `string`):

Optional category filter for the ads.

## `gender` (type: `string`):

Filter ads by target audience gender.

## `ageBucket` (type: `string`):

Filter ads by target audience age group.

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

Maximum number of ads to extract.

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

Proxy settings. Recommended for high-volume cloud execution.

## Actor input object example

```json
{
  "query": "shoes",
  "advertiserName": "Nike",
  "country": "FR",
  "adVertical": "ALL",
  "gender": "ALL",
  "ageBucket": "ALL",
  "maxItems": 50,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Dataset containing all scraped Pinterest ad creatives, targeting info, and advertiser metrics.

# 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 = {
    "country": "FR",
    "adVertical": "ALL",
    "gender": "ALL",
    "ageBucket": "ALL",
    "maxItems": 50,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeai/pinterest-ads-library-scraper").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 = {
    "country": "FR",
    "adVertical": "ALL",
    "gender": "ALL",
    "ageBucket": "ALL",
    "maxItems": 50,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("scrapeai/pinterest-ads-library-scraper").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 '{
  "country": "FR",
  "adVertical": "ALL",
  "gender": "ALL",
  "ageBucket": "ALL",
  "maxItems": 50,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call scrapeai/pinterest-ads-library-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapeai/pinterest-ads-library-scraper"
        }
    }
}

```

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/VdcYlpzDEnswPBbU0/builds/Le4NqT46LDNZLwwgd/openapi.json