# Pinterest Search Scraper: Trends & Reach Report (`scrapier/pinterest-trend-reach-report`) Actor

Scrape Pinterest search results with the Pinterest Search Scraper. Extract pins, images, descriptions, URLs, and engagement stats by keyword or topic. Perfect for trend tracking, market research, and content inspiration. Fast, reliable, and scalable for bulk searches.

- **URL**: https://apify.com/scrapier/pinterest-trend-reach-report.md
- **Developed by:** [Scrapier](https://apify.com/scrapier) (community)
- **Categories:** Social media, Lead generation, Videos
- **Stats:** 18 total users, 3 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

$24.99/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

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

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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 Trend & Reach Report

Search Pinterest by keyword, scrape structured **per-pin data**, and get a **run-level Trend & Reach Report** that aggregates the same scraped fields into keyword-level insight. This actor is a superset of a standard Pinterest search scraper: it keeps the exact per-pin output and adds a color-palette / creator-reach / posting-cadence / engagement / image-format report on top — computed only from data already fetched.

**Keywords:** pinterest scraper, pinterest search scraper, pinterest api, pinterest pins, pinterest trends, pinterest analytics, color palette analysis, creator reach, board analytics, engagement metrics, posting cadence, content freshness, image format distribution, pin data extraction, social media research.

### What it does

For every search:

1. **Per-pin scrape (default dataset).** Each pin is pushed live to the dataset with the base per-pin schema: `query`, `node_id`, `type`, `title`, `description`, `domain`, `link`, `dominant_color`, `created_at`, `board`, `reaction_counts`, `native_creator`, `pinner`, `image_url`, `image_width`, `image_height`, plus `scrapedAt`.
2. **Trend & Reach Report (key-value store → `TREND_REPORT`).** The same records are aggregated into a single run-level object with five sections:
   - **engagement** — total / average / median / max reactions and the raw reaction-type-ID breakdown (IDs left unlabeled — Pinterest does not expose their names), plus the top pins by reactions.
   - **colorPalette** — hue-family shares (red/orange/yellow/green/cyan/blue/purple/pink + black/white/gray neutrals) from each pin's real `dominant_color`, top raw hex colors, average saturation/brightness, and average reactions per color family.
   - **reach** — unique pinners and boards, top pinners by follower count, top boards by pin count, and top linked domains.
   - **cadence** — oldest/newest pin, median age in days, pins in the last 30/90 days, and a per-month histogram from each pin's `created_at`.
   - **imageFormats** — portrait/landscape/square counts and average width/height/aspect-ratio.

Every value in the report is a **count, mean, median, ratio, hue-bucket, or date-math** of scraped fields. Nothing is fabricated, hardcoded, or modeled.

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `query` | string (required) | `wallpaper` | Search term. |
| `filter` | enum `all` \| `videos` | `videos` | All pins or video pins only. |
| `limit` | integer 1–10000 | `10` | Pins to scrape; also the report's sample size. |
| `topN` | integer 1–100 | `10` | Entries per ranking in the report. |
| `rawData` | boolean | `false` | If `true`, only stream per-pin rows (skip the report). |
| `proxyConfiguration` | proxy | Residential | Residential proxy strongly recommended. |

### Output

- **Default dataset:** one row per pin (base schema + `scrapedAt`).
- **Key-value store record `TREND_REPORT`:** the aggregated report `{ query, filter, generatedAt, pinCount, analytics: { engagement, colorPalette, reach, cadence, imageFormats }, scrapedAt }`. Not written when `rawData=true`.

### Running

Run on the Apify platform or locally with the Apify CLI:

```bash
apify run --purge
````

Provide input via the Console form or an `INPUT.json`. Read the report after a run from the key-value store record `TREND_REPORT`.

### Notes & compliance

- **Anti-bot:** Pinterest blocks datacenter IPs. Without a residential proxy a run typically returns zero pins and an empty report. The actor retries with a fresh session up to 3 times and fails gracefully with a status message.
- Scrape only publicly available data and respect Pinterest's Terms of Service and applicable laws. Use collected data responsibly.

# Actor input Schema

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

What to search for on Pinterest. Example: query="minimalist living room" collects matching pins and builds a color/reach/cadence report for that keyword. Default is "wallpaper".

## `filter` (type: `string`):

Show all pins or only video pins. Example: filter="videos" restricts the scrape (and therefore the report) to video pins only. Default is "videos".

## `limit` (type: `integer`):

How many pins to scrape (1–10,000). This is also the sample size the Trend & Reach Report aggregates over — a larger limit gives more stable color/reach/cadence statistics. Example: limit=200. Default is 10.

## `topN` (type: `integer`):

How many entries to list in each ranking of the report (top pinners by followers, top boards by pin count, top domains, top dominant hex colors, top pins by reactions). Example: topN=5 lists the 5 biggest of each. Default is 10.

## `rawData` (type: `boolean`):

When enabled, the actor behaves like the base scraper: it streams the per-pin rows to the dataset and does NOT build the aggregated Trend & Reach Report. Example: rawData=true when you only want the raw pin records. Default is false.

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

Apify Residential proxy is strongly recommended — Pinterest blocks datacenter IPs and the run will return zero pins (and an empty report) without a residential session.

## Actor input object example

```json
{
  "query": "wallpaper",
  "filter": "videos",
  "limit": 10,
  "topN": 10,
  "rawData": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `pins` (type: `string`):

One item per pin (base per-pin schema + scrapedAt).

## `trendReport` (type: `string`):

Run-level aggregate: engagement, colorPalette, reach, cadence, imageFormats. Absent when rawData=true.

# 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 = {
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapier/pinterest-trend-reach-report").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 = { "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    } }

