Keyword Research & Expansion (Semrush)

Turn a handful of seed keywords into thousands of keyword ideas — related keywords, question keywords, and broad-match variants — each with search volume, keyword difficulty, CPC and competition. Excel export included.

How it works

seeds ─┬─▶ phrase_related     (semantically related)   ~40 units/row
       ├─▶ phrase_questions   (how/what/why searches)  ~40 units/row
       └─▶ phrase_fullsearch  (broad-match variants)   ~20 units/row
                    │
        dedup across seeds & sources ─▶ sort by volume ─▶ dataset + Excel

⚠️ Billing model (read before pricing)

Unit costs were measured against a live key, and they differ per report:

Report	Cost	Billing event
phrase_related	~40 units/row	keyword
phrase_questions	~40 units/row	keyword
phrase_fullsearch	~20 units/row	keyword_broad

That's 4× and 2× the cost of domain_organic (10 units/row) used by the other actors — so this one must be priced higher. Two events keep revenue aligned with the report actually used.

Keyword Difficulty is free here. These reports include Kd at no extra cost, unlike phrase_kdi (50 units/row). Always request it.

Rows are charged on fetch, because Semrush bills every returned row. Duplicates across seeds/sources are removed from your output but were still billed by Semrush.

Safety rails

• Seed dedup — seo tools and SEO TOOLS count once.
• limitPerSeed — bounds cost per seed per source.
• Server-side filters (minVolume, maxDifficulty, excludeKeywords) applied by Semrush before billing, so narrowing genuinely costs less.
• Charge-limit guard — per-event; stops before spending unbillable units.
• Units pre-flight — estimates cost and warns if your balance is short.
• Per-report error isolation — one failing report doesn't kill the run.

Setup

Set SEMRUSH_API_KEY as a secret environment variable on the actor.

Run locally

cd semrush-keyword-expander
npm install
$env:SEMRUSH_API_KEY = "your-semrush-api-key"   # PowerShell
node src/main.js

Example input:

{
  "seedKeywords": ["seo tools", "email marketing"],
  "sources": ["related", "questions", "broad"],
  "database": "us",
  "limitPerSeed": 200,
  "minVolume": 500,
  "maxDifficulty": 70
}

Input

Field	Meaning
seedKeywords / seedKeywordsText	starting keywords
sources	related, questions, broad (any combination)
database	country market (us, uk, de…)
limitPerSeed	ideas per seed per source — drives depth and cost
minVolume / maxDifficulty	server-side filters (also reduce cost)
excludeKeywords	drop keywords containing these terms
xlsxOutput	save formatted Excel (default on)
semrushApiKey	optional key override

Output

{
  "keyword": "how much does email marketing cost",
  "volume": 590,
  "difficulty": 31,
  "cpc": 4.12,
  "competition": 0.35,
  "results": 120000,
  "seed": "email marketing",
  "sources": "question",
  "database": "us"
}

sources lists every expansion type that surfaced the keyword (e.g. related, broad match).

Publish + pay-per-event

apify login
apify push

Publication ▸ Monetization ▸ Pay per event — delete the auto apify-default-dataset-item "Result" event, then add:

Event name	Title	Suggested price	Why
keyword	Keyword idea	$0.008	related + questions cost ~40 units
keyword_broad	Broad match keyword	$0.004	broad match costs ~20 units

Note these are 4× and 2× the price of your other actors' keyword event — because the underlying reports cost 4× and 2× more. Do not copy the $0.002 price across.

Roadmap

1. Intent tagging — classify each idea (informational / commercial / transactional).
2. Clustering — group ideas into topic clusters for content planning.
3. Chained expansion — feed top results back as seeds for a second wave.