# Amazon Keyword Discovery Tool (`khadinakbar/amazon-keyword-discovery-tool`) Actor

Amazon autocomplete across 20 markets with filters, localized queries, depth-3 recursion and monitoring. Basic packs from $0.00005; advanced workflows $0.25/1,000 rows. Startup and platform usage additional. No actual search volume.

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

## Pricing

from $0.25 / 1,000 advanced keywords

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### Amazon keyword discovery for listing and PPC research

Discover real Amazon autocomplete phrases from seed keywords, compare 20 marketplaces and departments, filter long tails, and keep only new phrases across repeated runs. Every keyword is a full JSON/CSV dataset row with source URL, collection time, best source rank and observed appearance count. No Amazon login or data-provider API key is required.

Use this Actor for autocomplete research, regional wording comparisons and a bounded keyword feed for agents. It does not return actual search volume, CPC, sales estimates, product rows or reverse-ASIN rankings. Appearance counts and wording labels are observations and heuristics, not demand or conversion estimates.

### Quick start

```json
{"keywords":["laptop stand"],"marketplaces":["US"],"expansionMode":"alphabet","maxResults":100}
```

Only `keywords` is required. Defaults: US, alphabet suffixes, all departments, 100 rows, 300 maximum lookups, automatic direct/residential routing. Direct HTTP is attempted first; proxy traffic, when needed, adds platform usage.

### Pricing and total cost

Pay per event **plus platform usage**. The live Pricing tab is authoritative. All plans receive complete individual JSON/CSV rows. Billing mode depends on the requested workflow:

- **Basic:** one marketplace, one department, no recursion or persistent monitoring. Localized templates, buyer/question/comparison/preposition expansion and filters are included.
- **Advanced:** automatically selected by more than one marketplace, more than one department, expansionDepth above 0, or monitorMode enabled. Advanced replaces both Basic pack fees.

| Event | Price | When charged |
|---|---:|---|
| Actor start | $0.00001 | Per GB RAM, minimum one |
| Basic first pack | $0.00005 | First up-to-100 delivered keywords, once per run |
| Basic additional pack | $0.00003 | Each additional up-to-10 delivered keywords |
| Advanced keyword | $0.00025 | Each delivered keyword in an Advanced job ($0.25/1,000) |

The first Basic pack covers100 rows; further packs cover10 rows. Basic packs do not cross run boundaries; the final partial pack rounds up once. At default memory, Basic event fees are $0.00006 for 1–100 rows, $0.00009 for 101–110, $0.00036 for 191–200, $0.00276 for 1,000 and $0.02976 for 10,000. Advanced event fees are $0.02501 for 100, $0.25001 for 1,000 and $2.50001 for 10,000.

Add actual compute, storage, transfer and proxy usage to every example. Empty, invalid and failed jobs have no result fee; startup and platform usage still apply. Monitoring with no new phrases still incurs startup and usage. Input descriptions and OUTPUT/RUN_SUMMARY identify the selected billing mode. Maximum event cost limits event fees; it does not cap platform usage.

### Inputs and limits

| Field | Use |
|---|---|
| `keywords` | 1–50 seed phrases, up to 100 characters each |
| `marketplaces` | Multiple markets in one run: US, CA, MX, BR, UK, DE, FR, IT, ES, NL, SE, PL, TR, AE, SA, JP, AU, SG, IN, IE |
| `expansionMode` | `seedOnly`, `alphabet`, `numbers`, `buyerModifiers`, `full`, `custom` |
| `customModifiers` | Up to 50 suffixes or templates, e.g. `best {seed}`; custom mode requires at least one |
| `department` / `departments` | One Amazon alias or 1–10 aliases, e.g. `aps`, `kitchen`, `electronics` |
| `expandPrefixAlphabet` | Add A–Z before each seed |
| `expandQuestions` | Add question prefixes in the market's default language |
| `expandComparisons` / `expandPrepositions` | Add locale-specific comparison/preposition suffixes |
| `expansionDepth` | 0–3 recursive levels, sharing the same maximum lookup budget |
| `mustIncludeTerms` / `excludeTerms` | Include any matching substring; exclude any matching substring |
| `mustContainSeed` / `minWordCount` / `onlyQuestions` | Require seed tokens, minimum words or question wording |
| `resultOrder` | `strongest`, `alphabetical`, `source`; grouped by seed and marketplace |
| `maxResults` | 1–10,000 full rows, default 100 |
| `maxResultsPerSeed` | 1–5,000 rows per root seed, default 1,000 |
| `maxLookups` | 1–2,000 requests, default 300; retries may add HTTP attempts |
| `includeSeedKeyword` | Keep suggestions equal to the seed, default true |
| `proxyMode` | `auto`, `direct`, `residential` |
| `monitorMode` / `monitorKey` | Emit unseen phrases using bounded caller-scoped history |