# Run the Actor and wait for it to finish
run = client.actor("scrapier/pinterest-trend-reach-report").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 '{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call scrapier/pinterest-trend-reach-report --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Pinterest Search Scraper: Trends & Reach Report",
        "description": "Scrape Pinterest search results with the Pinterest Search Scraper. Extract pins, images, descriptions, URLs, and engagement stats by keyword or topic. Perfect for trend tracking, market research, and content inspiration. Fast, reliable, and scalable for bulk searches.",
        "version": "1.1",
        "x-build-id": "hSVwmivWBofe4Kq2W"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/scrapier~pinterest-trend-reach-report/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-scrapier-pinterest-trend-reach-report",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/scrapier~pinterest-trend-reach-report/runs": {
            "post": {
                "operationId": "runs-sync-scrapier-pinterest-trend-reach-report",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/scrapier~pinterest-trend-reach-report/run-sync": {
            "post": {
                "operationId": "run-sync-scrapier-pinterest-trend-reach-report",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "query"
                ],
                "properties": {
                    "query": {
                        "title": "🔎 Search Query",
                        "type": "string",
                        "description": "What to search for on Pinterest. Example: query=\"minimalist living room\" collects matching pins and builds a color/reach/cadence report for that keyword. Default is \"wallpaper\".",
                        "default": "wallpaper"
                    },
                    "filter": {
                        "title": "📌 Content Type",
                        "enum": [
                            "all",
                            "videos"
                        ],
                        "type": "string",
                        "description": "Show all pins or only video pins. Example: filter=\"videos\" restricts the scrape (and therefore the report) to video pins only. Default is \"videos\".",
                        "default": "videos"
                    },
                    "limit": {
                        "title": "📊 Number of Pins",
                        "minimum": 1,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "How many pins to scrape (1–10,000). This is also the sample size the Trend & Reach Report aggregates over — a larger limit gives more stable color/reach/cadence statistics. Example: limit=200. Default is 10.",
                        "default": 10
                    },
                    "topN": {
                        "title": "🏆 Ranking Size (Top N)",
                        "minimum": 1,
                        "maximum": 100,
                        "type": "integer",
                        "description": "How many entries to list in each ranking of the report (top pinners by followers, top boards by pin count, top domains, top dominant hex colors, top pins by reactions). Example: topN=5 lists the 5 biggest of each. Default is 10.",
                        "default": 10
                    },
                    "rawData": {
                        "title": "🗃️ Raw Pins Only (skip report)",
                        "type": "boolean",
                        "description": "When enabled, the actor behaves like the base scraper: it streams the per-pin rows to the dataset and does NOT build the aggregated Trend & Reach Report. Example: rawData=true when you only want the raw pin records. Default is false.",
                        "default": false
                    },
                    "proxyConfiguration": {
                        "title": "🌐 Proxy Configuration",
                        "type": "object",
                        "description": "Apify Residential proxy is strongly recommended — Pinterest blocks datacenter IPs and the run will return zero pins (and an empty report) without a residential session.",
                        "default": {
                            "useApifyProxy": true,
                            "apifyProxyGroups": [
                                "RESIDENTIAL"
                            ]
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```