# Pinterest Ads Scraper (`maximedupre/pinterest-ads`) Actor

Search Pinterest's public Ads Transparency Repository by market, category, age, gender, advertiser, and campaign dates. Save structured ad records with available creative, targeting, reach, transparency, and destination data.

- **URL**: https://apify.com/maximedupre/pinterest-ads.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Marketing, Social media, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.10 / 1,000 ads

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/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 for public ad research

For marketers, agencies, and researchers, Pinterest Ads Scraper searches Pinterest's public Ads Transparency Repository with one set of filters across supported markets. It saves structured ad records with available advertiser, creative, campaign, targeting, reach, transparency, and destination data, so you can review public Pinterest ads in a dataset.

- Review creative patterns in **[Pinterest Carousel Ads](https://apify.com/maximedupre/pinterest-ads/examples/pinterest-carousel-ads)** across the markets you select.
- Review product promotion data with **[Pinterest Shopping Ads](https://apify.com/maximedupre/pinterest-ads/examples/pinterest-shopping-ads)** in your saved ad records.
- Group creative types with **[Pinterest Ad Formats](https://apify.com/maximedupre/pinterest-ads/examples/pinterest-ad-formats)** for a market or set of markets.
- Study real creative examples with **[Pinterest Ad Examples](https://apify.com/maximedupre/pinterest-ads/examples/pinterest-ad-examples)** from the public repository.
- Check source details for **[Pinterest Ad Specs](https://apify.com/maximedupre/pinterest-ads/examples/pinterest-ad-specs)** before planning a Pinterest campaign.

#### 🧾 Public Pinterest ad records

Each saved row represents one source ad from the public repository. It can include the ad ID and URL, market, advertiser and campaign dates, creative text and media links, audience targeting, public reach ranges, transparency flags, and destination URLs. Pinterest gaps remain unavailable rather than filled in.

#### ▶️ Search the Ads Transparency Repository

**How to run**

1. Set **Markets** to one or more supported markets.
2. Add optional category, age, gender, advertiser, or campaign date filters.
3. Use the same filter set across the selected markets for one combined search.
4. Set **Maximum ads** if you want to stop after a chosen number of saved records. Leave it empty to return all available results until the source is exhausted.
5. Start the run and open `datasetItems` to review or export the saved records.

Only one search batch is supported in a run. Use separate runs for different filter combinations.

#### ⚙️ Input

The Actor applies one common filter set to the markets you select. `markets` is required. All other fields are optional.

**Input fields**

| Field | Type | What it does |
| --- | --- | --- |
| `markets` | array of strings | Chooses one or more supported markets. Several markets use the same filters and return one combined search. Available markets are EU member states, Brazil, and Turkey. |
| `category` | string | Filters by an ad category value exactly as shown in Pinterest's public repository. |
| `age` | string | Filters by an audience age range exactly as shown in Pinterest's public repository, such as `25-34`. |
| `gender` | string | Filters by an audience gender value exactly as shown in Pinterest's public repository, such as `female`. |
| `advertiser` | string | Filters by the public advertiser name exactly as shown in Pinterest's public repository. |
| `campaignStartDate` | date string | Includes campaigns starting on or after this date. Use `YYYY-MM-DD`. |
| `campaignEndDate` | date string | Includes campaigns ending on or before this date. Use `YYYY-MM-DD`. |
| `maxItems` | integer | Optionally stops after this many saved ad records. Leave it empty to return all available results until the source is exhausted. The schema sets no upper bound. |

**Public input example**

This is the public input from the successful current-beta default-input run.

```json
{
  "markets": [
    "FR"
  ],
  "maxItems": 100
}
```

#### 🧾 Output

The run output contains a link to the default dataset. Each saved dataset row describes one public Pinterest ad. Optional values are left out when Pinterest does not publish them.

**Run output**

| Field | Type | What it does |
| --- | --- | --- |
| `datasetItems` | URL string | Opens the saved ad records in the run's default dataset. |

**Saved ad row**

| Field | Type | What it does |
| --- | --- | --- |
| `adId` | string | Gives the stable ID of the ad in the public Pinterest Ads Transparency Repository. |
| `adUrl` | URL string, optional | Links to the ad in the public repository. |
| `market` | string, optional | Gives the market code reported for the ad. |
| `advertiser` | object, optional | Holds public advertiser information when available. |
| `advertiser.name` | string | Gives the public advertiser name. |
| `campaign` | object, optional | Holds public campaign dates when available. |
| `campaign.startDate` | date string | Gives the campaign start date in `YYYY-MM-DD` form. |
| `campaign.endDate` | date string | Gives the campaign end date in `YYYY-MM-DD` form. |
| `creative` | object, optional | Holds the ad text and media published by Pinterest. |
| `creative.title` | string | Gives the title published with the ad. |
| `creative.description` | string | Gives the ad description or caption. |
| `creative.imageUrls` | array of URL strings | Lists image asset links published with the ad. |
| `creative.videoUrls` | array of URL strings | Lists video asset links published with the ad. |
| `targeting` | object, optional | Holds the audience targeting published for the ad. |
| `targeting.ageRanges` | array of strings | Lists the audience age ranges targeted by the ad. |
| `targeting.genders` | array of strings | Lists the audience genders targeted by the ad. |
| `targeting.countries` | array of strings | Lists the countries included in the ad's targeting. |
| `targeting.regions` | array of strings | Lists the regions included in the ad's targeting. |
| `targeting.interests` | array of strings | Lists the interests included in the ad's targeting. |
| `targeting.audienceSegments` | array of strings | Lists audience-list segments included in the ad's targeting. |
| `reach` | object, optional | Holds public estimated reach ranges for the ad. |
| `reach.euWide` | object | Holds the EU-wide estimated reach range. |
| `reach.euWide.lowerBound` | integer | Gives the lower end of the EU-wide reach range. |
| `reach.euWide.upperBound` | integer | Gives the upper end of the EU-wide reach range. |
| `reach.byCountry` | array of objects | Lists estimated reach ranges for individual countries. |
| `reach.byCountry[].countryCode` | string | Gives the country code for one reach estimate. |
| `reach.byCountry[].lowerBound` | integer | Gives the lower end of one country's reach range. |
| `reach.byCountry[].upperBound` | integer | Gives the upper end of one country's reach range. |
| `transparency` | object, optional | Holds public transparency information reported for the ad. |
| `transparency.isCommercial` | boolean | Says whether Pinterest marks the ad as commercial. |
| `transparency.reviewStatus` | string | Gives the public review status reported for the ad. |
| `transparency.disclosure` | string | Gives public review or disclosure information reported for the ad. |
| `transparency.inventoryFlags` | array of strings | Lists public inventory flags reported for the ad. |
| `commerce` | object, optional | Holds public product and destination link information for the ad. |
| `commerce.destinationUrls` | array of URL strings | Lists destinations used by the ad. |

**Example saved ad row**

This genuine row comes from the current beta run and is shown in full.

```json
{
  "adId": "196610339985409684",
  "adUrl": "https://ads.pinterest.com/ads-repository/?pin_id=196610339985409684",
  "market": "FR",
  "advertiser": {
    "name": "Perles & Co"
  },
  "campaign": {
    "startDate": "2026-06-23",
    "endDate": "2026-08-10"
  },
  "creative": {
    "title": "Des créoles en 5min 😁",
    "description": "Créoles en 5 min 💛\n\nDes boucles bluffantes avec un minimum de matériel.\n\nCarla te montre tout — tu choisis ta couleur, le reste prend 5 minutes 😄",
    "imageUrls": [
      "https://i.pinimg.com/474x/1e/99/ff/1e99fffa55c2f003515e625392fe85ba.jpg"
    ],
    "videoUrls": [
      "https://v1.pinimg.com/videos/mc/720p/af/42/f3/af42f3b2d439fd916c22604e1d525a70.mp4"
    ]
  },
  "targeting": {
    "ageRanges": [
      "18+"
    ],
    "genders": [
      "UNSPECIFIED",
      "FEMALE",
      "MALE"
    ],
    "countries": [
      "France"
    ],
    "interests": [
      "DIY_AND_CRAFTS"
    ],
    "audienceSegments": [
      "USER_LIST",
      "VISITOR",
      "ENGAGEMENT"
    ]
  },
  "reach": {
    "euWide": {
      "lowerBound": 0,
      "upperBound": 10000
    },
    "byCountry": [
      {
        "countryCode": "FR",
        "lowerBound": 0,
        "upperBound": 10000
      }
    ]
  },
  "transparency": {
    "isCommercial": true
  }
}
```

#### 💳 Pricing

The Actor uses pay-per-event pricing. Each saved ad from Pinterest's public Ads Transparency Repository is billed as one event. The event price depends on your Apify plan tier. Set `maxItems` when you want an upper bound on saved ads.

#### 🔌 Integrations

Open `datasetItems` from the run output to inspect the default dataset. You can also export the saved rows or read them through the Apify API.

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

#### ❓ FAQ

##### Can I search more than one market in one run?

Yes. Add several markets and the Actor applies the same filters to each one, then returns one combined search.

##### Can I search the United States or other markets?

No. The public repository coverage in this Actor includes EU member states, Brazil, and Turkey. The United States and other markets are outside its scope.

##### Can I filter by an arbitrary keyword or interest?

No. The input supports market, category, age, gender, advertiser, and campaign date filters. Interest and keyword details are returned only when Pinterest publishes them in an ad record.

##### What happens when Pinterest does not publish a field?

That value stays unavailable or the optional field is left out. The Actor does not fill gaps with guessed data.

##### What happens when the same ad appears more than once?

The first eligible occurrence of the source ad is saved. Later appearances of that same source ad are ignored.

##### What does leaving Maximum ads empty do?

The Actor returns all available results until the source is exhausted. There is no fixed schema maximum for this field.

##### Does this Actor manage Pinterest campaigns?

No. It searches the public Ads Transparency Repository. It does not create, edit, launch, or manage Pinterest campaigns.

### 📝 Changelog

**v0.0** (02-09-2026)

- Initial release.

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~pinterest-ads/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Related Actors

- [Google Ads Scraper](https://apify.com/maximedupre/google-ads-scraper) - Compare Pinterest creative research with public Google Ads Transparency Center creatives for the same brand.
- [Facebook Page Transparency Scraper](https://apify.com/maximedupre/facebook-page-transparency-scraper) - Review public Meta Ad Library creatives and Page transparency for a cross-platform ad audit.
- [Snapchat Ads Scraper](https://apify.com/maximedupre/snapchat-ads) - Search public Snapchat ad galleries to compare advertiser, creative, and impression data.
- [Pinterest Video Downloader](https://apify.com/maximedupre/pinterest-video-downloader) - Get direct media links from public Pinterest pins when you need to review a creative.
- [Pinterest Image Downloader](https://apify.com/maximedupre/pinterest-image-downloader) - Collect source image links and pin details for visual research alongside ad records.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `markets` (type: `array`):

Choose one or more supported markets. Several markets use these same filters and return one combined search. Only EU member states, Brazil, and Turkey are available.

## `category` (type: `string`):

Optional ad category filter. Enter the value exactly as shown in Pinterest's public repository.

## `age` (type: `string`):

Optional audience age filter. Enter the range exactly as shown in Pinterest's public repository, such as 25-34.

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

Optional audience gender filter. Enter the value exactly as shown in Pinterest's public repository, such as female.

## `advertiser` (type: `string`):

Optional advertiser filter. Enter the public advertiser name exactly as shown in Pinterest's public repository.

## `campaignStartDate` (type: `string`):

Optional first campaign date to include. This date is inclusive and must use YYYY-MM-DD.

## `campaignEndDate` (type: `string`):

Optional last campaign date to include. This date is inclusive and must use YYYY-MM-DD.

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

Optional positive limit on saved ad records. Leave it empty to return all available results until the source is exhausted.

## Actor input object example

```json
{
  "markets": [
    "FR"
  ],
  "maxItems": 100
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

Open the saved ad records 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 = {
    "markets": [
        "FR"
    ],
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/pinterest-ads").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 = {
    "markets": ["FR"],
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/pinterest-ads").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 '{
  "markets": [
    "FR"
  ],
  "maxItems": 100
}' |
apify call maximedupre/pinterest-ads --silent --output-dataset

```

## MCP server setup

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

```

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/QsrnxEmEaIIFJop1j/builds/NUiqaJBbyQbBAKKB8/openapi.json