# ✨ Keyword Research Pro - Bulk Volume & CPC | Launch 80% Off (`winningsolutions/keyword-research-pro`) Actor

Check Google search volume, CPC, competition, and keyword ideas for up to 10,000 keywords per run. Filters, competitor domains, and white-label reports. $0.50 per 1,000 at launch. 230+ countries. Official search data. No scraping. No broken runs.

- **URL**: https://apify.com/winningsolutions/keyword-research-pro.md
- **Developed by:** [Winning Solutions](https://apify.com/winningsolutions) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 keyword results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

## Keyword Research Pro: Bulk Google Search Volume, CPC and Competition

An Apify Actor for **SEO keyword research** at scale. Paste a **seed keyword list** or enter a **competitor domain**, pick a **research mode**, and get structured metrics for up to **10,000 keywords per run** across **230+ countries**. No Google Ads account required.

It returns **average monthly search volume**, **CPC**, **competition**, **top-of-page bid ranges**, **keyword difficulty**, **search intent**, **backlink-gap signals**, and a **12-month volume series** for every term. Optional enrichments add **SERP competitors**, **AI search volume**, **extended trends**, and **clickstream demographics**. White-label **HTML** (+ CSV) and **PDF** reports are available for client delivery.

Designed for **SEO teams**, **PPC planners**, **agencies**, and **automation workflows**, the Actor uses **official search data APIs**.
Pay only for keywords returned, and cap spend with `maxTotalChargeUsd`. <br>

#### No scraping. No broken runs. No captchas to solve.

  <br>

> ## 🚀 Launch pricing: 80% DISCOUNT
>
> **$0.50 per 1,000 keywords**
>
> Launch rates apply until 31 October 2026. Regular rates start on 1 November 2026 which will also be very competitive. See the [price tables](#pricing).

<br>

### Use Cases

- Run **bulk search volume checks** on hundreds or thousands of keywords in one job
- Prioritize **SEO content** by real search demand before you write
- Plan **PPC / Google Ads budgets** with CPC and top-of-page bid ranges
- Spot **seasonality and demand shifts** with 12-month volume history
- Feed **agents and automation** with stable JSON field names for API, MCP, n8n, or Make

### Index

- [Use Cases](#use-cases)
- [Release Notes](#release-notes)
- [Research Modes](#research-modes)
- [Features](#features)
- [Optional Enrichments](#optional-enrichments)
- [Pricing](#pricing)
- [Input](#input)
- [Input Example](#input-example)
- [API and MCP usage](#api-and-mcp-usage)
- [Output Structure](#output-structure)
- [Output Example](#output-example)

### Release Notes

#### v1.0 - Initial public release

- **Five research modes:** Suggestions, Ideas, Related, Overview (metrics for your own list), and Competitor (domain seed)
- **Built-in filters:** min/max volume, max difficulty, search intent, include/exclude words, questions only, min/max word count
- **Backlink gap metrics:** average backlinks, referring domains, and domain rank of top-ranking pages (included in base metrics)
- **Optional enrichments:** SERP overview (top competitors), AI search volume, extended trend history
- **SERP feature flags:** SERP feature types (including AI Overview), clickstream demographics and normalized volumes
- **White-label reports:** HTML (+ CSV) and PDF with custom title, logo, subline, and domain line
- **Export toggles:** omit metric, intent, backlink, AI, SERP, or clickstream field groups from dataset rows
- **Pay-per-event pricing:** Actor start, per keyword result, optional SERP / AI / trends / clickstream / report charges; spending-limit safe
- **Launch pricing:** discounted flat rates until 31 October 2026. Regular rates apply from 1 November 2026.

### Research Modes

Choose how the Actor discovers or scores keywords. Set **Mode** in the Input tab or pass `mode` in your API call.

| Mode          | Seed required     | What it does                                             |
| ------------- | ----------------- | -------------------------------------------------------- |
| `suggestions` | Seed keywords     | Longtail phrases and close variants from each seed       |
| `ideas`       | Seed keywords     | Broad topic expansion from seed keywords (default)       |
| `related`     | Seed keywords     | Semantically related terms from each seed                |
| `overview`    | Seed keywords     | Metrics only for the keywords you provide. No expansion. |
| `competitor`  | Competitor domain | Organic keywords the domain ranks for                    |

If you provide only a competitor domain and leave the mode on the default, the Actor **auto-infers Competitor mode** and logs a seed warning.

**Ideas** expands by Google Ads category, not by semantic similarity. Use **Suggestions** for close variants, or add `includeWords` / `excludeWords`.

Use **Overview** when you already have a keyword list and need volume, CPC, and competition only. One dataset row per keyword.

### Features

🔍 **Five research modes:** Expand from seeds, score your own list, or map a competitor domain

🎯 **Built-in filters:** Volume, difficulty, intent, include/exclude words, questions only, exact phrase match, word-count bounds

📈 **Core SEO metrics:** Search volume, CPC, competition, keyword difficulty (0-100), bid range, monthly history, trend %, opportunity score

🔗 **Backlink gap:** Average backlinks and referring domains of pages ranking for each keyword

🌍 **230+ countries:** Location and language targeting for local and international research

📄 **White-label reports:** HTML (+ CSV) and/or PDF with your branding; first 500 keywords in the report table

🛡️ **Reliable by design:** Official search data APIs. No scraping. No broken runs.

#### Optional Enrichments

Turn these on in the Input tab when you need deeper data. Each optional enrichment is billed only when enabled and data is returned.

- **SERP overview** (`includeSerpOverview`) - Top organic competitors per keyword with position and visibility signals. Charged as **serp-overview** ($3.20 / 1,000 keywords at launch).
- **AI search volume** (`includeAiSearchVolume`) - LLM / AI search volume and AI share for GEO and AI-SEO workflows. Charged as **ai-search-volume** ($0.40 / 1,000 keywords at launch).
- **Trend data** (`includeTrends`) - Extended monthly search-volume history beyond the default series. Charged as **trends** ($2.30 / 1,000 keywords at launch).
- **Clickstream data** (`includeClickstreamData`) - Demographics and clickstream / Bing-normalized volumes. Charged as **clickstream** ($0.22 / 1,000 keywords at launch).
- **SERP feature flags** (`includeSerpInfo`) - SERP feature types (including AI Overview) and indexed result counts from the discovery call. No separate enrichment charge.

White-label **HTML** (+ CSV) and **PDF** reports are flat per-run charges when generation succeeds (**html-report** $0.05, **pdf-report** $0.05 at launch).

### Pricing

Launch pricing is active until 31 October 2026.
Base metrics cost **$0.50 per 1,000 keywords**, roughly a quarter of what comparable actors charge.
Reports cost **$0.05 each**.

Launch pricing is available to everyone. No code is needed.
Runs started before 1 November 2026 are billed at the launch rate.

From **1 November 2026** the regular rates apply.

#### Launch prices (until 31 October 2026)

| Cost item                         | Launch rate                      |
| --------------------------------- | -------------------------------- |
| Keyword result                    | $0.50 / 1,000 keywords           |
| SERP overview (optional)          | $3.20 / 1,000 keywords           |
| AI search volume (optional)       | $0.40 / 1,000 keywords           |
| Trend data (optional)             | $2.30 / 1,000 keywords           |
| Clickstream data (optional)       | $0.22 / 1,000 keywords           |
| HTML report (optional)            | $0.05 once per run               |
| PDF report (optional)             | $0.05 once per run               |
| Actor start                       | $0.02 (infrequent)               |
| Apify platform compute (RAM/time) | Billed by Apify platform pricing |

> **Cost per keyword (Overview, no enrichments): ~$0.00052** - about **$0.52 per 1,000 keywords** including Actor start. 100 keywords cost about **$0.07**.

No tier discounts during launch. Every plan pays the same launch rate.

#### Regular prices (from 1 November 2026)

| Cost item                         | Regular rate                     |
| --------------------------------- | -------------------------------- |
| Keyword result                    | $1.80 / 1,000 keywords           |
| SERP overview (optional)          | $5.00 / 1,000 keywords           |
| AI search volume (optional)       | $0.80 / 1,000 keywords           |
| Trend data (optional)             | $3.50 / 1,000 keywords           |
| Clickstream data (optional)       | $0.40 / 1,000 keywords           |
| HTML report (optional)            | $0.25 once per run               |
| PDF report (optional)             | $0.15 once per run               |
| Actor start                       | $0.02 (infrequent)               |
| Apify platform compute (RAM/time) | Billed by Apify platform pricing |

Volume discounts on keyword results down to **$1.20 per 1,000** apply from the Bronze plan upwards after 1 November 2026.

Optional enrichments are billed separately when enabled. Use `maxTotalChargeUsd` (default $25) to cap run cost. The Actor stops charging and keeps results already written.

#### Cost Examples (launch rates)

**Scenario A: 1,000 keywords, Overview, no enrichments**

- Actor start: $0.02
- 1,000 keyword results: $0.50
- **Total: ~$0.52**

**Scenario B: 1,000 keywords + HTML report**

- Actor start: $0.02
- 1,000 keyword results: $0.50
- HTML report: $0.05
- **Total: ~$0.57**

**Scenario C: 1,000 keywords + live SERP overview**

- Actor start: $0.02
- 1,000 keyword results: $0.50
- SERP overview (1,000 x $0.0032): $3.20
- **Total: ~$3.72**

**Scenario D: 1,000 keywords + AI search volume + PDF report**

- Actor start: $0.02
- 1,000 keyword results: $0.50
- AI volume (1,000 x $0.0004): $0.40
- PDF report: $0.05
- **Total: ~$0.97**

### Input

The Actor accepts the following input parameters (see the **Input** tab in the Apify Console for the full, interactive schema):

| Parameter                | Type    | Required                 | Default                   | Description                                                                                                          |
| ------------------------ | ------- | ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `mode`                   | string  | no                       | `ideas`                   | Research mode: `suggestions`, `ideas`, `related`, `overview`, or `competitor`.                                       |
| `seedKeywords`           | string  | for non-competitor modes | -                         | One seed keyword per line (up to 1,000). Required for Suggestions / Ideas / Related / Overview.                      |
| `seedDomain`             | string  | for `competitor`         | -                         | Bare hostname of the competitor (no `https://` or `www`). Required for Competitor; ignored otherwise (warning only). |
| `location`               | string  | no                       | `Germany`                 | Country or region for volume and competition data (English country name preferred).                                  |
| `language`               | string  | no                       | `de`                      | Two-letter ISO language code.                                                                                        |
| `limit`                  | integer | no                       | `100`                     | Maximum keywords returned for the whole run (1-10,000).                                                              |
| `maxTotalChargeUsd`      | number  | no                       | `25`                      | Stop the run once this USD amount has been charged.                                                                  |
| `limitPerSeed`           | integer | no                       | -                         | Optional cap per seed for Suggestions / Ideas / Related. Ignored in Overview and Competitor.                         |
| `minVolume`              | integer | no                       | -                         | Drop keywords below this monthly search volume.                                                                      |
| `maxVolume`              | integer | no                       | -                         | Drop keywords above this monthly search volume.                                                                      |
| `maxDifficulty`          | integer | no                       | -                         | Drop keywords harder than this score (0-100).                                                                        |
| `intentFilter`           | string  | no                       | -                         | Keep only `informational`, `commercial`, `transactional`, or `navigational`.                                         |
| `includeWords`           | array   | no                       | -                         | Keep only keywords that contain every listed word (case-insensitive).                                                |
| `excludeWords`           | array   | no                       | -                         | Drop keywords that contain any listed word (case-insensitive).                                                       |
| `questionsOnly`          | boolean | no                       | `false`                   | Keep only question-style keywords (who / what / how / why / when / where).                                           |
| `exactMatch`             | boolean | no                       | `false`                   | Suggestions / Related only: keyword must contain the exact seed phrase.                                              |
| `ignoreSynonyms`         | boolean | no                       | `false`                   | Prefer core keywords; skip near-duplicate synonym variants.                                                          |
| `includeSeedKeyword`     | boolean | no                       | `false`                   | Also return metrics for the seed itself (Suggestions / Ideas / Related).                                             |
| `includeSerpInfo`        | boolean | no                       | `false`                   | Add SERP feature types and result counts (no separate enrichment charge).                                            |
| `includeClickstreamData` | boolean | no                       | `false`                   | Add demographics and clickstream / Bing-normalized volumes (extra charge per keyword with data).                     |
| `includeSerpOverview`    | boolean | no                       | `false`                   | Enrich with top organic SERP competitors ($0.0032 / keyword at launch when data returned).                           |
| `includeAiSearchVolume`  | boolean | no                       | `false`                   | Enrich with AI / LLM search volume ($0.0004 / keyword at launch when data returned).                                 |
| `includeTrends`          | boolean | no                       | `false`                   | Add extended monthly search-volume history ($0.0023 / keyword at launch when data returned).                         |
| `htmlReport`             | boolean | no                       | `false`                   | Write white-label HTML (+ CSV) to the key-value store ($0.05 once at launch). Auto-enabled by custom title/logo.     |
| `pdfReport`              | boolean | no                       | `false`                   | Write white-label PDF to the key-value store ($0.05 once at launch; independent of HTML).                            |
| `reportTitle`            | string  | no                       | `Keyword Research Report` | Report headline. Non-default title auto-enables HTML report.                                                         |
| `reportLogoUrl`          | string  | no                       | -                         | Public logo URL. Setting a logo auto-enables HTML report.                                                            |
| `reportShowSubline`      | boolean | no                       | `true`                    | Show meta line (keyword count, location, language, mode).                                                            |
| `reportShowDomain`       | boolean | no                       | `true`                    | Show "for domain: ..." line on reports.                                                                              |
| `reportDomain`           | string  | no                       | -                         | Domain label for reports; falls back to competitor seed when empty.                                                  |
| `minWords`               | integer | no                       | -                         | Keep keywords with at least this many words (1-32).                                                                  |
| `maxWords`               | integer | no                       | -                         | Keep keywords with at most this many words (1-32).                                                                   |
| `disableMetrics`         | boolean | no                       | `false`                   | Omit volume, CPC, competition, difficulty, and related columns.                                                      |
| `disableIntent`          | boolean | no                       | `false`                   | Omit intent columns.                                                                                                 |
| `disableBacklinkGap`     | boolean | no                       | `false`                   | Omit backlink-gap columns.                                                                                           |
| `disableAiVolume`        | boolean | no                       | `false`                   | Omit AI volume columns (even if enrichment ran).                                                                     |
| `disableSerpOverview`    | boolean | no                       | `false`                   | Omit SERP competitor columns (even if enrichment ran).                                                               |
| `disableSerpInfo`        | boolean | no                       | `false`                   | Omit SERP-feature columns.                                                                                           |
| `disableClickstream`     | boolean | no                       | `false`                   | Omit demographics / clickstream columns.                                                                             |

### Input Example

#### Overview: bulk Volume / CPC for your list

```json
{
  "mode": "overview",
  "seedKeywords": "seo tools\nkeyword research\nbest crm for startups",
  "location": "United States",
  "language": "en",
  "limit": 1000
}
```

#### Competitor domain

```json
{
  "mode": "competitor",
  "seedDomain": "ahrefs.com",
  "location": "United States",
  "language": "en",
  "limit": 500,
  "minVolume": 100,
  "includeSerpOverview": true,
  "pdfReport": true,
  "reportTitle": "Competitor Keyword Map: Ahrefs",
  "reportLogoUrl": "https://cdn.example.com/brand/logo.png",
  "reportDomain": "your-agency.com"
}
```

#### Ideas from seed keywords

```json
{
  "mode": "ideas",
  "seedKeywords": "seo tools\nkeyword research",
  "location": "Germany",
  "language": "de",
  "limit": 100,
  "minVolume": 50,
  "maxDifficulty": 40,
  "intentFilter": "commercial",
  "includeAiSearchVolume": false,
  "htmlReport": false
}
```

### API and MCP usage

Runs write **one dataset row per keyword**. Optional reports are stored in the run **key-value store** as `HTML_REPORT` / `CSV_REPORT` and/or `PDF_REPORT`. Fetch rows from the default dataset after the run succeeds (or use the synchronous endpoint below).

**REST (sync, returns dataset items):** replace `YOUR_USERNAME`, `YOUR_API_TOKEN`, and use the same JSON body as in [Input Example](#input-example).

```bash
curl "https://api.apify.com/v2/acts/YOUR_USERNAME~keyword-research-pro/run-sync-get-dataset-items?token=YOUR_API_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"mode":"overview","seedKeywords":"seo tools\nkeyword research","location":"United States","language":"en","limit":50}'
```

**JavaScript (`apify-client`):**

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const input = {
  mode: 'overview',
  seedKeywords: 'seo tools\nkeyword research',
  location: 'United States',
  language: 'en',
  limit: 50,
};
const run = await client.actor('YOUR_USERNAME~keyword-research-pro').call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

// Optional reports (when enabled in input):
// await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('HTML_REPORT');
// await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('PDF_REPORT');
```

**Apify MCP server (AI agents):** configure your MCP client with URL `https://mcp.apify.com?tools=YOUR_USERNAME~keyword-research-pro` (you can combine multiple tools per [Apify MCP docs](https://docs.apify.com/platform/integrations/mcp)). Pass the API token via your client (for example an `Authorization: Bearer ...` header), not inside the Actor input JSON.

### Output Structure

The Actor returns structured data for each keyword. The table below lists the main fields. Optional dataset views in the Apify Console (**Overview**, **Metrics**, **Enrichments**, **Diagnostics**) may show a subset. When **disable** options are enabled, the corresponding keys are omitted from each row.

| Field                           | Type                   | Description                                                         | Example Value                    |
| ------------------------------- | ---------------------- | ------------------------------------------------------------------- | -------------------------------- |
| `keyword`                       | string                 | Keyword phrase                                                      | `"seo tools"`                    |
| `seed_keyword`                  | string | null          | Seed keyword or competitor domain that produced this row            | `"seo tools"`                    |
| `search_volume`                 | integer | null         | Average monthly search volume                                       | `12100`                          |
| `cpc`                           | number | null          | Cost per click (USD)                                                | `2.45`                           |
| `competition`                   | number | null          | Competition index (0-1)                                             | `0.67`                           |
| `competition_level`             | string | null          | `LOW` / `MEDIUM` / `HIGH`                                           | `"MEDIUM"`                       |
| `low_top_of_page_bid`           | number | null          | Lower Ads top-of-page bid                                           | `0.85`                           |
| `high_top_of_page_bid`          | number | null          | Upper Ads top-of-page bid                                           | `3.20`                           |
| `keyword_difficulty`            | integer | null         | Difficulty score 0-100                                              | `42`                             |
| `words_count`                   | integer | null         | Number of words in the keyword                                      | `2`                              |
| `search_intent`                 | string | null          | Primary intent                                                      | `"commercial"`                   |
| `search_intent_probabilities`   | object | number | null | Intent confidence                                                   | `0.82`                           |
| `foreign_intent`                | array | null           | Secondary intents                                                   | `["informational"]`              |
| `monthly_searches`              | array                  | Monthly volume history                                              | see below                        |
| `search_volume_trend`           | object | null          | MoM / QoQ / YoY trend percentages                                   | `{"monthly": 5.2}`               |
| `opportunity_score`             | number | null          | Volume / max(difficulty, 1)                                         | `288.1`                          |
| `categories`                    | array                  | Category IDs / labels from the API                                  | `[10004]`                        |
| `core_keyword`                  | string | null          | Core form of the keyword when provided by the API                   | `"seo tool"`                     |
| `avg_backlinks`                 | number | null          | Avg backlinks of top-ranking pages                                  | `120.5`                          |
| `avg_dofollow`                  | number | null          | Avg dofollow links                                                  | `95.2`                           |
| `avg_referring_pages`           | number | null          | Avg referring pages                                                 | `340`                            |
| `avg_referring_domains`         | number | null          | Avg referring domains                                               | `48.3`                           |
| `avg_domain_rank`               | number | null          | Avg domain rank of ranking pages                                    | `512`                            |
| `avg_main_domain_rank`          | number | null          | Avg main-domain rank                                                | `480`                            |
| `backlink_gap`                  | number | null          | Estimated backlinks needed to compete (same basis as avg backlinks) | `120.5`                          |
| `serp_item_types`               | array                  | SERP feature types when `includeSerpInfo` is on                     | `["organic","people_also_ask"]`  |
| `se_results_count`              | integer | null         | Indexed result count for the query                                  | `125000000`                      |
| `has_ai_overview`               | boolean | null         | Whether an AI Overview appears in the SERP                          | `true`                           |
| `gender_distribution`           | object | null          | Clickstream gender mix when enabled                                 | `{"female": 0.42, "male": 0.58}` |
| `age_distribution`              | object | null          | Clickstream age mix when enabled                                    | see API                          |
| `clickstream_search_volume`     | integer | null         | Clickstream volume                                                  | `9800`                           |
| `clickstream_normalized_volume` | integer | null         | Clickstream-normalized volume                                       | `11000`                          |
| `bing_normalized_volume`        | integer | null         | Bing-normalized volume                                              | `10500`                          |
| `ai_search_volume`              | integer | null         | AI / LLM search volume when enrichment is on                        | `420`                            |
| `ai_share`                      | number | null          | `ai_search_volume / search_volume`                                  | `0.03`                           |
| `ai_monthly_searches`           | array                  | Monthly AI volume history when AI enrichment is on                  | see API                          |
| `ai_search_volume_trend`        | object | null          | AI volume trend percentages when AI enrichment is on                | `{"monthly": 2.1}`               |
| `serp_competitors`              | array                  | Top organic competitors when SERP overview is on                    | see below                        |
| `detected_language`             | string | null          | Detected keyword language                                           | `"en"`                           |
| `is_another_language`           | boolean | null         | Language mismatch flag                                              | `false`                          |
| `_metadata.resultCharged`       | boolean                | Whether this row was charged as a keyword result                    | `true`                           |
| `_metadata.error`               | string | null          | Present on failure / empty diagnostic rows                          | *(varies)*                       |
| `_metadata.errorContext`        | string | null          | Extra error context when `error` is set                             | *(varies)*                       |

#### Key-value store reports

When enabled, download from the run's key-value store:

| Record        | Content                                    |
| ------------- | ------------------------------------------ |
| `HTML_REPORT` | White-label HTML report (`text/html`)      |
| `CSV_REPORT`  | CSV companion written with the HTML report |
| `PDF_REPORT`  | White-label PDF report (`application/pdf`) |

#### Output Example

```json
{
  "keyword": "seo tools",
  "seed_keyword": "seo tools",
  "search_volume": 12100,
  "cpc": 2.45,
  "competition": 0.67,
  "competition_level": "MEDIUM",
  "low_top_of_page_bid": 0.85,
  "high_top_of_page_bid": 3.2,
  "keyword_difficulty": 42,
  "words_count": 2,
  "search_intent": "commercial",
  "search_intent_probabilities": 0.82,
  "foreign_intent": ["informational"],
  "monthly_searches": [
    { "year": 2026, "month": 6, "search_volume": 11800 },
    { "year": 2026, "month": 5, "search_volume": 12100 }
  ],
  "search_volume_trend": {
    "monthly": 5.2,
    "quarterly": 8.1,
    "yearly": 12.4
  },
  "opportunity_score": 288.1,
  "categories": [10004],
  "core_keyword": "seo tool",
  "avg_backlinks": 120.5,
  "avg_dofollow": 95.2,
  "avg_referring_pages": 340,
  "avg_referring_domains": 48.3,
  "avg_domain_rank": 512,
  "avg_main_domain_rank": 480,
  "backlink_gap": 120.5,
  "serp_item_types": ["organic", "people_also_ask", "ai_overview"],
  "se_results_count": 125000000,
  "has_ai_overview": true,
  "ai_search_volume": 420,
  "ai_share": 0.03,
  "serp_competitors": [
    {
      "domain": "ahrefs.com",
      "avg_position": 2.1,
      "etv": 15400.5,
      "visibility": 0.42
    }
  ],
  "detected_language": "en",
  "is_another_language": false,
  "_metadata": {
    "resultCharged": true,
    "error": null,
    "errorContext": null
  }
}
```

# Actor input Schema

## `mode` (type: `string`):

Selects the discovery method and which seed field is required (keywords vs. domain).

Example: Ideas: broad topic expansion from seed keywords

## `seedKeywords` (type: `string`):

Starting keywords for Suggestions, Ideas, Related, and Overview. Enter one keyword per line (up to 1,000). Required for all modes except Competitor.

Example: seo tools

## `seedDomain` (type: `string`):

Domain whose organic rankings to analyze in Competitor mode. Required for Competitor; ignored otherwise. Use the bare hostname. Do not add https:// or www.

Example: ahrefs.com

## `location` (type: `string`):

Country or region used for search volume and competition data. Prefer the common English country name.

Example: Germany

## `language` (type: `string`):

Two-letter ISO language code for the keyword language you want to research.

Example: de

## `limit` (type: `integer`):

Maximum number of keywords returned for the whole run (1-10,000). Above 5,000, base keyword-result charges alone exceed about $2.52 at launch rates before enrichments.

Example: 100

## `maxTotalChargeUsd` (type: `number`):

Stops the run once this amount has been charged. Already written dataset rows are kept.

Example: 25

## `limitPerSeed` (type: `integer`):

Optional cap on how many expanded keywords each seed may contribute (Suggestions, Ideas, Related only). Ignored in Overview and Competitor. Leave empty to use only the global Result limit.

Example: 50 (with 2 seeds and Result limit 100, each seed adds at most 50 keywords)

## `minVolume` (type: `integer`):

Drop keywords whose monthly search volume is below this value.

Example: 100

## `maxVolume` (type: `integer`):

Drop keywords whose monthly search volume is above this value. Use this to skip ultra-competitive head terms.

Example: 10000

## `maxDifficulty` (type: `integer`):

Drop keywords harder than this score (0 = easiest, 100 = hardest).

Example: 40

## `intentFilter` (type: `string`):

Keep only keywords whose primary search intent matches this value.

Example: Commercial

## `includeWords` (type: `array`):

Keep only keywords that contain every listed word (case-insensitive).

Example: free

## `excludeWords` (type: `array`):

Drop keywords that contain any of these words (case-insensitive).

Example: jobs

## `questionsOnly` (type: `boolean`):

Keep only question-style keywords that start with words like who, what, how, why, when, or where.

Example: true → keeps "how to do keyword research", drops "keyword research tools"

## `exactMatch` (type: `boolean`):

Suggestions/Related only: returned keywords must contain the exact seed phrase as written.

Example: seed "seo tools" → keeps "best seo tools 2026", drops "seo software"

## `ignoreSynonyms` (type: `boolean`):

Return core keywords only and skip highly similar synonym variants that add little new coverage.

Example: true → keeps "keyword research", drops near-duplicates like "keyword researches"

## `includeSeedKeyword` (type: `boolean`):

Also return metrics for the seed keyword itself alongside the expanded results (Suggestions, Ideas, Related).

Example: true with seed "seo tools" → output includes a row for "seo tools" plus expansions

## `includeSerpInfo` (type: `boolean`):

Add SERP feature types (AI Overview, featured snippet, People Also Ask, and more) and result counts from the Labs discovery response. No extra enrichment call.

Example: true → fields like serp\_item\_types and has\_ai\_overview appear on each row

## `includeClickstreamData` (type: `boolean`):

Add demographics plus clickstream- and Bing-normalized volumes. Extra charge per keyword with data.

Example: true → fields like gender\_distribution and clickstream\_search\_volume appear on each row

## `includeSerpOverview` (type: `boolean`):

Enrich each keyword with its top organic SERP competitors (extra charge).

Example: true → serp\_competitors lists domains ranking for that keyword

## `includeAiSearchVolume` (type: `boolean`):

Enrich each keyword with AI/LLM search volume and AI trend data (extra charge).

Example: true → ai\_search\_volume and ai\_share appear on each row

## `includeTrends` (type: `boolean`):

Add extended monthly search-volume history for seasonality analysis (extra charge per keyword with trend data).

Example: true → monthly\_searches includes a longer month-by-month series

## `htmlReport` (type: `boolean`):

Write a white-label HTML (+ CSV) report to the run key-value store ($0.05 once when generated). Also auto-enabled when you set a custom report title or logo. Table includes at most the first 500 keywords.

Example: true → download HTML\_REPORT from the run's key-value store

## `pdfReport` (type: `boolean`):

Write a white-label PDF report using the same title, logo, subline, and domain options ($0.05 once when generated). Includes at most the first 500 keywords. Independent of the HTML toggle.

Example: true → download PDF\_REPORT from the run's key-value store

## `reportTitle` (type: `string`):

Headline shown at the top of HTML and PDF reports. Setting a non-default title auto-enables HTML report generation.

Example: Acme SEO Q3 Keyword Map

## `reportLogoUrl` (type: `string`):

Public image URL for the report header logo. Setting a logo auto-enables HTML report generation.

Example: https://cdn.example.com/brand/logo.png

## `reportShowSubline` (type: `boolean`):

Show the meta line under the title with keyword count, location, language, and mode.

Example: true → "288 keywords | Germany | de | mode: ideas"

## `reportShowDomain` (type: `boolean`):

Show a "for domain: ..." line under the title. Set the domain name in the field below.

Example: true → "for domain: acme.com"

## `reportDomain` (type: `string`):

Domain label shown as "for domain: ..." on reports. Falls back to the competitor seed domain when empty.

Example: acme.com

## `disableMetrics` (type: `boolean`):

Omit volume, CPC, competition, and difficulty columns from the dataset output.

Example: true → search\_volume, cpc, and keyword\_difficulty are left out

## `disableIntent` (type: `boolean`):

Omit search intent and intent-probability columns from the dataset output.

Example: true → search\_intent and search\_intent\_probabilities are left out

## `disableBacklinkGap` (type: `boolean`):

Omit average backlinks, referring domains, and backlink-gap columns from the dataset output.

Example: true → avg\_backlinks and backlink\_gap are left out

## `disableAiVolume` (type: `boolean`):

Omit AI search volume and AI trend columns from the dataset output (even if the enrichment ran).

Example: true → ai\_search\_volume and ai\_share are left out

## `disableSerpOverview` (type: `boolean`):

Omit SERP competitor columns from the dataset output (even if the enrichment ran).

Example: true → serp\_competitors is left out

## `minWords` (type: `integer`):

Keep only keywords with at least this many words. Use this as a longtail filter.

Example: 3 → keeps "best seo tools", drops "seo"

## `maxWords` (type: `integer`):

Keep only keywords with at most this many words.

Example: 4 → keeps "best seo tools", drops "best free seo tools online"

## `disableSerpInfo` (type: `boolean`):

Omit Labs SERP-feature columns from the dataset output.

Example: true → serp\_item\_types, se\_results\_count, and has\_ai\_overview are left out

## `disableClickstream` (type: `boolean`):

Omit demographics and clickstream/Bing-normalized volume columns from the dataset output.

Example: true → gender\_distribution and clickstream\_search\_volume are left out

## Actor input object example

```json
{
  "mode": "ideas",
  "seedKeywords": "seo tools\nkeyword research",
  "location": "Germany",
  "language": "de",
  "limit": 100,
  "maxTotalChargeUsd": 25,
  "questionsOnly": false,
  "exactMatch": false,
  "ignoreSynonyms": false,
  "includeSeedKeyword": false,
  "includeSerpInfo": false,
  "includeClickstreamData": false,
  "includeSerpOverview": false,
  "includeAiSearchVolume": false,
  "includeTrends": false,
  "htmlReport": false,
  "pdfReport": false,
  "reportTitle": "Keyword Research Report",
  "reportShowSubline": true,
  "reportShowDomain": true,
  "disableMetrics": false,
  "disableIntent": false,
  "disableBacklinkGap": false,
  "disableAiVolume": false,
  "disableSerpOverview": false,
  "disableSerpInfo": false,
  "disableClickstream": false
}
```

# Actor output Schema

## `results` (type: `string`):

HTTP URL of the default dataset items endpoint.

## `htmlReport` (type: `string`):

Key-value store record with the white-label HTML report when htmlReport input is enabled.

## `csvReport` (type: `string`):

Key-value store record with the CSV companion written with the HTML report.

## `pdfReport` (type: `string`):

Key-value store record with the white-label PDF report when pdfReport input is enabled.

# 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": `seo tools
keyword research`
};

// Run the Actor and wait for it to finish
const run = await client.actor("winningsolutions/keyword-research-pro").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": """seo tools
keyword research""" }

# Run the Actor and wait for it to finish
run = client.actor("winningsolutions/keyword-research-pro").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 '{
  "seedKeywords": "seo tools\\nkeyword research"
}' |
apify call winningsolutions/keyword-research-pro --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,winningsolutions/keyword-research-pro"
        }
    }
}

```

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/rzkQvd0Aa9yXUzuwL/builds/1x4Cr7aibO7L1q9I1/openapi.json