# Pinterest Autocomplete Keyword Scraper (`automation-lab/pinterest-autocomplete-keyword-scraper`) Actor

Export ranked Pinterest autocomplete suggestions from seeds or search URLs, with recursive long-tail expansion and parent-keyword edges.

- **URL**: https://apify.com/automation-lab/pinterest-autocomplete-keyword-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.39 / 1,000 pinterest suggestion saveds

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/platform/actors/running/actors-in-store#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 Autocomplete Keyword Scraper

Turn seed phrases and Pinterest search URLs into ranked, export-ready Pinterest autocomplete keywords.
The Actor opens Pinterest anonymously, captures its public autocomplete response, removes duplicates, and can recursively expand suggestions into a long-tail keyword map.

Use it to plan Pinterest SEO, seasonal content, ecommerce collections, promoted-pin themes, and client research without copying suggestions by hand.
No Pinterest account or private API key is required.

### What does Pinterest Autocomplete Keyword Scraper do?

For each input keyword, the Actor:

1. opens the matching public Pinterest pin-search page;
2. captures Pinterest's structured autocomplete response;
3. validates and normalizes the returned suggestions;
4. preserves rank, suggestion ID, type, and destination URL;
5. deduplicates repeated suggestions across inputs;
6. retains all parent seed relationships; and
7. optionally uses discovered suggestions as the next expansion level.

The default depth of `0` performs one fast autocomplete lookup per input.
Depth `1` or `2` builds a wider long-tail graph while `maxSuggestions` keeps the job bounded.

### Who is this Pinterest keyword tool for?

- **Pinterest marketers** discovering phrases people are prompted to search.
- **SEO teams** comparing Pinterest language with web-search keyword lists.
- **Ecommerce planners** naming collections, gift guides, and seasonal landing pages.
- **Content teams** turning broad themes into article, video, and pin-board ideas.
- **Agencies** refreshing keyword exports for multiple clients or locales.
- **Data teams** feeding ranked suggestions into Sheets, BigQuery, a warehouse, or an LLM workflow.

### Why use autocomplete data?

Autocomplete is a useful source of real topic phrasing because suggestions appear directly in Pinterest's public search experience.
It can reveal modifiers such as style, audience, room, season, color, product, and occasion.

This Actor returns source data rather than estimating search volume.
It does not claim that a suggestion has a specific monthly volume, trend score, or paid-ad value.
Combine it with your analytics and campaign data when prioritizing keywords.

### What Pinterest keyword data is extracted?

| Field | Meaning |
| --- | --- |
| `seed` | Input or recursive parent that produced the record |
| `parentSeeds` | Every processed parent connected to the deduplicated suggestion |
| `suggestion` | Normalized autocomplete query |
| `label` | Human-readable label returned by Pinterest |
| `suggestionId` | Pinterest autocomplete ID, when available |
| `rank` | One-based position for this parent seed |
| `resultIndex` | Zero-based Pinterest result index |
| `type` | Usually `query`; `guide` identifies the rendered fallback |
| `searchUrl` | Absolute Pinterest search URL for the suggestion |
| `sourceUrl` | Search page opened for the parent seed |
| `locale` | Requested browser locale |
| `country` | Country detected by Pinterest, when available |
| `depth` | Parent expansion level; direct inputs are `0` |
| `scrapedAt` | ISO 8601 collection timestamp |

### How to scrape Pinterest autocomplete keywords

1. Open the Actor input page.
2. Add up to 100 phrases in **Seed keywords**, or paste Pinterest pin-search URLs.
3. Choose a browser locale such as `en-US` or `de-DE`.
4. Keep expansion depth at `0` for a quick export, or choose `1`–`2` for long-tail research.
5. Set the global maximum number of unique suggestions.
6. Run the Actor.
7. Export the default dataset as JSON, CSV, Excel, XML, or RSS.

A useful first run is:

```json
{
  "seedKeywords": ["summer wedding", "fall home decor"],
  "locale": "en-US",
  "expansionDepth": 0,
  "maxSuggestions": 50
}
```

### Input parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `seedKeywords` | string array | none | Phrases to expand; up to 100 unique values |
| `startUrls` | request list | none | Pinterest `/search/pins/?q=...` URLs |
| `locale` | string | `en-US` | Browser locale and deduplication context |
| `country` | string | none | Optional ISO country for a supplied Apify proxy |
| `expansionDepth` | integer | `0` | Recursive levels from 0 through 2 |
| `maxSuggestions` | integer | `100` | Global output cap from 1 through 5,000 |
| `proxyConfiguration` | object | direct | Optional user-controlled Apify Proxy settings |

At least one non-empty seed or valid Pinterest search URL is required.
Only public Pinterest pin-search URLs are accepted in `startUrls`.

### Pinterest search URL input

If your workflow already stores Pinterest searches, pass them directly:

```json
{
  "startUrls": [
    { "url": "https://www.pinterest.com/search/pins/?q=home%20office%20ideas" }
  ],
  "maxSuggestions": 25
}
```

