Etsy Keyword Suggestions

What Etsy's own search box completes your keywords to, as a dataset: one row per unique suggestion, with the seed it came from, the exact query that produced it, and its position in Etsy's list.

Etsy completes a partial query from what buyers actually type. That makes its suggestions the closest public thing to a demand signal Etsy offers: a phrase Etsy completes is a phrase buyers search, and a seed with no completions is a phrase nobody types. This Actor reads the public suggestions endpoint the etsy.com search box itself calls, expands every seed letter by letter (candle a, candle b, ... candle 9) to surface the long tail, and can go one level deeper by querying every suggestion it found as a seed of its own.

Use case

You are writing the 13 tags for a listing, or naming a new product line, and you want the phrases Etsy's own buyers type rather than the ones you would guess. Put your seeds in, leave expansion on, and you get a few hundred real completions per seed with the query that produced each one - so you can see that candle w completes to candle warmer long before you would have thought of it, and that a seed you liked completes to nothing at all. That last case is the cheap finding: a phrase Etsy will not complete is a phrase you should not build a listing around.

What you get

One dataset row per unique suggestion:

field	meaning
keyword	the suggestion, exactly as Etsy returned it
seed	the seed keyword it was reached from
query	the exact query sent to Etsy that returned it
position	1-based position in that query's list (Etsy's order)
depth	0 seed query, 1 letter-by-letter expansion, 2 discovered suggestion queried as a seed
categories	category hints Etsy attached, when any
simplified_queries	Etsy's simplified forms of the query, when any
read_at	when the query was answered (UTC)

The key-value store also gets a RUN_SUMMARY: seeds, queries sent, empty answers, suggestions seen, unique rows pushed, and what stopped the run if a cap or a block did.

Sample output

Two rows from a run on 2026-09-06, exactly as the dataset holds them - the first from the seed query itself, the second from the letter-by-letter expansion that is what you are really paying for:

[
  {
    "keyword": "candle holder",
    "seed": "candle",
    "query": "candle",
    "position": 2,
    "depth": 0,
    "categories": [],
    "simplified_queries": [],
    "read_at": "2026-09-06T20:24:59.452Z"
  },
  {
    "keyword": "candle centerpieces",
    "seed": "candle",
    "query": "candle c",
    "position": 9,
    "depth": 1,
    "categories": [],
    "simplified_queries": [
      "c",
      "candle"
    ],
    "read_at": "2026-09-06T20:25:00.026Z"
  }
]

How to run it

1. Open the Actor in Apify Console and press Start. The defaults are one seed, expansion on, depth 1: 37 queries and about 250 rows, a few seconds.
2. Paste your own seeds into Seed keywords - one per line. Each seed costs 37 queries with expansion on, and returns a few hundred rows.
3. Read the dataset in Console, export it as JSON or CSV, or fetch it from the API with the run's defaultDatasetId.

Sample input

{
  "keywords": [
    "candle",
    "wall art"
  ],
  "expand": true,
  "depth": 1,
  "maxQueries": 200,
  "maxSuggestions": 500
}

Input

• keywords - the seeds to expand. One query each, plus 36 more per seed when expanding.
• expand - also query each seed followed by a space and each of a-z, 0-9. On by default. This is where the long tail comes from.
• depth - 0 seeds only; 1 seeds plus expansion; 2 also query every suggestion found as its own seed, one level deep.
• maxQueries, maxSuggestions - caps on requests sent and unique rows pushed. Defaults 2,000 and 10,000; 0 is unbounded. These caps are also your bill ceiling.
• concurrency, timeoutSecs - how the requests are paced.

Pricing

Pay per event, with no charge for starting the Actor and no charge for platform usage:

event	price	when
query	$0.002	one request sent to Etsy's suggestions endpoint
suggestion-row	$0.003	one unique suggestion pushed to the dataset

A suggestion seen again under another query is not charged again, and an empty answer costs one query and no rows. What a run costs:

run	events	price
default: 1 seed, expanded, depth 1	37 queries + about 250 rows	about $0.82
the sample input above (2 seeds, capped at 500 rows)	up to 74 + 500	at most $1.65
10 seeds, expanded, depth 1	370 + about 2,500	about $8.24
the default caps, whatever you feed them	2,000 + 10,000	$34.00

Lower maxQueries and maxSuggestions to bound a run below that.

Use it from code

The API tab on this page has ready-made snippets for Node.js, Python and curl, including run-sync-get-dataset-items, which starts a run and returns the rows in one call.

Use it from Claude or ChatGPT (Apify MCP)

This Actor is a tool your assistant can call directly, over the Model Context Protocol. Apify hosts the server at https://mcp.apify.com; adding ?tools= pins this Actor as one named tool rather than loading the whole store.

Claude Desktop or Claude Code - add a custom connector with the URL:

https://mcp.apify.com?tools=vital_tuxedo/etsy-keyword-suggestions

Any other MCP client (Cursor, VS Code, ChatGPT developer mode, your own agent) - add the server to its config:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=vital_tuxedo/etsy-keyword-suggestions",
      "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
    }
  }
}

Drop the headers block to use OAuth instead: the browser opens once so you can sign in to Apify and approve access. Then ask in plain language:

What does Etsy complete "soy candle" to? Give me the long tail, not the head terms.

Your assistant starts the run, waits for it and reads the dataset back. The per-event prices above are the whole cost - going through MCP adds nothing.

No Apify account at all? This Actor is flagged eligible for agentic payments, so an agent holding USDC on Base can buy a prepaid Apify token at https://agi.apify.com over x402 and run it with no account and no signup.

FAQ

Does this report search volume? No, and it will not pretend to. Etsy publishes no search volumes, so there are none here. position is where the suggestion sat in one query's list - an ordinal, not a volume, not a rank across queries, and not a difficulty score.

Does it sign in, or open listings and shops? No. It calls one public endpoint, the one the etsy.com search box calls, and reads its answer. No cookie, no account, no listing page, no shop page, and no scraping of search results.

Why did a seed return nothing? Etsy completed it to nothing. That is a real answer about the phrase, and it costs you one query event and no rows.

Do the suggestions change? Yes - they move with season and region, which is why every row carries read_at. Two runs a month apart are meant to differ; that difference is often the interesting part.

What does depth 2 cost? Each suggestion found at depth 1 becomes a seed of its own, so the query count multiplies rather than adds. Set maxQueries before you turn it on.

Running locally

npm install
npm start

Input is read from storage/key_value_stores/default/INPUT.json; the dataset lands under storage/datasets/default/.