# Keyword Explorer API — SemRush / Ahrefs / Moz Alternative (`khadinakbar/ahrefs-keyword-explorer`) Actor

Request bounded Google Ads metrics, matching terms, related terms, or keyword suggestions through DataForSEO. Returns normalized rows with endpoint provenance and terminal outcomes.

- **URL**: https://apify.com/khadinakbar/ahrefs-keyword-explorer.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** SEO tools, Automation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 dataforseo keyword results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Explorer — DataForSEO Research

This private Actor runs bounded Google keyword research through the [DataForSEO Labs API](https://docs.dataforseo.com/v3/dataforseo_labs-google-overview/). It returns normalized dataset rows for exact-keyword metrics (`overview`), matching keyword terms, related Google searches, and keyword ideas. The configured DataForSEO account is used only through encrypted Actor secrets; credentials never appear in dataset rows, `OUTPUT`, or `RUN_SUMMARY`.

### Best fit

Use this Actor when an SEO team needs repeatable, budget-bounded Google keyword research inside an Apify workflow. Every persisted row carries its research report, DataForSEO location and language targeting, seed terms, collection time, endpoint, task ID, and provider-cost attribution.

Use the adjacent [Keyword Rank Tracker](https://apify.com/khadinakbar/keyword-rank-tracker) after selecting target terms to measure a domain’s observed Google position. This Actor discovers and evaluates keywords; it does not track a domain’s ranking.

### Workflow

1. Add one or more seed keywords, a DataForSEO location code, and a language code.
2. Choose `overview` for metrics on exact terms, `matching_terms` for phrases containing the seed, `related_terms` for searches related to the seed, or `search_suggestions` for category-based keyword ideas.
3. The Actor removes blanks and duplicates, caps retained seeds, and persists no more than `maxResults` rows (maximum 100).
4. Each schema-valid row is written and charged as one `keyword-explorer-result` event. Duplicates and malformed provider rows are never billed.
5. Read the `keyword_overview` dataset view for prioritization and `RUN_SUMMARY` for endpoints, provider cost, output count, and terminal outcome.

### Quick start and inputs

| Input | Purpose |
|---|---|
| `report` | `overview`, `matching_terms`, `related_terms`, or `search_suggestions`. |
| `keywords` | One or more seed phrases; blanks and duplicates are removed. |
| `locationCode` | DataForSEO numeric market code, such as `2840` for the United States. |
| `languageCode` | Language code such as `en`. |
| `maxResults` | Hard persisted-row cap from 1–100; default 50. |
| `maxSeedKeywords` | Hard retained-seed cap from 1–10; default 3. Discovery reports can make one provider request per retained seed. |

#### Example: matching terms

```json
{
  "report": "matching_terms",
  "keywords": ["web scraping"],
  "locationCode": 2840,
  "languageCode": "en",
  "maxResults": 25,
  "maxSeedKeywords": 1
}
```

#### Example: exact keyword metrics

```json
{
  "report": "overview",
  "keywords": ["web scraping", "data extraction"],
  "locationCode": 2840,
  "languageCode": "en",
  "maxResults": 10,
  "maxSeedKeywords": 2
}
```

### Dataset output

Each row identifies the exact `report`, `locationCode`, `languageCode`, and `seedKeywords` used. Core fields include:

- `keyword`, `searchVolume`, `monthlySearches`, `cpcUsd`, competition fields, and, where supplied, `keywordDifficulty`;
- `mainIntent`, `serpFeatures`, and `searchVolumeTrend` when the selected DataForSEO Labs endpoint supplies them;
- `retrievedAt` plus `provenance` with the DataForSEO endpoint, provider task ID, and per-request provider cost.

```json
{
  "runId": "abc123XYZ",
  "report": "matching_terms",
  "keyword": "web scraping tools",
  "locationCode": 2840,
  "languageCode": "en",
  "seedKeywords": ["web scraping"],
  "searchVolume": 1200,
  "keywordDifficulty": 42,
  "mainIntent": "commercial",
  "retrievedAt": "2026-08-10T00:00:00.000Z",
  "provenance": {
    "source": "DataForSEO",
    "endpoint": "dataforseo_labs/google/keyword_suggestions/live",
    "taskId": "provider-task-id",
    "providerCostUsd": 0.01
  }
}
```

### Terminal outcomes

Every terminal path writes both `OUTPUT` and `RUN_SUMMARY`.

- `COMPLETE`: all returned valid rows up to the chosen cap were persisted.
- `PARTIAL`: at least one row was persisted, but later persistence or provider work could not finish.
- `VALID_EMPTY`: DataForSEO completed the selected query with no rows.
- `INVALID_INPUT`: correct the report, keywords, location code, or language code.
- `CONFIG_ERROR`: configure valid `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD` Actor secrets, or resolve account access/balance.
- `UPSTREAM_FAILED`: DataForSEO exhausted its bounded retries, or returned only rows outside the dataset contract.

### Pricing and provider usage

Apify Pay per event charges $0.01 for each persisted `keyword-explorer-result` row, plus $0.00005 for Actor start. Platform usage is passed through according to the Pricing tab. The Actor announces the maximum result-event amount before it queries the provider.

DataForSEO bills its API usage separately to the configured account. DataForSEO documents that Labs Keyword Overview provides metrics for specified keywords, while Keyword Suggestions, Related Keywords, and Keyword Ideas return discovery datasets through their own live endpoints. Start with one seed and a small result cap; inspect `RUN_SUMMARY.providerCostUsd` before scaling a workflow.

### API and MCP

```bash
curl -X POST "https://api.apify.com/v2/acts/khadinakbar~ahrefs-keyword-explorer/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "report": "related_terms",
    "keywords": ["web scraping"],
    "locationCode": 2840,
    "languageCode": "en",
    "maxResults": 25,
    "maxSeedKeywords": 1
  }'
```

Prompt card for an Apify MCP workflow:

> Run `khadinakbar/ahrefs-keyword-explorer` with `matching_terms` for `web scraping`, US location code `2840`, language `en`, and at most 25 rows. Read `keyword_overview` and `RUN_SUMMARY`, then report keyword, volume, difficulty when available, intent, provenance, provider cost, and terminal outcome.

### Best-results guidance

- Begin with one seed and 10–25 rows to validate targeting and account costs.
- Keep location and language consistent when comparing scheduled research runs.
- Choose `overview` for known terms, `matching_terms` for phrase expansion, `related_terms` for Google related-search expansion, and `search_suggestions` for category-based keyword ideas.
- Treat volumes, CPC, competition, difficulty, and intent as provider estimates, then combine them with first-party analytics for traffic and conversion decisions.
- Keep provider credentials in encrypted Actor secrets; public task inputs and API examples use only research parameters.

### Responsible use and data access

Use DataForSEO credentials from an account you are authorized to access, follow the applicable DataForSEO terms and your organization’s data-access rules, and retain research outputs according to your privacy and compliance obligations. This Actor processes keyword research data rather than personal data.

### Source documentation

- [DataForSEO Labs Keyword Overview](https://docs.dataforseo.com/v3/dataforseo_labs-google-keyword_overview-live/)
- [DataForSEO Labs Keyword Ideas](https://docs.dataforseo.com/v3/dataforseo_labs-google-keyword_ideas-live/)
- [DataForSEO Labs Keyword Suggestions](https://docs.dataforseo.com/v3/dataforseo_labs-google-keyword_suggestions-live/)
- [DataForSEO Labs Related Keywords](https://docs.dataforseo.com/v3/dataforseo_labs-related_keywords-live/)

### Builder's note

I designed this Actor around DataForSEO Labs because a keyword-research workflow benefits from one credentialed provider that can return both exact Google keyword metrics and Google keyword-discovery data. The Actor preserves a small, explicit row cap, records endpoint provenance and provider cost, and couples the Apify result event to the schema-valid dataset write. Its terminal records keep useful data, valid empty research, account configuration, and upstream availability distinct for downstream workflows.

# Actor input Schema

## `report` (type: `string`):

Choose the DataForSEO Labs report. Overview returns metrics for exact supplied terms. Matching terms, related terms, and keyword ideas discover new keyword opportunities from the supplied seeds.

## `keywords` (type: `array`):

One or more keyword phrases for the selected report, such as web scraping. Blank and duplicate values are removed before the seed cap is applied. This is not a domain or URL field.

## `locationCode` (type: `integer`):

Numeric DataForSEO location identifier used to target the report. Use 2840 for the United States, 2826 for the United Kingdom, or another supported DataForSEO location. This is not an ISO country code.

## `languageCode` (type: `string`):

DataForSEO language code used with the selected location, such as en for English. Defaults to en and must be two to ten letters. This is not a locale such as en-US.

## `maxResults` (type: `integer`):

Maximum normalized rows persisted across the entire run. The Actor requests no more than 100 rows and stops before charging beyond this cap. DataForSEO may bill its API request independently of this Apify row cap.

## `maxSeedKeywords` (type: `integer`):

Safety cap applied after blank and duplicate seeds are removed. Discovery reports can make one DataForSEO request per retained seed, so a smaller value makes provider usage predictable. Defaults to three and never exceeds ten.

## Actor input object example

```json
{
  "report": "matching_terms",
  "keywords": [
    "web scraping",
    "data extraction"
  ],
  "locationCode": 2840,
  "languageCode": "en",
  "maxResults": 50,
  "maxSeedKeywords": 3
}
```

# Actor output Schema

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

Normalized keyword rows returned through DataForSEO.

## `output` (type: `string`):

Terminal outcome, row count, provider cost, event charges, and warnings.

## `runSummary` (type: `string`):

Request context and provider diagnostics without credentials.

# 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 = {
    "keywords": [
        "web scraping"
    ],
    "locationCode": 2840,
    "languageCode": "en",
    "maxResults": 50,
    "maxSeedKeywords": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/ahrefs-keyword-explorer").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 = {
    "keywords": ["web scraping"],
    "locationCode": 2840,
    "languageCode": "en",
    "maxResults": 50,
    "maxSeedKeywords": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/ahrefs-keyword-explorer").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 '{
  "keywords": [
    "web scraping"
  ],
  "locationCode": 2840,
  "languageCode": "en",
  "maxResults": 50,
  "maxSeedKeywords": 3
}' |
apify call khadinakbar/ahrefs-keyword-explorer --silent --output-dataset

```

## MCP server setup

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

```

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/vGeGNydgXcdBIeka2/builds/3HLe1lqd8k9xdxtce/openapi.json