# Pinterest Autocomplete Keywords Scraper (`automation-lab/pinterest-seed-keyword-autocomplete`) Actor

Export Pinterest autocomplete query suggestions for seed phrases, with labels, IDs, rank and search links for recurring content planning. No login, pins, volume estimates or trend scores.

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

## Pricing

from $1.44 / 1,000 query suggestions

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Pinterest Autocomplete Keywords Scraper

Export **Pinterest autocomplete keywords** for your own seed phrases. Turn the anonymous search box's query suggestions into a dataset with labels, suggestion IDs, source order and search links. Use repeated snapshots to plan content; this Actor does not measure search volume or rank trends.

### What does it collect?

One-level query suggestions returned by Pinterest for each supplied seed. The Actor opens an anonymous browser session and reads Pinterest's autocomplete response. It excludes user accounts, pins, boards and rendered guide chips. No Pinterest login, API key or customer cookies are required.

### Who is it for?

- Content planners refreshing a seed roster before writing pin titles.
- Agencies organizing source-provided phrases into editorial briefs.
- Retail teams comparing wording for seasonal collections.
- Researchers keeping dated snapshots of search suggestions.

### Why use this Actor?

Keep the original seed beside every query so that overlapping suggestions remain attributable. Separate query-only `rank` from the original `resultIndex`, which can contain gaps where Pinterest inserted a user suggestion. The observed locale and country make localization limits visible instead of silently assuming US results.

### Getting started

1. Enter seed phrases such as `home decor` and `summer wedding`.
2. Set a global `maxItems` cap, or use the default 100.
3. Optionally select a browser language preference.
4. Start the Actor and inspect the Suggestions dataset.
5. Export JSON, CSV or Excel from Apify Console. Check the Summary for processed seeds and limit status.

```json
{"seeds":["home decor","summer wedding"],"maxItems":100,"locale":"en-US"}
```

### Input parameters

| Field | Default | Behavior |
| --- | --- | --- |
| `seeds` | Required | 1–50 nonempty strings, at most 150 characters each after trimming. |
| `maxItems` | 100 | Integer 1–1000; global saved suggestion cap, not per seed. |
| `locale` | en-US | Browser preference: en-US, en-GB, de-DE, fr-FR, es-ES or pt-BR. |

Leading/trailing whitespace is removed, internal whitespace collapsed, and identical normalized seeds deduplicated **case-sensitively**. Seeds run in input order. Queries are deduplicated by exact query text within each seed, not across seeds. Unsupported input fields and invalid combinations fail validation rather than being silently ignored.

A seed asks Pinterest for autocomplete expansions; it is not an exact phrase filter on pins or a claim that every returned phrase contains the seed. There is no recursive, a–z or unlimited expansion. A large maxItems does not increase Pinterest's upstream suggestion count. Later seeds are skipped after the cap is reached. Zero is not unlimited.

### Output fields

| Field | Meaning |
| --- | --- |
| `seed` | Normalized input phrase. |
| `query` | Pinterest's suggested query. |
| `label` | Source display label. |
| `suggestionId` | Source ID, or null when absent; not a permanent identity guarantee. |
| `rank` | One-based position among unique query suggestions for this seed. Not popularity. |
| `resultIndex` | Original zero-based source position; may contain gaps. |
| `searchUrl` | Public Pinterest search link provided for this query. |
| `locale` | Locale returned in source context, or null. |
| `country` | Country reported in source context, or null. |
| `countryFromIp` | IP country reported by Pinterest, or null. |
| `retrievedAt` | ISO timestamp of this observation. |

### Output example

A local anonymous lookup returned this record (IDs and timestamps vary):

```json
{
  "seed": "home decor",
  "query": "home decor ideas",
  "label": "home decor ideas",
  "suggestionId": "ac_VtSAni06",
  "rank": 1,
  "resultIndex": 0,
  "searchUrl": "https://www.pinterest.com/search/pins/?q=home+decor+ideas&rs=ac&len=10&source_id=ac_VtSAni06",
  "locale": "en-US",
  "country": "DE",
  "countryFromIp": "DE",
  "retrievedAt": "2026-10-16T14:05:28.271Z"
}
```

