Pinterest Keywords Discovery Tool

What does Pinterest Keywords Discovery Tool do?

This Actor builds a bounded breadth-first discovery tree from seed terms using the public Pinterest search experience. It records each keyword only after Pinterest returns a source-backed autocomplete response whose request metadata matches the complete current keyword and whose suggestions retain every non-trivial parent token.

The result is a research graph, not a claim that every returned term is a ranking, volume, or trend measurement. Pinterest can change or withhold autocomplete data; the Actor reports failures and empty results in logs and OUTPUT_SUMMARY while keeping non-result rows out of the dataset.

Why use Pinterest Keywords Discovery Tool?

• Discover long-tail Pinterest search terms from a small set of seed phrases.
• Preserve parent-child relationships and breadth-first depth for downstream topic clustering.
• Prevent unrelated partial-query terms from contaminating the graph.
• Bound the discovery output and traversal with a maximum depth, global normal-record cap, timeout, retry, delay, and optional proxy. The crawler can still visit candidates already queued before the output cap is reached, so browser-request count can exceed the number of normal rows.

Apify supplies the dataset, run history, API access, scheduling, and optional proxy configuration. Optional response metadata is not invented, and a proxy can improve transport reliability but cannot bypass sign-in, CAPTCHA, or other access controls.

What data can Pinterest Keywords Discovery Tool extract?

Normal discovery fields

Field	Type	Meaning and source
entityType	string	Always pinterest_keyword_discovery for a normal row.
keyword	string	The normalized keyword whose autocomplete response was accepted.
depth	integer	0 for a seed; each queued child increments its parent depth by one.
parentKeyword	string	The normalized parent that caused the child to be queued; omitted for seeds.
suggestions	array of strings	Unique, lowercase, relevant suggestions returned for the complete current keyword.
suggestionCount	integer	Length of suggestions.
locale	string	Locale used for the autocomplete request.
sourceUrl	string	Pinterest search URL used for this keyword.
scrapedAt	string	ISO 8601 UTC time when the row was written.

When a keyword cannot produce a usable expansion, the dataset has no row for that keyword. Failures are described in the run log and OUTPUT_SUMMARY; successful empty responses remain empty results.

How to scrape Pinterest keyword expansions

1. Open the Pinterest Keywords Discovery Tool in Apify Console.
2. In Input, enter one or more complete seedKeywords.
3. Choose maxDepth and maxItems; keep them small for an initial smoke run.
4. Optionally set locale, timeout/retry controls, a delay, or Proxy Configuration.
5. Click Start and inspect the dataset, run log, and OUTPUT_SUMMARY.
6. Use BLOCKED, CAPTCHA, and NO_RELEVANT_SUGGESTIONS in the run summary to distinguish access errors from an empty successful result.

For API or automation use, send the same JSON object to the Actor’s API tab or run apify call jjHj7PvQ9MX3HumHQ --input-file input.json. Dataset and OUTPUT_SUMMARY links are exposed in the run output.

How much will it cost to discover Pinterest keywords?

Apify charges for browser time, storage, data transfer, and any configured proxy resources. Cost grows with the number of keywords actually visited, maxDepth, retries, response size, and delays. maxItems is a global cap on normal keyword records, not a guarantee that Pinterest will return that many expansions or a hard cap on browser requests: candidates already queued before the cap is reached may still navigate before the handler short-circuits. The repository's deterministic fixture tests do not represent Cloud collection cost.

Input

Input fields

Field	Type	Default	Required	Limits and behavior
seedKeywords	array of strings	—	yes	1–50 non-blank strings, each at most 200 characters. Values are trimmed, lowercased, deduplicated, and kept in first-seen order.
maxDepth	integer	2	no	Maximum emitted depth, from 1–4. Seeds are depth 0; 1 permits one child level; deeper values permit additional BFS levels.
maxItems	integer	100	no	Global maximum of 1–1000 source-backed keyword records.
locale	string	en_US	no	Two-letter language with optional two-letter region, such as en_US, en-GB, or fr_FR. Invalid or missing values fall back to en_US; hyphens are normalized to underscores.
requestTimeoutSecs	integer	90	no	Per-keyword request timeout from 30–180 seconds.
maxRequestRetries	integer	0	no	Crawlee retries for a failed keyword page request, from 0–2. Retries do not bypass a source block.
requestDelayMs	integer	0	no	0–5000 milliseconds after a normal keyword record is written. It is not a pagination control.
proxyConfiguration	object	direct	no	Apify/custom proxy settings. A proxy is used only when useApifyProxy is true or a non-empty proxyUrls array is supplied.

Unknown input fields are rejected. startUrls, an arbitrary query field, category/date filters, sortBy, page counts, detail toggles, credential fields, and arbitrary developer headers are not supported.

Minimal input

{
  "seedKeywords": ["interior design", "home decor"]
}

Bounded depth and locale

{
  "seedKeywords": ["interior design"],
  "maxDepth": 2,
  "maxItems": 20,
  "locale": "en_GB",
  "requestTimeoutSecs": 90,
  "maxRequestRetries": 0,
  "requestDelayMs": 250
}

Proxy input

{
  "seedKeywords": ["wedding ideas", "yoga"],
  "maxDepth": 1,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}

Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

Normal discovery record

{
  "entityType": "pinterest_keyword_discovery",
  "keyword": "interior design ideas",
  "depth": 1,
  "parentKeyword": "interior design",
  "suggestions": [
    "interior design ideas living room",
    "interior design ideas bedroom"
  ],
  "suggestionCount": 2,
  "locale": "en_US",
  "sourceUrl": "https://www.pinterest.com/search/pins/?q=interior%20design%20ideas",
  "scrapedAt": "2026-09-08T16:00:00.000Z"
}