The Actor extracts the `q` value and applies the same locale, limits, deduplication, retry, and expansion behavior used for direct seeds.
Unsupported domains and empty `q` parameters fail clearly instead of producing misleading empty datasets.

### Recursive long-tail keyword expansion

Set `expansionDepth` to `1` to scrape the initial seed and then scrape its discovered suggestions.
Depth `2` adds one more level.
The queue is breadth-first, so broad coverage is collected before deeper branches.

`maxSuggestions` limits unique output records, not page visits.
A suggestion returned by multiple parents appears once with all relationships in `parentSeeds`.
The first parent remains in `seed`, and `depth` shows the level where that record was first saved.

For a bounded research map:

```json
{
  "seedKeywords": ["small balcony garden"],
  "expansionDepth": 2,
  "maxSuggestions": 150
}
```

### Output example

A current anonymous Pinterest response produces records like:

```json
{
  "seed": "summer wedding",
  "parentSeeds": ["summer wedding"],
  "suggestion": "summer wedding guest dress",
  "label": "summer wedding guest dress",
  "suggestionId": "ac_qvTrYIzi",
  "rank": 1,
  "resultIndex": 0,
  "type": "query",
  "searchUrl": "https://www.pinterest.com/search/pins/?q=summer+wedding+guest+dress&rs=ac&len=14&source_id=ac_qvTrYIzi",
  "sourceUrl": "https://www.pinterest.com/search/pins/?q=summer%20wedding",
  "locale": "en-US",
  "country": "DE",
  "depth": 0,
  "scrapedAt": "2026-07-26T07:14:53.029Z"
}
```

IDs, suggestions, country detection, and rankings come from Pinterest and can change between runs.
Fallback guide records can have `suggestionId: null`.

### How much does it cost to scrape Pinterest autocomplete keywords?

The Actor uses pay per event: you pay only for each unique suggestion saved to the dataset.
There is no separate start fee.
The FREE tier is **$0.00075178 per saved suggestion**, with lower per-item rates on higher Apify tiers.

Multiply the number of saved suggestions by your plan's displayed per-item rate to estimate a run; for example, 100 results use 100 item events and 1,000 results use 1,000 item events.

Apify rounds and bills according to your platform plan.
Optional proxy traffic and platform usage can affect your total account cost.
Prices shown here describe this Actor's current source-configured pricing and must be checked on the live pricing tab before a production budget is finalized.

### Reliability, retries, and proxy behavior

The implementation listens for Pinterest's autocomplete network response before navigation, validates its success status, and blocks unnecessary images, video, and fonts.
Transient failures are retried twice with a fresh isolated browser context and bounded backoff.
A visible public search-guide extraction is used only when structured autocomplete does not arrive.

Direct anonymous access is the default.
The Actor never enables a residential fallback automatically.
If you supply `proxyConfiguration`, its session and optional country are used for that attempt; proxy costs remain under your control.
A terminal blocked or changed response fails the run rather than silently reporting zero keywords.

### Limits and responsible scaling

- Maximum 100 unique input seeds per run.
- Expansion depth is capped at 2.
- Output is capped at 5,000 unique suggestions.
- Pinterest commonly returns a small bounded set per keyword.
- Locale and IP geography can influence results.
- Public endpoint shape and availability may change.

For large research jobs, start with depth `0`, inspect relevance, and expand only high-value themes.
Prefer scheduled incremental refreshes over repeatedly running thousands of low-value variants.

### Integrations and automation ideas

- Schedule weekly exports to detect new seasonal phrasing.
- Send dataset items to Google Sheets for editorial triage.
- Join autocomplete phrases with Search Console or paid-search metrics.
- Group modifiers with an LLM after extraction.
- Build Pinterest board and collection naming briefs.
- Trigger Slack or email alerts when a target suggestion appears.
- Export CSV files for client deliverables.
- Use webhooks to launch downstream enrichment Actors.

### Run with the Apify API

Replace `YOUR_TOKEN` with your Apify API token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~pinterest-autocomplete-keyword-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"seedKeywords":["summer wedding"],"maxSuggestions":25}'
```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/pinterest-autocomplete-keyword-scraper').call({
  seedKeywords: ['summer wedding'],
  locale: 'en-US',
  maxSuggestions: 25,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient
import os

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/pinterest-autocomplete-keyword-scraper').call(run_input={
    'seedKeywords': ['summer wedding'],
    'locale': 'en-US',
    'maxSuggestions': 25,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use with Apify MCP and AI assistants

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/pinterest-autocomplete-keyword-scraper"
```

#### Claude Desktop setup

Add this JSON to Claude Desktop's MCP configuration.

#### Cursor setup

Use the same HTTP server entry in Cursor's MCP settings.

#### VS Code setup