The Summary link opens the `SUMMARY` record in the default key-value store: saved rows, upstream attempts/responses, processed seeds and cap status. This report is included at no additional cost.

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

Pay-per-event pricing consists of a one-time **$0.001 start fee**, plus one `item` event per saved query suggestion. Per-suggestion rates are FREE $0.0027508, BRONZE $0.002392, SILVER $0.0018658 and GOLD/PLATINUM/DIAMOND $0.0014352. Check the Actor's Pricing tab for the applicable tier.

At the BRONZE rate, 1 suggestion is $0.003392, 10 are $0.02492, and 100 are $0.2402 including the start fee. These are estimates, not guaranteed invoices; tax and account conditions may differ. Tiers refer to qualifying aggregate monthly Apify Store spend, not the number of results from this Actor.

Only saved query suggestions count toward item charges. Retries, excluded user/pin entities, and the summary have no separate event charge. The same query under two different seeds is two records. A valid zero-result run may still incur the start fee. Set an appropriate maximum total charge in Console; Apify's charge cap may stop collection earlier than maxItems.

### Coverage and limitations

Autocomplete is a suggestion surface, not exhaustive keyword research. It can change by time, browser preference and network location. Locale sets browser language only; it cannot select IP country or guarantee localized suggestions. Inspect the reported country fields before comparing snapshots.

No volume estimates, trends, popularity scores, historical series, pin metrics or private analytics are inferred. Source position is not search demand. Suggestions are not promised to be stable between runs, and this Actor does not implement change detection or alerts itself.

### Failures and troubleshooting

Each seed has at most two attempts, using a fresh anonymous browser context on retry. Missing or malformed autocomplete responses and HTTP failures fail the run; they are not reported as empty success. A successful response containing no query suggestions legitimately produces no rows for that seed.

If a later seed fails, earlier saved rows remain **partial output**; do not interpret them as complete coverage. Check run status and logs before exporting. Reduce the seed list to investigate a failing phrase; repeated blind reruns do not guarantee recovery. The Actor does not solve CAPTCHAs, log in or accept paid proxy credentials.

### Integrations

Schedule the same seed roster in Apify and store each dataset in your warehouse or spreadsheet. Join snapshots on normalized seed plus query, not suggestion ID. Compare additions/removals downstream while retaining locale, country and timestamp.

Use Make, Zapier or n8n to run the Actor, wait for its terminal status, and export the default dataset. For editorial briefs, group suggestions by seed and let a human choose appropriate wording. No AI service is used by this Actor.

### API examples

Start once and retain the returned run and storage IDs. Replace the placeholder token in your own secure environment.

```bash
curl -X POST 'https://api.apify.com/v2/acts/automation-lab~pinterest-seed-keyword-autocomplete/runs' \
  -H "Authorization: Bearer $APIFY_TOKEN" -H 'Content-Type: application/json' \
  -d '{"seeds":["home decor"],"maxItems":20}'
```

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/pinterest-seed-keyword-autocomplete')
  .call({ seeds: ['home decor'], maxItems: 20 });
if (run.status !== 'SUCCEEDED') throw new Error(`Run ${run.id}: ${run.status}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems({ limit: 20 });
console.log(items);
```

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/pinterest-seed-keyword-autocomplete').call(
    run_input={'seeds': ['home decor'], 'maxItems': 20})
if run['status'] != 'SUCCEEDED':
    raise RuntimeError(run['status'])