Localized templates cover German, French, Italian, Spanish, Portuguese, Dutch, Swedish, Polish, Turkish, Arabic and Japanese. US, UK, CA, AU, SG, IN and IE use English templates. These are wording aids, not guaranteed grammatical variants or guaranteed non-empty suggestions. Custom modifiers let you supply another language. India uses Amazon’s UK completion host with India’s marketplace ID; the source URL exposes both, and product search links remain amazon.in. Labels such as `buyingIntent` remain English wording heuristics; question detection also recognizes the built-in question prefixes. Word-count filters use whitespace, which is less useful for Japanese.

### Compare departments and discover long tails

```json
{"keywords":["kaffeemühle"],"marketplaces":["DE"],"departments":["aps","kitchen"],"expansionMode":"buyerModifiers","expandQuestions":true,"expandComparisons":true,"expandPrepositions":true,"expansionDepth":3,"maxLookups":120,"maxResults":100,"excludeTerms":["gebraucht"]}
```

Recursive candidates retain their root seed. Remaining requests are shared between the requested depth levels so early rounds cannot consume the whole recursive budget. Results are unique by marketplace, department and case-normalized phrase. A phrase can legitimately appear in multiple markets or departments. Request caps can limit coverage; source URLs make the resulting scope inspectable.

### Monitor new phrases

```json
{"keywords":["coffee grinder"],"marketplaces":["US"],"expansionMode":"alphabet","monitorMode":true,"monitorKey":"weekly-coffee","maxResults":100}
```

Run the same input again to emit only unseen phrases. The history belongs to the calling Apify user and this Actor/query contract; another caller cannot select that history by guessing a monitor name. Different seeds, filters, request budgets or expansion settings create another scope. Changing row caps or sort order can continue draining unseen results from the same scope. A new `monitorKey` starts fresh.

History retains the latest 10,000 identities, so evicted phrases may reappear. A history unused for 30 days resets on its next read. No schedule is created. Run a monitor scope sequentially: its best-effort overlap guard is not a distributed transaction or exactly-once guarantee. Named monitoring storage persists between runs; manage or delete it through your account when no longer needed.

### Output contract

Each dataset row includes `keyword`, `seedKeyword`, `matchedSeedKeywords`, `marketplace`, `marketplaceDomain`, `department`, `depth`, `position`, `bestRank`, `appearanceCount`, `lookupsForSeed`, `appearanceShare`, `firstSeenPrefix`, `matchedPrefixes`, `wordCount`, `characterCount`, `containsSeed`, `isSeedKeyword`, `isQuestion`, `buyingIntent`, `keywordType`, `amazonSearchUrl`, `sourceUrl`, `source`, `collectedAt` and optional source metadata (`thumbnailUrl`, `sourceRefTag`, `suggestionStrategy`, null when unavailable).

`OUTPUT` and `RUN_SUMMARY` contain outcomes, lookup counts, saved rows, named event counts and estimated event fees. `COMPLETE` means requested work completed; `PARTIAL` identifies failures, truncation or insufficient event budget; `VALID_EMPTY` means no matching new phrases; `INVALID_INPUT` identifies input errors; `UPSTREAM_FAILED` and `CONFIG_ERROR` fail honestly when no trustworthy completion is available. Inspect these records rather than relying only on run status.

Rows are validated before saving. Basic pack charges follow acknowledged row persistence. Advanced rows use the SDK coupled write-and-charge operation; named-event counters reconcile the accepted charge. An ambiguous write/charge or resurrection after a write attempt blocks automatic replay; inspect `KEYWORD_WRITE_STATE`, existing rows and charges. This favors avoiding duplicate billing over automatic recovery. It is not exactly-once processing. Interrupted jobs can contain useful partial rows.

### API and agents

```bash
curl -X POST 'https://api.apify.com/v2/acts/khadinakbar~amazon-keyword-discovery-tool/run-sync-get-dataset-items' \
  -H "Authorization: Bearer $APIFY_TOKEN" -H 'Content-Type: application/json' \
  -d '{"keywords":["laptop stand"],"marketplaces":["US"],"maxResults":100}'
```