Use the same server URL in your VS Code MCP configuration.

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/pinterest-autocomplete-keyword-scraper"
    }
  }
}
```

Example prompts:

- “Expand `minimalist kitchen` into 50 ranked Pinterest suggestions.”
- “Create a one-level keyword map for `winter wedding` and return CSV-ready fields.”
- “Compare parent relationships for `small patio ideas` and `balcony garden`.”

### Legal and responsible use

This Actor accesses publicly available anonymous Pinterest search suggestions.
Use the data only for lawful purposes and follow Pinterest's terms, robots guidance, applicable privacy rules, and your contractual obligations.
Do not use the Actor to overload Pinterest, evade access controls, or infer sensitive traits about individuals.
You are responsible for deciding whether your collection and downstream use are permitted in your jurisdiction.

### Troubleshooting

#### Why did my run fail instead of returning an empty dataset?

A blocked page, malformed response, invalid URL, or exhausted retry path is treated as an error.
This prevents upstream changes from looking like a legitimate “no suggestions” result.
Check the run log, reduce input size, confirm the URL shape, or supply an appropriate proxy configuration.

#### Why are suggestions different from my browser?

Pinterest can vary results by time, locale, IP country, experiments, and session context.
Match the `locale` and, when necessary, use a proxy configured for the intended country.
The output `country` field shows what Pinterest reported when available.

#### Why are there fewer rows than `maxSuggestions`?

The value is a ceiling, not a promise.
Pinterest may return fewer unique suggestions, especially at depth `0`, and duplicate terms are merged across parents.
Increase expansion depth or add materially different seeds for broader coverage.

#### Why is a suggestion ID null?

The structured response normally supplies an ID.
If the Actor used the visible search-guide fallback, the public link may not expose one; those records use `type: "guide"` and `suggestionId: null`.

### FAQ

#### Does this scrape pins or boards?

No. It exports autocomplete keyword suggestions and their search links, not pin or board records.

#### Is a Pinterest login required?

No. The current workflow uses the public anonymous search experience.

#### Does the Actor estimate search volume?

No. It preserves Pinterest's ordering but does not invent volume, CPC, competition, or trend metrics.

#### Can I use multiple locales?

Run separate tasks per locale so each dataset has a clear locale context and predictable deduplication.

#### Can I schedule it?

Yes. Use Apify Schedules and export or webhook integrations to refresh keyword research automatically.

### Related automation-lab Actors

- [Pinterest Scraper](https://apify.com/automation-lab/pinterest-scraper) — collect public pin and profile data after keyword discovery.
- [Pinterest Trends Scraper](https://apify.com/automation-lab/pinterest-trends-scraper) — monitor Pinterest trend surfaces for adjacent research.

Use this Actor first for keyword expansion, then pass selected `searchUrl` values into a pin-focused workflow when you need content-level data.

# Actor input Schema

## `seedKeywords` (type: `array`):

One or more phrases to expand with Pinterest autocomplete. Empty values are rejected and at most 100 unique seeds are processed.

## `startUrls` (type: `array`):

Optional Pinterest pin-search URLs. The q parameter is extracted and handled exactly like a seed keyword.

## `locale` (type: `string`):

Locale used by the anonymous browser session and for locale-aware suggestion deduplication.

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

Optional two-letter ISO country code. It is applied to an Apify proxy configuration when one is supplied; the output also reports Pinterest's detected country when available.

## `expansionDepth` (type: `integer`):

0 collects suggestions only for your inputs; 1 or 2 recursively expands discovered suggestions into longer-tail keywords.

## `maxSuggestions` (type: `integer`):

Global maximum number of unique suggestion records saved across all seeds and recursive levels.

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

Optional Apify Proxy configuration. Direct anonymous access is the default; no residential fallback is enabled automatically.

## Actor input object example

```json
{
  "seedKeywords": [
    "summer wedding",
    "small balcony garden"
  ],
  "startUrls": [
    {
      "url": "https://www.pinterest.com/search/pins/?q=home%20office%20ideas"
    }
  ],
  "locale": "en-US",
  "country": "US",
  "expansionDepth": 0,
  "maxSuggestions": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Open the default dataset in the ranked overview view.

# 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 = {
    "seedKeywords": [
        "summer wedding",
        "small balcony garden"
    ],
    "startUrls": [
        {
            "url": "https://www.pinterest.com/search/pins/?q=home%20office%20ideas"
        }
    ],
    "locale": "en-US",
    "country": "US",
    "expansionDepth": 0,
    "maxSuggestions": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/pinterest-autocomplete-keyword-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 = {
    "seedKeywords": [
        "summer wedding",
        "small balcony garden",
    ],
    "startUrls": [{ "url": "https://www.pinterest.com/search/pins/?q=home%20office%20ideas" }],
    "locale": "en-US",
    "country": "US",
    "expansionDepth": 0,
    "maxSuggestions": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/pinterest-autocomplete-keyword-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 '{
  "seedKeywords": [
    "summer wedding",
    "small balcony garden"
  ],
  "startUrls": [
    {
      "url": "https://www.pinterest.com/search/pins/?q=home%20office%20ideas"
    }
  ],
  "locale": "en-US",
  "country": "US",
  "expansionDepth": 0,
  "maxSuggestions": 20
}' |
apify call automation-lab/pinterest-autocomplete-keyword-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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