Amazon Ranked Keywords Analyzer — find every keyword your product ranks for

Discover all the search keywords an Amazon ASIN ranks for, along with monthly search volume, ranking positions, ratings, pricing, badges (Best Seller / Amazon's Choice), and competitive metrics. Cursor-paginates upstream results via numeric offset (up to 1,000 keywords per run).

Why Use This Actor

Problem	How This Actor Solves It
Need to know what keywords an ASIN ranks for?	Run the Actor with the ASIN — get the full list of ranked keywords in one shot.
Need more than 100 keywords?	Set limit up to 1,000 (paid tier, upstream cap). To go beyond, run again with offset set to the previous run's _nextOffset.
Tracking multiple products?	Pass up to 10 ASINs in one run (comma or newline separated).
Need competitive context?	Each keyword row includes rank position, the SERP item's title/price/rating/badges, and the SERP URL for manual inspection.

What You Get

For every ranked keyword you receive:

• Keyword: text, monthly searchVolume, keywordLastUpdated
• Ranking: rankGroup, rankAbsolute, position (left/right), serpItemType (organic vs paid)
• SERP Item: domain, title, url, asin, imageUrl, priceFrom/priceTo, currency
• Signals: isBestSeller, isAmazonChoice, rating/ratingMax/ratingVotes, boughtPastMonth, specialOffers
• Context: seResultsCount (competing results count), checkUrl (the search that returned this row), serpItemTypes, deliveryInfo
• Provenance: query (echo), totalCount, nextOffset (for pagination)

Quick Start

1. Run with Example Input

{
  "asin": "B0C2JXSHSK",
  "marketplace": "United States",
  "language": "English",
  "limit": 100
}

Returns up to 100 ranked keywords for that ASIN on Amazon US. Free users are capped at 100 per ASIN per run — see Pricing & Limits below.

2. Export Your Results

• Open the run in Apify Console.
• Click the Dataset tab → Export → JSON / CSV / Excel.
• Or fetch the API: GET https://api.apify.com/v2/acts/<ACTOR_ID>/runs/<RUN_ID>/dataset/items

Input Reference

Top-Level Structure

{
  "asin": "B0C2JXSHSK\nB08N5WRWNW",
  "marketplace": "United States",
  "language": "English",
  "limit": 100,
  "offset": 0,
  "ignore_synonyms": false
}

asin — Amazon ASINs

Required	Type	Default	Description
No	string (textarea)	B0C2JXSHSK (test ASIN)	One or more ASINs, separated by commas or newlines. Up to 10 per run.

Examples:

B0C2JXSHSK
B08N5WRWNW
B09G3HRMVB

marketplace — Amazon Marketplace

Required	Type	Default	Description
No	select	United States	Amazon marketplace. Currently only US is supported by the upstream API — other markets return Invalid Field: 'location_code'.

language — Result Language

Required	Type	Default	Description
No	select	English	Language for keyword data. Only English is currently wired up.

limit — Keyword Limit (per ASIN)

Required	Type	Default	Min	Max	Description
No	integer	100	1	1000 (paid tier) / 100 (free tier)	How many keywords to retrieve per ASIN. Free-tier users are silently capped at 100 per ASIN per run — see Pricing & Limits.

offset — Pagination Offset

Required	Type	Default	Description
No	integer	0	Skip the first N keywords. To paginate: first run returns up to limit keywords with nextOffset on each row. Second run sets offset to that value to get the next batch.

ignore_synonyms — Ignore Synonyms

Required	Type	Default	Description
No	boolean	false	If true, the upstream API skips highly similar keyword variants and returns only core keywords.

Output Reference

Keyword Object — one row per ranked keyword

Field	Type	Description
keyword	string	The search keyword the ASIN ranks for.
searchVolume	number	Monthly search volume.
keywordLastUpdated	string|null	ISO timestamp of last keyword data update.
serpItemType	string|null	amazon_serp (organic) or amazon_paid (sponsored).
serpItemTypes	string[]	All SERP types this keyword returns.
rankGroup	number	Ranking position group.
rankAbsolute	number	Absolute ranking position.
position	string|null	left or right placement.
domain	string	Always www.amazon.com for Amazon results.
title	string	SERP item title.
url	string	SERP item URL.
asin	string	The ASIN of the SERP item.
imageUrl	string|null	Product image URL.
priceFrom	number|null	Lowest price in the price range.
priceTo	number|null	Highest price (null for fixed-price items).
currency	string	Currency code, e.g. USD.
isBestSeller	boolean	Best Seller badge flag.
isAmazonChoice	boolean	Amazon's Choice badge flag.
rating	number	Product rating (0–5).
ratingMax	number	Maximum rating value (always 5).
ratingVotes	number	Total ratings count.
boughtPastMonth	number|null	Estimated units bought in the past month.
deliveryInfo	object|null	Delivery info (free shipping, Prime, etc).
specialOffers	string|null	Special offer text.
seResultsCount	number	Total competing results for this keyword on Amazon.
serpLastUpdated	string|null	Last SERP data update.
serpPreviousUpdated	string|null	Previous SERP data update.
checkUrl	string|null	The Amazon search URL that produced this row.
query	object	Echo of the input that produced this row (asin, marketplace, language, etc).
totalCount	number	Total keywords upstream found for this ASIN.
nextOffset	number|null	Pass this into the next run's offset to fetch the next batch. null when exhausted.

Run Summary

Stored under the SUMMARY key in the default key-value store. The summary now includes a tier block so free vs. paid users can see exactly what gates applied to their run:

{
  "ok": true,
  "query": {
    "asins": ["B0C2JXSHSK"],
    "marketplace": "United States",
    "locationCode": 2840,
    "language": "English",
    "languageCode": "en",
    "limit": 100,
    "limitRequested": 500,
    "limitCapped": true,
    "offset": 0,
    "ignoreSynonyms": false
  },
  "tier": {
    "kind": "free",
    "rowsPerAsinCeiling": 100,
    "freeDailyRunLimit": 5,
    "freeDailyRunsUsed": 2
  },
  "perAsin": {
    "B0C2JXSHSK": { "totalCount": 5005, "collected": 100, "hasMore": true }
  },
  "result": { "totalCollected": 100, "rowsReturned": 100 },
  "errors": [],
  "apiRequests": 1,
  "completedAt": "2026-07-21T08:00:00.000Z"
}

limitCapped: true means the user-requested limit was higher than the per-tier ceiling and was silently lowered — see the tier block for the exact number. To unlock the full 1,000 per ASIN, switch on pay-per-event pricing in the Actor's Pricing tab.

Pagination — How It Works

Each ASIN returns up to limit keywords (default 100, free tier ceiling 100, paid tier ceiling 1,000). To paginate:

Run 1: offset=0    → 100 keywords (1-100),    nextOffset on rows = 100
Run 2: offset=100  → 100 keywords (101-200),  nextOffset on rows = 200
Run 3: offset=200  → 100 keywords (201-300),  nextOffset on rows = 300
...

When nextOffset is null, the upstream has no more results for this ASIN.

For paid users who want more than 1,000 keywords:

Run 1: offset=0,    limit=1000 → 1000 keywords (1-1000),   nextOffset on rows = 1000
Run 2: offset=1000, limit=1000 → 1000 keywords (1001-2000), nextOffset on rows = 2000
...

Upstream cap: limit is capped at 1000 per request (paid tier only). The Amazon Labs endpoint does not impose a hard offset + limit ceiling (unlike some other DataForSEO endpoints) — verified up to offset=9900.

Marketplace Coverage

The upstream DataForSEO Labs Amazon endpoint supports 4 marketplaces, each with a fixed list of Amazon-supported languages:

Marketplace	Location Code	Amazon-Supported Languages
United States	2840	English, Spanish
Egypt	2818	Arabic
Saudi Arabia	2682	Arabic
United Arab Emirates	2784	Arabic

Combining a marketplace with a non-supported language returns Invalid Field: 'language_code' (e.g. United States + Arabic). The Actor auto-falls-back to the marketplace's first Amazon-supported language when the user-supplied language is unsupported for the chosen marketplace.

If the upstream gains more locations, they'll be added to src/constants.js and the input schema in a single release.

Pricing & Limits

The Actor uses Apify's Pay per event pricing model. There is no separate monthly subscription. Every gate is enforced in src/lib/billing.js:

	Free tier	Paid tier (pay-per-event on)
Runs per day	5 (KV-scoped counter, resets at UTC midnight)	Unlimited
Keywords per ASIN per run	100	1,000 (upstream hard cap)
ASINs per run	10	10
Upstream DataForSEO charges	—	One row at keyword-result
Silent capping	limit > 100 → capped to 100 + limitCapped: true in SUMMARY	limit > 1000 → capped to 1000 + limitCapped: true in SUMMARY
tier.kind in SUMMARY	"free"	"paid"

How free-tier detection works

The Actor reads Apify's APIFY_USER_IS_PAYING environment variable, which is automatically set to 1 when the user has pay-per-event pricing turned on for the Actor, and 0 (or unset) otherwise. There is no manual toggle.

How capping works

When a free user submits limit higher than 100:

1. The Actor logs a warning at run start (visible in the run log).
2. The requested value is recorded in query.limitRequested.
3. The applied value is recorded in query.limit.
4. query.limitCapped is set to true in SUMMARY.

The dataset rows themselves are unchanged — only the count of returned rows is reduced.

How Pay per event works

Once you turn on pay-per-event pricing for the Actor (Apify Console → Actor → Pricing tab), every keyword row the Actor pushes to the dataset triggers one keyword-result event billed by Apify. The Actor never charges for runs that hit an error before producing rows.

FAQ

Q: Why are all rows in my old runs empty/null? A: If you ran the previous version (v0.1.x), it read the wrong upstream fields (items[i].keyword_info, items[i].serp_item) — those nested paths don't exist, so rows came out as null. v1.2 fixes the parser. Re-run the Actor to get real data.

Q: Why only 4 marketplaces? A: That's all the upstream DataForSEO Labs Amazon endpoint currently exposes (verified against /dataforseo_labs/locations_and_languages — Amazon's available_sources field only marks these 4 as Amazon-supported). The endpoint docs say the same: https://docs.dataforseo.com/v3/dataforseo_labs/amazon/ranked_keywords/live/