print(client.dataset(run['defaultDatasetId']).list_items(limit=20).items)
```

### MCP use

Connect a stable Actor-specific subset:

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

Claude Desktop, Cursor and VS Code clients supporting HTTP MCP can use this equivalent configuration (supply Apify authentication securely in your client):

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

Example prompt: “Collect query suggestions for home decor, cap at 20, and group the returned phrases by seed. Do not call source order search volume.”

Discover actual names and input schemas with scoped `tools/list`; Actor selection also adds run/data helper tools, not exactly one tool. Discovery does not authorize execution. For an authorized call, start once and retain its run ID. A call may return before completion (server wait is at most 45 seconds). Poll the **same run** with bounded 2/4/8-second backoff capped at 10 seconds and a 120-second deadline. Set client timeout above the chosen wait plus transport margin. Recover a known run after client timeout rather than starting another. At the deadline report pending and stop polling; failures and partial results are not success.

After success, read explicit fields in pages of 20 source rows, offset 0 onward, at most 100 rows and 64 KiB of serialized results admitted to model context. Enforce the byte ceiling host-side, disclose omitted oversized rows, and report partial status and continuation offset. If the client cannot intercept responses, do not promise a hard byte cap. Keep full exports outside model context. These are consumer limits, not Actor coverage reductions. No numeric token-savings claim is made.

### Data handling and retention

Seed phrases are sent to Pinterest. Submit only topics you have permission to process, never secrets or sensitive personal queries. Only query suggestions and source context listed above are saved; user/profile objects are discarded. Browser cookies live only in the ephemeral context and are not persisted. Results, input and logs remain in your Apify storage under your account's retention settings; delete run storage through Apify when no longer needed. This Actor does not create a separate results archive.

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL query strings are removed; reports are retained for 30 days. Apify provides execution/storage; Pinterest receives lookup phrases; private GlitchTip receives failure diagnostics. There is no runtime LLM, training pipeline or external paid data supplier.

### Legality and support

This independent tool is not affiliated with or endorsed by Pinterest. Pinterest is named only to identify the data source. Use under Apify's standard terms, respect source terms and applicable law, and avoid abusive request volumes or collection of sensitive personal information. Use the Actor's Issues tab for support with a run ID and a nonsensitive example seed.

### FAQ

**Why is country DE when locale is en-US?** Browser language and IP location are different. Country fields describe observed source context, not a selected market.

**Why are there fewer rows than maxItems?** Pinterest limits its own suggestions. The cap is an upper bound, not a requested count; empty responses and duplicate queries can reduce rows.

**Does rank measure popularity?** No. It is order among the unique query suggestions returned in that observation.

**Can I monitor changes?** Schedule snapshots and compare them downstream. This Actor itself exports a snapshot and sends no change alerts.

### Related Actors

Use [Pinterest Scraper](https://apify.com/automation-lab/pinterest-scraper) for pin, board and profile records, or [Pinterest Trends Scraper](https://apify.com/automation-lab/pinterest-trends-scraper) for market-level trend records. Neither is a substitute for this autocomplete snapshot, and their outputs/pricing are separate.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/pinterest-seed-keyword-autocomplete/changelog.md

# Actor input Schema

## `seeds` (type: `array`):

One-level autocomplete lookup for 1–50 phrases, processed in input order. Leading/trailing whitespace is removed and internal whitespace collapsed; identical normalized seeds are deduplicated case-sensitively. Suggestions are source-provided expansions, not exact-match search results. No recursive or alphabet expansion.

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

Global cap on saved and charged query suggestions across all seeds, after per-seed exact-query deduplication. Default 100; range 1–1000; zero/unlimited is unsupported. Later seeds may not be processed once the cap is reached. This does not increase Pinterest's own suggestion count or promise that many results.

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

Browser locale preference, default en-US. This is not an IP country selector or a guarantee that Pinterest localizes results. Output reports the actual locale and country returned by Pinterest, or null when absent. No login, proxy or customer cookies are accepted.

## Actor input object example

```json
{
  "seeds": [
    "home decor",
    "summer wedding"
  ],
  "maxItems": 20,
  "locale": "en-US"
}
```

# Actor output Schema

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

Source query suggestions only.

## `summary` (type: `string`):

Processed seeds and limits.

# 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 = {
    "seeds": [
        "home decor",
        "summer wedding"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/pinterest-seed-keyword-autocomplete").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 = {
    "seeds": [
        "home decor",
        "summer wedding",
    ],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/pinterest-seed-keyword-autocomplete").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 '{
  "seeds": [
    "home decor",
    "summer wedding"
  ],
  "maxItems": 20
}' |
apify call automation-lab/pinterest-seed-keyword-autocomplete --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/pinterest-seed-keyword-autocomplete"
        }
    }
}
```

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/W1q8C1EyFccLAUGcz/builds/ZqS6KMe9aDB440fEj/openapi.json