For longer jobs start an asynchronous run, wait for completion, then read its dataset and `OUTPUT`. Export JSON, CSV, Excel or HTML through the Dataset tab. Limited permissions suffice; no owner token or elevated account access is required.

Agent prompt: “Find 100 Amazon US autocomplete phrases for laptop stand, exclude pink, return keyword, source rank, marketplace and Amazon search URL. Check OUTPUT for partial results and report total event fees plus usage.”

For hosted MCP use [Apify MCP](https://mcp.apify.com), inspect this Actor's explicit identifier and schema, call with complete input, then read the returned run/dataset. Public discovery and model preference require separate measurements; availability of an API is not evidence of agent preference. This Actor remains private until its owner publishes it.

### Workflow boundaries

For product listings and prices, use [Amazon Search Scraper](https://apify.com/khadinakbar/amazon-search-scraper). For Google search demand rather than Amazon autocomplete, consider [Keyword Search Volume API](https://apify.com/khadinakbar/keyword-search-volume-api). Neither autocomplete rank nor appearance frequency establishes Amazon monthly search volume.

Amazon controls endpoint availability and suggestions. Some valid seeds return none. Department aliases and source thumbnails vary by market. Automatic residential recovery can cost more than direct mode. Use bounded jobs and inspect warnings before scaling.

### Responsible use and support

This Actor reads public autocomplete without logging in. Users must review Amazon's Conditions of Use, applicable law and their own data-use policies. Amazon is a trademark of Amazon.com, Inc.; this independent tool is not affiliated with Amazon. Open an Actor issue with the run ID and a non-secret input example for support.

# Changelog

This Actor's version history is a separate document: https://apify.com/khadinakbar/amazon-keyword-discovery-tool/changelog.md

# Actor input Schema

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

Seed phrases to expand, such as a product type or niche ("laptop stand", "yoga mat"). 1-50 phrases, each up to 100 characters. Duplicates are removed case-insensitively. Use short head terms: the tool appends letters, digits, or buyer modifiers to them and records what Amazon's search box suggests.

## `marketplaces` (type: `array`):

Amazon markets to compare in one run. Twenty markets including India (IN) and Ireland (IE). Selecting more than one marketplace automatically selects Advanced pricing: $0.00025 per saved keyword, replacing Basic pack fees; startup and platform usage additional.

## `expansionMode` (type: `string`):

How each seed is expanded into autocomplete prefixes. seedOnly = 1 lookup (the seed itself, ~10 keywords). alphabet = seed + a..z (27 lookups, broadest long-tail). numbers = seed + 0..9 (sizes, counts, models). buyerModifiers = 23 buyer-intent patterns such as "best {seed}", "{seed} for women", "{seed} under 50". full = alphabet + numbers + buyerModifiers (+ customModifiers). custom = only your customModifiers.

## `customModifiers` (type: `array`):

Extra expansion patterns. Put {seed} where the seed phrase goes ("best {seed} for", "{seed} with"); patterns without {seed} are appended after it ("for small spaces" -> "laptop stand for small spaces"). Used by the custom mode and added to full mode. Up to 50 entries.

## `department` (type: `string`):

Amazon search department (search alias) that scopes suggestions. aps = All Departments (default). Pick a department to get category-specific suggestions, for example kitchen or pets.

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

Hard cap on full saved keyword rows, 1–10,000, default 100. Basic: first up-to-100 $0.00005 then $0.00003 per additional up-to-10. Advanced: $0.00025 per row. Startup and platform usage additional.

## `maxResultsPerSeed` (type: `integer`):

Cap on keyword rows saved per seed phrase (across its marketplaces), so one broad seed cannot use the whole budget. Defaults to 1000.

## `maxLookups` (type: `integer`):

Maximum distinct autocomplete lookups across all seeds, markets, departments and recursion levels, 1–2,000. Default 300. Requests consume metered platform usage even when no keyword matches.

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

When true (default), a suggestion that exactly equals the seed phrase is kept as a row (isSeedKeyword = true). Set false to return only new keywords.

## `departments` (type: `array`):

Compare 1–10 Amazon search aliases in the same run. Each department has distinct keyword provenance. Omit this field to use Department. This shares maxLookups with every seed and marketplace. Selecting more than one department automatically selects Advanced pricing: $0.00025 per saved keyword, replacing Basic pack fees; startup and platform usage additional.

## `expansionDepth` (type: `integer`):

Re-seed discovered phrases for 0–3 levels under one shared maxLookups budget. Setting depth above zero automatically selects Advanced pricing: $0.00025 per saved keyword, replacing Basic pack fees; startup and platform usage additional.

## `resultOrder` (type: `string`):

Choose strongest, alphabetical or source order. Strongest uses observed appearance counts and rank. Alphabetical sorts inside seed and marketplace groups. Source keeps discovery order within each group.

## `mustIncludeTerms` (type: `array`):

Keep keywords containing at least one supplied term. Matching ignores case. Combine this with other filters to target the final keyword bank. Empty input keeps all keywords.

## `excludeTerms` (type: `array`):

Remove keywords containing any supplied term. Matching ignores case. Removed keywords incur no keyword event. Empty input excludes nothing.

## `mustContainSeed` (type: `boolean`):

Keep phrases containing every word of their original root seed. Word order may differ. This works after recursive discovery too. Default false retains all source suggestions.

## `minWordCount` (type: `integer`):

Keep phrases with at least this many whitespace-separated words. Use 3 or more for English long-tail phrases. Word counts are whitespace based for every language. Default 0 applies no length filter.

## `onlyQuestions` (type: `boolean`):

Keep phrases starting with a recognized English or built-in locale question prefix. This wording heuristic does not prove question intent. Enable expandQuestions to search additional question prefixes.

## `expandPrefixAlphabet` (type: `boolean`):

Search a–z before each seed as well as the chosen expansion mode. This exposes different autocomplete lists from suffix letters. It shares the single maxLookups cap. Default false keeps existing expansion behavior.

## `expandQuestions` (type: `boolean`):

Prepend questions in the marketplace default language. English for US, UK, CA, AU, SG, IN and IE.

## `proxyMode` (type: `string`):

Use auto for direct requests with residential recovery. Direct skips residential recovery. Residential explicitly uses the metered Apify Residential route. Proxy traffic is platform usage and may dominate the cost of a large run.

## `expandComparisons` (type: `boolean`):

Append locale-specific comparison wording such as vs, oder or 比較.

## `expandPrepositions` (type: `boolean`):

Append locale-specific prepositions such as with, sans or mit.

## `monitorMode` (type: `boolean`):

Persist a caller-scoped history and emit only unseen phrases. Run the same scope sequentially; history retains up to 10,000 identities for 30 days. Enabling monitoring automatically selects Advanced pricing: $0.00025 per saved keyword, replacing Basic pack fees; startup and platform usage additional.

## `monitorKey` (type: `string`):

Separate monitoring histories, e.g. weekly-launch. Same caller, query settings and name reuse history. New name starts fresh. No schedule is created.

## Actor input object example

```json
{
  "keywords": [
    "laptop stand",
    "yoga mat",
    "dog bed"
  ],
  "marketplaces": [
    "US",
    "UK",
    "DE"
  ],
  "expansionMode": "alphabet",
  "customModifiers": [
    "{seed} for small spaces",
    "best {seed} for",
    "adjustable"
  ],
  "department": "aps",
  "maxResults": 20,
  "maxResultsPerSeed": 1000,
  "maxLookups": 300,
  "includeSeedKeyword": true,
  "expansionDepth": 0,
  "resultOrder": "strongest",
  "mustIncludeTerms": [],
  "excludeTerms": [],
  "mustContainSeed": false,
  "minWordCount": 0,
  "onlyQuestions": false,
  "expandPrefixAlphabet": false,
  "expandQuestions": false,
  "proxyMode": "auto",
  "expandComparisons": false,
  "expandPrepositions": false,
  "monitorMode": false,
  "monitorKey": "default"
}
```

# Actor output Schema

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

One row per unique Amazon keyword per marketplace, with rank, prevalence, and source URLs.

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

Final outcome, itemsPushed, keywordsDiscovered, and chargedEventCounts.

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

Per-marketplace lookup counts, routing, caps, and billing counters.

# 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": [
        "laptop stand"
    ],
    "marketplaces": [
        "US"
    ],
    "expansionMode": "alphabet",
    "department": "aps",
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/amazon-keyword-discovery-tool").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": ["laptop stand"],
    "marketplaces": ["US"],
    "expansionMode": "alphabet",
    "department": "aps",
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/amazon-keyword-discovery-tool").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": [
    "laptop stand"
  ],
  "marketplaces": [
    "US"
  ],
  "expansionMode": "alphabet",
  "department": "aps",
  "maxResults": 20
}' |
apify call khadinakbar/amazon-keyword-discovery-tool --silent --output-dataset

```

## MCP server setup

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

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/VqLjaTLe3viUQbtd9/builds/yteoVmzejWhDJO7Mt/openapi.json