Fallback behavior

For each queued keyword, the Actor observes matching AdvancedTypeaheadResource or TypeaheadResource responses from the public search page. If no usable response is intercepted, it types the complete keyword when possible, tries the same public resource wrappers directly, and then tries two legacy public typeahead endpoints. Every path still requires complete-keyword request metadata and parent-token relevance. No credential, stealth flag, or access-control workaround is used.

{
  "url": "https://www.pinterest.com/search/pins/?q=unknown",
  "error": "Pinterest returned no autocomplete suggestions demonstrably related to the full keyword \"unknown\".",
  "errorCode": "NO_RELEVANT_SUGGESTIONS",
  "scrapedAt": "2026-09-08T16:00:00.000Z"
}

OUTPUT_SUMMARY

{
  "status": "SUCCEEDED",
  "hasData": true,
  "normalRecords": 8,
  "diagnosticRecords": 0,
  "seedKeywordsRequested": 2,
  "keywordsRequested": 20,
  "keywordsCollected": 8,
  "maxDepth": 2,
  "proxyUsed": false,
  "source": "pinterest",
  "finishedAt": "2026-09-08T16:00:00.000Z"
}

keywordsRequested in the summary is the configured global maxItems cap retained for compatibility; seedKeywordsRequested is the number of distinct seeds, and keywordsCollected must equal the number of normal dataset rows. A successful empty response is summarized as NO_RESULTS; a failure with no keyword rows fails the run. When rows were already stored, a later failure preserves them and reports PARTIAL.

Limits, precedence, filtering, and deduplication

• Source and precedence: Each seed or queued child becomes https://www.pinterest.com/search/pins/?q=<encoded keyword>. There is no startUrls input and therefore no startUrls precedence rule.
• Traversal: The queue is breadth-first with one active browser request at a time. Seeds are depth 0. After a normal record is written, at most the first five relevant suggestions are queued as children, and only while maxDepth and the current normal-row count are below maxItems. Candidates already in the queue can still be navigated after the cap is reached, but the handler returns before extraction and emits no further normal rows.
• Depth: The normal row for a keyword is emitted at its queue depth. A seed row can therefore have depth: 0, and a maxDepth: 1 run can emit seed and first-child rows but does not expand children further.
• Pagination: There is no user-controlled pagination. Autocomplete suggestions are not paginated search results; the Actor does not claim to enumerate every possible related term.
• Request sequence: It accepts only intercepted typeahead requests whose data.options.term and, when present, source_url query match the complete current keyword. If needed, it tries the complete-keyword input, two public resource wrappers, and two legacy endpoints.
• Relevance: A suggestion must equal, start with, or contain every non-trivial parent token as an exact token or prefix. This allows ordinary inflections such as design → designer and rejects unrelated terms such as independence day for interior design.
• Deduplication: Seed keywords and queued children are deduplicated case-insensitively. Normal dataset rows are unique by normalized keyword; suggestion arrays are lowercase, deduplicated, relevance-filtered, and capped at 50 values by the record builder.
• Ordering and sorting: BFS queue order and Pinterest response order are preserved. There is no sortBy, ranking, category, date, or detail-enrichment option.
• Local tests: The repository test suite uses fixture records to exercise normalization and parent-relevance checks.
• Blocked behavior: Challenge pages, visible CAPTCHA frames, access-denied text, unusual-traffic text, and similar signals are logged and reflected in run status, never written as dataset rows. The Actor does not mutate anti-bot signals, spoof navigator.webdriver, or bypass sign-in.
• Proxy behavior: Proxy use is opt-in. If a requested proxy cannot be created, the run fails closed rather than silently falling back to direct access. proxyUsed describes the configured transport, not the availability of keyword data.

Tips and advanced options

• Start with one or two seeds, maxDepth: 1, and maxItems: 20; increase depth only after reviewing relevance.
• Use maxDepth: 2 for a second BFS layer. Because only five children per normal row are queued, the graph remains bounded even when Pinterest returns many suggestions.
• Keep locale stable when comparing markets, and use parentKeyword plus depth for graph joins.
• Raise maxRequestRetries only for transient navigation failures; retries do not fix an empty or blocked autocomplete response.
• The repository test suite uses fixture records to exercise normalization, parent checks, and summary validation without contacting Pinterest.
• For a flat list of suggestions without recursion, use the Pinterest Keyword Autocomplete Scraper instead.

Troubleshooting and support

No keyword rows are returned

A successful empty response completes with NO_RESULTS. A blocked or failed request is reported in the run log and summary; if no keyword rows were stored, the Actor run fails. NO_RELEVANT_SUGGESTIONS means the response did not meet the complete-parent contract; BLOCKED, CAPTCHA, or navigation codes indicate transport/source access issues. A proxy may improve transport but cannot make private or sign-in-gated suggestions public.

The graph stops earlier than expected

Check the global maxItems cap, maxDepth, and the five-child-per-record branching limit. Duplicate or token-unrelated suggestions are intentionally not queued. A child is never emitted solely because it appeared in an unverified partial-query response.

How do I report a problem or use the API?

Use the Actor’s Issues tab and include the run ID, sanitized input shape, OUTPUT_SUMMARY, a redacted run log, and the affected parent keyword. The API tab exposes the same input, dataset, and key-value-store endpoints. Do not include cookies, credentials, or private account data in an issue.

Privacy, legal, and affiliation

Use this Actor only for information Pinterest makes publicly accessible and in accordance with Pinterest’s Terms, robots directives, applicable law, and your own obligations. Do not use it to collect private data, evade access controls, or infer sensitive attributes. You are responsible for lawful use, rate choices, retention, and downstream processing. This Actor is an independent community tool and is not affiliated with, endorsed by, or sponsored by Pinterest.