# Pinterest Ads Scraper 📌 (`shahidirfan/pinterest-ads-scraper`) Actor

Scrape live Pinterest ads & promoted pins instantly. Extract creatives, descriptions, URLs, likes, saves & advertiser details. Perfect for ad intelligence, competitor benchmarking, creative inspiration & ecommerce market research. Structured datasets.

- **URL**: https://apify.com/shahidirfan/pinterest-ads-scraper.md
- **Developed by:** [Shahid Irfan](https://apify.com/shahidirfan) (community)
- **Categories:** E-commerce, Social media, Lead generation
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

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

Extract comprehensive marketing data from the Pinterest Ad Library with ease. Collect targeting demographics, ad details, and creatives at scale. Perfect for competitive intelligence, ad monitoring, and market research.

***

### Features

- **Granular Filters** — Filter by date range, country, category, age, and gender
- **Demographic Targeting** — Retrieve specific age buckets and gender targeting details
- **Creative Extraction** — Extract ad creatives including image links and content descriptions
- **Customized Limits** — Control the number of ads fetched to optimize runs

***

### Use Cases

#### Competitive Analysis

Monitor competitors' active campaigns, messaging, and visual assets on Pinterest. Identify when they launch campaigns and what categories they target.

#### Market Trend Research

Understand regional advertising trends by analyzing ad counts, active durations, and demographic targeting configurations across different countries.

#### Demographic Profiling

Analyze which age ranges and genders are most heavily targeted within specific business categories to optimize your own audience targeting.

***

### Input Parameters

The actor accepts the following input parameters:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `start_date` | String | Yes | — | Start date for ad search (YYYY-MM-DD) |
| `end_date` | String | Yes | — | End date for ad search (YYYY-MM-DD) |
| `country` | String | Yes | — | Target country code (ISO Alpha-2) |
| `category` | String | No | `"ALL"` | Target ad category value |
| `age` | String | No | `"ALL"` | Target age bucket value |
| `gender` | String | No | `"ALL"` | Target gender value |
| `results_limit` | Integer | No | `50` | Maximum number of ads to retrieve |

***

#### Filter Options

Use these value mappings to ensure proper input validation when using the actor via API or programmatically:

##### 🌍 Countries (`country` input)

Use any of the following **ISO Alpha-2 codes**:

| Label          | Value |
| -------------- | ----- |
| Austria        | AT    |
| Belgium        | BE    |
| Brazil         | BR    |
| Bulgaria       | BG    |
| Croatia        | HR    |
| Cyprus         | CY    |
| Czech Republic | CZ    |
| Denmark        | DK    |
| Estonia        | EE    |
| Finland        | FI    |
| France         | FR    |
| Germany        | DE    |
| Greece         | GR    |
| Hungary        | HU    |
| Ireland        | IE    |
| Italy          | IT    |
| Latvia         | LV    |
| Lithuania      | LT    |
| Luxembourg     | LU    |
| Malta          | MT    |
| Netherlands    | NL    |
| Norway         | NO    |
| Poland         | PL    |
| Portugal       | PT    |
| Romania        | RO    |
| Slovakia       | SK    |
| Slovenia       | SI    |
| Spain          | ES    |
| Sweden         | SE    |
| Turkey         | TR    |

***

##### 🗂 Categories (`category` input)

| Label              | Value             |
| ------------------ | ----------------- |
| All Categories     | ALL               |
| Animals            | ANIMALS           |
| Architecture       | ARCHITECTURE      |
| Art                | ART               |
| Beauty             | BEAUTY            |
| Children's fashion | CHILDRENS\_FASHION |
| Design             | DESIGN            |
| DIY and crafts     | DIY\_AND\_CRAFTS    |
| Education          | EDUCATION         |
| Electronics        | ELECTRONICS       |
| Entertainment      | ENTERTAINMENT     |
| Event planning     | EVENT\_PLANNING    |
| Finance            | FINANCE           |
| Food and drinks    | FOOD\_AND\_DRINKS   |
| Health             | HEALTH            |
| Home decor         | HOME\_DECOR        |
| Gardening          | GARDENING         |
| Men's fashion      | MENS\_FASHION      |
| Parenting          | PARENTING         |
| Quotes             | QUOTES            |
| Sport              | SPORT             |
| Travel             | TRAVEL            |
| Vehicles           | VEHICLES          |
| Wedding            | WEDDING           |
| Women's fashion    | WOMENS\_FASHION    |
| Other              | OTHER             |

***

##### 🎂 Ages (`age` input)

| Label    | Value       |
| -------- | ----------- |
| All Ages | ALL         |
| 18–24    | AGE\_18\_24   |
| 21–24    | AGE\_21\_24   |
| 18–20    | AGE\_18\_20   |
| 25–34    | AGE\_25\_34   |
| 35–44    | AGE\_35\_44   |
| 45–49    | AGE\_45\_49   |
| 50–54    | AGE\_50\_54   |
| 55–64    | AGE\_55\_64   |
| 65+      | AGE\_65\_PLUS |

***

##### ⚥ Genders (`gender` input)

| Label       | Value       |
| ----------- | ----------- |
| All Genders | ALL         |
| Male        | MALE        |
| Female      | FEMALE      |
| Unspecified | UNSPECIFIED |

***

### Output Data

Each item in the dataset contains the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `pin_id` | String | Unique identifier of the pin |
| `ad_details_start_date` | String | Campaign launch date |
| `ad_details_end_date` | String | Campaign end date |
| `ad_details_age_buckets` | String | Targeted age ranges as a comma-separated list |
| `ad_details_genders` | String | Targeted genders as a comma-separated list |
| `ad_details_countries` | String | Targeted countries as a comma-separated list |
| `ad_details_content_commercial` | Boolean | Whether the ad is marked as commercial content |
| `ad_details_user_count_by_country` | String | Country-level audience estimate summary |
| `ad_details_user_count_eu` | String | EU-wide audience estimate summary |
| `ad_details_image_link` | String | URL of the main creative |
| `ad_details_pin_data_image_link` | String | URL of the pin image asset |
| `ad_details_pin_data_title` | String | Title of the advertised pin |
| `ad_details_pin_data_details` | String | Ad caption or text copy |

Only populated values are included in each record, so some optional columns appear only when Pinterest provides them.

***

### Usage Examples

#### Retrieve German Home Decor Ads

Filter ads in Germany specifically related to Home Decor:

```json
{
  "start_date": "2026-01-01",
  "end_date": "2026-06-01",
  "country": "DE",
  "category": "HOME_DECOR",
  "age": "ALL",
  "gender": "ALL",
  "results_limit": 20
}
```

#### Age-Targeted Campaign Scraping

Fetch ads targeting young adults (18-24) in France:

```json
{
  "start_date": "2026-01-01",
  "end_date": "2026-06-01",
  "country": "FR",
  "category": "ALL",
  "age": "AGE_18_24",
  "gender": "ALL",
  "results_limit": 50
}
```

#### Female-Targeted Beauty Ads in Spain

Filter specifically for female demographic beauty ads:

```json
{
  "start_date": "2026-01-01",
  "end_date": "2026-06-01",
  "country": "ES",
  "category": "BEAUTY",
  "age": "ALL",
  "gender": "FEMALE",
  "results_limit": 100
}
```

***

### Sample Output

```json
{
  "pin_id": "4602327078024214784",
  "ad_details_start_date": "2026-04-02",
  "ad_details_end_date": "2026-06-12",
  "ad_details_age_buckets": "18+",
  "ad_details_genders": "UNSPECIFIED, FEMALE, MALE",
  "ad_details_countries": "Italy",
  "ad_details_content_commercial": true,
  "ad_details_is_local_inventory": false,
  "ad_details_has_excluded_locations": false,
  "ad_details_user_count_by_country": "Italy: 0 - 10000",
  "ad_details_user_count_eu": "0 - 10000",
  "ad_details_keywords_used": false,
  "ad_details_negative_keywords_used": false,
  "ad_details_image_link": "https://i.pinimg.com/474x/35/18/f9/3518f9b5222df2ac47c3d2db86049c25.jpg",
  "ad_details_pin_data_image_link": "https://i.pinimg.com/474x/35/18/f9/3518f9b5222df2ac47c3d2db86049c25.jpg",
  "ad_details_pin_data_title": "Pantaloni pieghetti Meraner | Comoda e alla moda vestibilità dritta",
  "ad_details_pin_data_details": "Valorizza il tuo look quotidiano con i pantaloni plissettati Merano..."
}
```

***

### Tips for Best Results

#### Date Ranges

- Avoid requesting excessively large date ranges at once.
- Fetch in smaller chunks (e.g., monthly) to avoid hitting limits or timeouts.

#### Handling Empty Fields

- The actor skips null and empty values, so only populated fields are written to the dataset.
- Optional fields can vary by ad and by market depending on what Pinterest exposes publicly.

***

### Integrations

Connect your data with:

- **Google Sheets** — Export for analysis
- **Airtable** — Build searchable databases
- **Slack** — Get notifications
- **Webhooks** — Send to custom endpoints
- **Make** — Create automated workflows
- **Zapier** — Trigger actions

#### Export Formats

Download data in multiple formats:

- **JSON** — For developers and APIs
- **CSV** — For spreadsheet analysis
- **Excel** — For business reporting
- **XML** — For system integrations

***

### Frequently Asked Questions

#### Can I run this without proxies?

For stable runs and bypassing blocks, we recommend utilizing Apify's proxy options.

#### What are the correct codes for filters?

Please check the tables in the Filter Options section above for the valid country codes, category values, age parameters, and gender formats.

#### How is the pricing calculated?

Pricing is based on computing power (CU) consumed per run. Optimize your limits to reduce costs.

***

### Support

For issues or feature requests, contact support through the Apify Console.

#### Resources

- [Apify Documentation](https://docs.apify.com/)
- [API Reference](https://docs.apify.com/api/v2)
- [Scheduling Runs](https://docs.apify.com/schedules)

***

### Legal Notice

This actor is designed for legitimate data collection purposes. Users are responsible for ensuring compliance with website terms of service and applicable laws. Use data responsibly and respect rate limits.

# Actor input Schema

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

Select the target country (ISO Alpha-2 code) to retrieve ads from.

## `start_date` (type: `string`):

Start date for filtering campaigns (format: YYYY-MM-DD). The total date range must be less than 30 days. If not specified, defaults to 7 days ago.

## `end_date` (type: `string`):

End date for filtering campaigns (format: YYYY-MM-DD). The total date range must be less than 30 days. If not specified, defaults to today.

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

Filter ads by a specific industry category (e.g. Beauty, Home Decor, Art).

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

Filter campaigns based on targeted gender demographics.

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

Filter campaigns based on targeted age range buckets.

## `results_limit` (type: `integer`):

The maximum number of ad records to fetch and save.

## Actor input object example

```json
{
  "country": "FR",
  "category": "ALL",
  "gender": "ALL",
  "age": "ALL",
  "results_limit": 20
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# 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",
    "category": "ALL",
    "gender": "ALL",
    "age": "ALL",
    "results_limit": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("shahidirfan/pinterest-ads-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",
    "category": "ALL",
    "gender": "ALL",
    "age": "ALL",
    "results_limit": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("shahidirfan/pinterest-ads-scraper").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 '{
  "country": "FR",
  "category": "ALL",
  "gender": "ALL",
  "age": "ALL",
  "results_limit": 20
}' |
apify call shahidirfan/pinterest-ads-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/J3xYjkWqw6S24Q3DD/builds/gEgYBgUnE0tvcncZg/openapi.json