Q: Can I use Arabic in the United States marketplace? A: No. Each marketplace has a fixed set of Amazon-supported languages. United States only accepts English and Spanish. If you submit a non-supported pairing (e.g. United States + Arabic), the Actor falls back to the marketplace's first supported language (English in this case).

Q: Can I get more than 1000 keywords per ASIN? A: Yes — use offset pagination. Run 1 with offset=0, limit=1000, run 2 with offset=1000, limit=1000, etc. Paid tier only — free tier stops at 100 per ASIN per run.

Q: Why is my run returning only 100 rows even though I set limit=500? A: You're on the free tier. The Actor silently caps keywords-per-ASIN at 100 per run for free users. To retrieve up to 1,000 keywords per ASIN per run, open the Actor's Pricing tab in Apify Console and turn on pay-per-event billing — paid users are charged per row and have no keyword cap. Check the run SUMMARY for tier.kind and query.limitCapped to confirm.

Q: Why is my run failing with "Free tier limit reached" after only a few runs? A: Free tier is capped at 5 runs per day (the counter lives in the Actor's KV store and resets at UTC midnight). To lift the daily cap and the per-run keyword cap in one go, switch on pay-per-event billing for the Actor.

Q: How does ignore_synonyms work? A: It tells the upstream API to deduplicate highly similar keyword variants (e.g. "running shoes" vs "running shoe"). Useful for getting core keyword counts, not the long-tail.

Support

• Console run page: open the run for live logs + retry options.
• Email: sam.wang0420@gmail.com

License

MIT License — free to use and modify.