Buy Box Map

Find the Buy Box seller, price, and delivery estimates for an Amazon product across regions in US, UK, DE, or FR. Searches run asynchronously and belong to the selected account.

Use bearer authentication. API tokens use the account bound to the token. The Buy Box Map tool must be enabled. Reading searches requires BUY_BOX_MAP_VIEW or BUY_BOX_MAP_MANAGE; starting a search requires BUY_BOX_MAP_MANAGE.

1. Start or reuse a search

Call POST /buy-box-map:

{
    "marketplace": "US",
    "asin": "B08N5WRWNW",
    "regenerate": false
}

The response contains data.search and data.progress. Save data.search.id to retrieve the search later. Both new and reused searches return HTTP 200.

By default, the newest non-error search for the same account, marketplace, and ASIN created within the last 24 hours is reused. If no reusable search exists, or its in-progress tracking has expired, a new search starts. Set regenerate: true to force a new search.

A new search reserves one BBM_SEARCHES use. The hold is charged when the search succeeds and released if it fails. Reusing a search does not reserve another use. Exhausted feature limits return 402; invalid input or a product that cannot be found returns 422.

2. Poll for completion

Call GET /buy-box-map/{search} with the search ID. Only searches belonging to the selected account can be retrieved.

data.search.status	Meaning
0	In progress
1	Ready: isReady is true and regional results are available
2	Error: hasError is true

data.progress is the processing percentage rounded to a whole number, or null when the search is ready, has failed, or progress is unavailable. Use data.search.status to determine completion, since regional processing may reach 100 before results are finalized. Polling also detects expired progress and marks stale searches as failed.

When ready, data.search.results contains regional entries:

• state and stateKey: the region label and map identifier.
• sellerId, sellerName, and sellerType: the Buy Box seller; seller types are 1 (Amazon), 2 (FBA), and 3 (FBM).
• price: the Buy Box price in major units of the marketplace currency.
• freeFrom / freeTo, paidFrom / paidTo, and primeFrom / primeTo: minimum and maximum delivery durations in days for free, paid, and Prime delivery.

Seller, price, and delivery fields can be null when unavailable. Results are an empty array while the search is in progress or has failed.

3. Browse search history

Call GET /buy-box-map for paginated history, including all search statuses.

Query parameter	Behavior
marketplace	Filter by marketplace code
search	Case-insensitive substring match on ASIN or product title
sort	created_at (default), title, or status
sortDesc	Descending when true (default); ascending when false
page	Page number, starting at 1
perPage	Number of searches per page; defaults to 15

The response contains data, links, and meta. History entries always have an empty results array; retrieve an individual search to get its regional results.

Common

General-purpose endpoints that combine data from multiple tools and are not specific to a single product area.

---

History endpoints

Endpoint	What it returns
GET /common/search-volume	Weekly and monthly search volume history for a keyword
GET /common/search-volume-batch	Weekly and monthly search volume history for up to 100 keywords per request
GET /common/sales-history	Estimated daily sales history for an ASIN
GET /common/bsr-history	Best Sellers Rank (BSR) history for an ASIN with category metadata
GET /common/ratings-history	Review count and average star rating history for an ASIN
GET /common/price-history	Buy Box price history for an ASIN

Keyword endpoints

Endpoint	What it returns
POST /common/keywords/top-asins	Top 10 ranked ASINs for each of the given keywords

Index Checker

Check keyword indexing for Amazon products and browse saved results in the selected account.

Use bearer authentication. API tokens use the account bound to the token. The Index Checker tool must be enabled.

1. Check the product

Call POST /index-checker/check-asin with marketplace and asin to look up product details before starting a check:

{
    "marketplace": "US",
    "asin": "B08N5WRWNW"
}

The response contains data with the product's asin, title, coverImage, isParent, isVariation, parent details, variationsCount, and a variations array of ASINs. A product that cannot be found returns 404; invalid input returns 422.

2. Start a process

Call POST /index-checker/start:

{
    "marketplace": "US",
    "asin": "B08N5WRWNW",
    "keywords": ["smart speaker", "wireless speaker"],
    "sellerId": null
}

Supply between 1 and 500 keywords. Keywords are trimmed, lowercased, and deduplicated. Provide sellerId to include storefront checks; otherwise those results are null.

Every call starts a new asynchronous process. The response contains data with the process resource. Save the numeric data.id for polling and deletion; the string data.processId is a separate internal tracking identifier. A newly created resource returns HTTP 201; invalid input returns 422.

3. Poll for results

Call GET /index-checker/process/{process} with the numeric process ID every 3–5 seconds until data.status is 2 (completed) or 3 (failed). Results are in data.keywordsData.

Polling refreshes saved progress for unfinished processes and can restart unfinished work when its progress tracking has expired. Only processes belonging to the selected account can be accessed. A missing process returns 404; access to another account's process returns 403.

4. Browse history

Call GET /index-checker/history for paginated history, including all process statuses and keyword indexing results.

Query parameter	Behavior
page	Page number, starting at 1
perPage	Processes per page; defaults to 100, minimum 1, maximum 1000
filters[asin]	Case-insensitive ASIN prefix match; maximum 255 characters
sort	createdAt (default), asin, keywordsCount, or status; unknown values fall back to createdAt
sortDesc	Descending when true (default); ascending when false

For example: GET /index-checker/history?filters[asin]=B08&perPage=20&sort=createdAt&sortDesc=true.

The response contains data, links, and meta. Each process includes its id, processId, product details, sellerId, keywordsCount, keywordsData, status, progress, createdAt, and updatedAt.

status	Meaning
0	Pending
1	Processing
2	Completed
3	Failed

progress is the percentage of completed keywords, rounded to a whole number. Completed and failed processes both report 100; use status to determine success.

Keyword results

keywordsData includes keyword, searchVolume, abaRank, competitors, and a keyword-level status using the same values as the process status. Metrics can be null when unavailable. abaRank is also null unless the selected account has an active Brand Analytics token.

The asinKeywordIndex, fieldAsinIndex, and storefrontIndex fields are boolean indexing results, or null when unavailable. storefrontIndex is null if no seller ID was provided. overallIndexStatus counts positive checks from 0 to 3, treating false and null as zero. Pending results can therefore have an overall value of 0; check their status before interpreting it. keywordsData is empty when no process data is stored.

5. Delete saved processes

Call DELETE /index-checker/delete with a JSON body containing ids, a non-empty array of positive numeric process IDs, for example {"ids": [42, 43]}.

Only saved processes belonging to the selected account are deleted. Unknown IDs and other accounts' IDs are ignored. Success returns 204 with no response body. Deleting saved processes does not cancel queued tasks.

Influencer Radar

Find Amazon influencers for potential product collaborations using profile details, content activity, categories, and featured product metrics. Search results include storefront codes, biographies, contact emails when available, social profile links, post counts, video statistics, and category metadata.

Search influencers

GET /influencer-radar/influencers returns matching influencers in data and search/pagination details in meta. Use a bearer API token with access to Influencer Radar and view or manage permission.

For example, search Brazil and show the most active creators first:

GET /influencer-radar/influencers?marketplace=BR&fullDataMode=false&page=1&perPage=10&sort=postsCount&sortDesc=true

Send fullDataMode explicitly. For paginated requests, also send page and perPage (1–100). These parameters should be included for correct pagination or full data response. Sorting defaults to postsCount ascending.

Filters

Pass filters using bracket notation, such as filters[videosCount][min]=10.

• Profile: name, exact storefront code, exact email, and emailExists.
• Content: ranges for videosCount, ideasCount, photosCount, upperVideosCount, lowerVideosCount, avgVideoLength (seconds), and avgVideoLikes; plus isLiveStream and isTopCreator.
• Biography: descriptionContains and descriptionExclude, using comma-separated terms.
• Social profiles: repeat filters[socialLinks][]=instagram for each required platform. Supported platforms are facebook, instagram, youtube, tiktok, and pinterest. Every selected profile must exist.
• Featured products: filters[asins][], filters[categories][], comma-separated filters[brand], and ranges for filters[avgRatingsCount], filters[avgReviewRating], and filters[avgPrice] in the marketplace currency.

emailExists, isLiveStream, and isTopCreator use 0 = any, 1 = yes, 2 = no. name, descriptionContains, brand, and asins[] match any supplied value within their respective filters. Different filters are combined to narrow the search.

Range filters accept optional min and max values. Bounds must be at least 1, and max must be greater than or equal to min when both are supplied. Review rating bounds must be between 1 and 5. Counts and video metric bounds are integers; price and review rating bounds can be decimal numbers. postsCount and last30DaysPostsCount are available for sorting and in results, but have no search range filters.

For root category filtering, pass the returned category's btgNodeId in filters[categories][], for example filters[categories][]=7841278011 for Books in Brazil. This differs from both the internal id and the category's nodeId. Subcategory node IDs are expanded to their descendants.

Pagination and search credits

A new search that returns results consumes one Influencer Radar search credit and returns meta.searchId. Pass that ID on subsequent requests to paginate or change sorting without another search charge:

GET /influencer-radar/influencers?marketplace=BR&searchId=297&fullDataMode=false&page=2&perPage=10&sort=postsCount&sortDesc=true

An existing searchId loads the saved filters, replacing any filters supplied in the request. Continue to send the same marketplace. An unknown searchId is treated as a new search. Repeating filters without a valid searchId can consume another credit, even when the results are cached.

Searches retrieve at most 1,000 influencers. meta.total is the number retrieved. A saved search reuses filters, not a permanent snapshot of the results.

Set fullDataMode=true to return all retrieved results at once, still capped at 1,000. In this mode, meta.current_page and meta.per_page are null.

A new search with no matches returns an empty data array, meta.total=0, and meta.searchId=null, and consumes no search credit. New searches require available search credits and are limited to 500 searches with results per account per 24-hour throttle window. Existing saved searches do not incur that search charge or increment that limit.

Response details

Unavailable profile fields and metrics are null; missing social profile URLs are also null. avgRatingsCount, avgReviewRating, and avgPrice describe featured products. They are not influencer ratings or collaboration fees. upperVideosCount and lowerVideosCount describe product video carousel placements. Category websiteDisplayGroup can be a string or an array of strings. Category sales estimation interval exceptions are an empty array when absent, or an object keyed by rank threshold when configured.

Keyword Research workflow

There are three search types. The response always contains a searchType field that tells you which type was created.

---

Single-ASIN search (searchType: 0) — synchronous

The search runs immediately and returns status: 2 (completed) right away. No polling needed.

1. POST /keyword-research/searches/asin/single with { "asin": "B08N5WRWNW", "marketplace": "US" }
2. GET /keyword-research/searches/asin/single/{id} — fetch keyword results.

---

Multi-ASIN search (searchType: 1) — asynchronous

Compares 2–10 ASINs. The search runs in the background — poll for progress, then fetch results.

1. POST /keyword-research/searches/asin/multi with { "asins": ["B08N5WRWNW", "B07XJ8C8F5"], "marketplace": "US" } — returns status: 0 (started).
2. GET /keyword-research/searches/{id}/progress — poll until searchStatus: 2 (completed) or searchStatus: 13 ( failed). Stop polling on either.
3. GET /keyword-research/searches/multi/{id} — fetch results.

---

Keyword search (searchType: 2) — asynchronous

Searches by a single keyword phrase. The search runs in the background. Results are returned in the same format as multi-ASIN.

1. POST /keyword-research/searches/keyword/single with { "keyword": "dog toys", "marketplace": "US" } — returns status: 0 (started). Accepts exactly one keyword phrase.
2. GET /keyword-research/searches/{id}/progress — poll until searchStatus: 2 (completed) or searchStatus: 13 ( failed).
3. GET /keyword-research/searches/multi/{id} — fetch results.

---

Search statuses

Status	Meaning
0	Started — search is running
2	Completed — results are ready
13	Failed — keyword or ASIN produced no results

Listing Analyzer

Analyze the listing quality of your Amazon products and compare them side by side with competitor listings. Each analysis runs asynchronously and produces a Listing Quality Score (LQS) with actionable per-attribute suggestions.

---

Concepts

Process — the central entity in Listing Analyzer. Each process analyzes one main ASIN together with a set of competitor ASINs on a specific marketplace. A process is created in a pending state, transitions to processing while the analysis is running, and finally reaches completed (or failed).

LQS (Listing Quality Score) — a 0–100 score that quantifies how well a listing is optimized.

lqsCharacteristics — the breakdown of the LQS. For each evaluated attribute it contains the score, maxScore, percent, machine-generated suggestions, and raw details.

Review insights — review count and rating distribution extracted from the product page.

---

Typical workflow

1. Start an analysis

Call POST /listing-analyzer/processes with the main ASIN, marketplace, and an optional list of competitor ASINs:

{
    "marketplace": "US",
    "mainAsin": "B08N5WRWNW",
    "competitorsAsins": [
        "B07XJ8C8F5",
        "B09B8YWXDF"
    ]
}

The response contains the new process's id — save it, you will need it to poll for completion.

Billing uses are held immediately for the total number of ASINs (main + competitors). The hold is charged only when the process completes successfully, and released if it fails.

---

2. Poll the process

GET /listing-analyzer/processes/{process} returns the current state of a process.

While the process is pending or processing, the call synchronously refreshes its status and returns the latest data. When the process is completed, the response is enriched with database data (BSR, price, ratings, etc.) for every analyzed ASIN.

The status field indicates progress:

Value	Meaning
0	Pending — analysis has been queued but not started
1	Processing — one or more ASINs are still being analyzed
2	Completed — all ASINs are scored; results is fully populated
3	Failed — the process could not be completed; held uses are released

Each entry in the results array represents one ASIN and includes:

• asin — the analyzed ASIN.
• title, mainImage, images — listing title, cover image, and full image gallery.
• lqs — the 0–100 Listing Quality Score.
• lqsCharacteristics — the per-attribute breakdown described above.
• videos — seller, influencer, and customer videos split by source.
• bsr, rootCategory, subcategoriesBsr — Best Sellers Rank data.
• price, rating, ratingsCount — buy box price and review metrics.
• bbSeller, bbSellerType, brand, manufacturer — buy box and brand details.
• parentAsin, variationsCount — variation family information.
• reviewInsights — review distribution insights.
• status, createdAt, startedAt, finishedAt — per-ASIN lifecycle timestamps.

---

3. Browse history

GET /listing-analyzer/processes returns a paginated list of completed processes for the selected account.

Filter by filters.asin (prefix match on the main ASIN) and sort by createdAt, mainAsin, competitorsCount, or status. Use perPage (up to 1000) and page for pagination. Only completed processes are returned.

---

4. Deleting processes

DELETE /listing-analyzer/processes removes one or more processes from history.

{
    "ids": [
        42,
        43
    ]
}

Only processes belonging to the selected account can be deleted. The endpoint returns 204 No Content on success.

Product Research workflow

Use Product Research to discover Amazon products that match specific criteria: niche, price range, BSR, sales volume, fulfillment type, and more.

Estimated sales and revenue

All estimated sales and revenue data are provided at the parent product (Parent ASIN) level only. For products with variations, these estimates represent combined totals across all variations under the Parent ASIN. We do not estimate sales or revenue separately for individual variations.

The existing sales and revenue fields contain parent-level values, as shown by their corresponding parent* fields, including null when data is unavailable:

Existing field (contains parent-level data)	Explicit parent-level field
sales	parentSales
salesTrend	parentSalesTrend
yearlySales	parentYearlySales
yearOverYearTrend	parentYearOverYearTrend
bestSalesPeriod	parentBestSalesPeriod
revenue	parentRevenue
netRevenue	parentNetRevenue

---

Basic product search

1. GET /product-research/products?marketplace=US&filters[bsr][max]=5000&filters[price][min]=20 — run a new search. Returns a paginated list of matching products and a meta.searchId. A request without searchId consumes one search credit only when the search returns at least one product. Empty searches consume no credit. Repeating the same filters without searchId starts a new search and consumes another credit if it returns at least one product.
2. Paginate through results using page and perPage. Pass searchId on subsequent page requests to continue the same search without consuming another credit.
3. GET /product-research/products/{id}/variations?searchId={searchId} — fetch variations for a product (only when PrProduct.variations is true).

Search limits

Each search has a hard limit of 10,000 products across all pages, including in fullDataMode.

fullDataMode=true returns the search results without pagination (requires the Export feature), but the same limit applies. meta.total reports the number of products available in the search results, not the total number of matches beyond this limit.

To discover more products, add filters to narrow the product niche and run multiple searches targeting different subcategories, title keywords, or price/BSR ranges. Start each new search with its own filters and without searchId; each request without searchId consumes one search credit only when the search returns at least one product.

---

Filtering by category

Categories let you scope a search to a specific Amazon browse node. The workflow mirrors how the app's category picker works:

Option A — Search by keyword (interactive picker)

1. GET /product-research/categories-tree?marketplace=US&searchQuery=Electronics — returns a nested tree of matching categories.
2. Pick the desired nodes, collect their nodeId values.
3. Pass them as filters[categories][]=7141124011&filters[categories][]=1055398 to GET /product-research/products.

Option B — Browse root categories then drill down

1. GET /product-research/categories?marketplace=US&level=2 — returns all top-level categories (level 2 = root nodes available in Product Research).
2. GET /product-research/categories/{id}/children — use the id field (not nodeId) to fetch direct subcategories. Repeat to traverse the tree as deep as needed.
3. Collect nodeId values and pass them to filters[categories][].

id vs nodeId: id is the internal database integer — used only in the /{id}/children path parameter. nodeId is the Amazon node identifier — this is what goes into filters[categories][].

---

Variation cache

Variations are served from an in-memory cache populated during the original search (TTL: 1 hour). If the cache has expired, GET /product-research/products/{id}/variations returns 404 — re-run the search via GET /product-research/products?searchId={id} to refresh it.

---

Browsing past searches

GET /product-research/searches lists all past searches for your account. Use the returned id as searchId to replay any past search without consuming a search credit.

Rank Tracker

Monitor keyword rankings for your Amazon products across organic and sponsored search results.

---

Concepts

Group — the central entity in Rank Tracker. Each group tracks one primary product (ASIN) on a specific marketplace and holds a list of keywords to monitor.

Product — an ASIN attached to a group. The first product becomes the primary product. Add more products to compare ranking performance across the same keyword set side by side.

Phrase — a keyword being tracked inside a group. Each phrase stores the current organic and sponsored rank for every product in the group, along with search volume, CPC, ABA data (when available), and full position history.

Tag — a label (with a custom color) used to organise groups, products, and phrases for filtering.

Boost — a flag on a phrase that signals SoldScope to collect position data more frequently for that keyword. Requires search volume ≥ 500.

Suggested phrase — a keyword suggested by SoldScope based on competitor analysis. Suggested phrases can be reviewed and applied to (or ignored from) a group's keyword list.

---

Typical workflow

1. Create a group

Call POST /rank-tracker/groups with the primary ASIN, marketplace, and an initial list of keywords:

{
    "asin": "B08N5WRWNW",
    "marketplace": "US",
    "trackAllVariations": false,
    "phrases": [
        "wireless earbuds",
        "bluetooth headphones sport"
    ]
}

If trackAllVariations is true and the ASIN is a child variation, SoldScope automatically resolves it to the parent ASIN and tracks all child variations under the group.

The response contains the new group's id — save it, you will need it for all subsequent calls.

---

2. Browse groups

GET /rank-tracker/groups returns a paginated list of all groups for the selected account, each enriched with aggregated keyword stats (top-10/50 keywords by organic and sponsored rank, total search volume in those positions).

Filter by marketplace, search (ASIN or title), or tags[] to narrow the list.

---

3. Manage products

A group can track multiple products against the same keyword set.

List products: GET /rank-tracker/groups/{groupId}/products

List products with aggregated ranking stats: GET /rank-tracker/groups/{groupId}/products-with-stats returns average organic/sponsored rank, number of ranking keywords, and total ranked search volume per product.

Add products: POST /rank-tracker/groups/{groupId}/products

{
    "products": [
        {
            "asin": "B07XJ8C8F5",
            "trackAllVariations": false
        },
        {
            "asin": "B09B8YWXDF",
            "trackAllVariations": false
        }
    ]
}

Remove products: DELETE /rank-tracker/groups/{groupId}/products with a products array of product IDs in the request body.

---

4. Manage keywords

Read the current keyword list: GET /rank-tracker/groups/{groupId}/phrases-list returns the raw list of tracked keywords for a group.

Replace the entire keyword list: POST /rank-tracker/groups/{groupId}/phrases-list replaces all tracked keywords with the supplied list. Use this for bulk updates.

{
    "phrases": [
        "wireless earbuds",
        "sport bluetooth earphones",
        "running headphones"
    ]
}

Delete keywords: DELETE /rank-tracker/groups/{groupId}/phrases with a phrases array of keyword IDs in the request body.

Suggested keywords

SoldScope can automatically discover new keywords for a group based on competitor data and AI analysis.

GET /rank-tracker/groups/{groupId}/suggested-phrases returns a paginated list of pending keyword suggestions for a group.

Apply suggestions (add them to the keyword list): POST /rank-tracker/groups/{groupId}/suggested-phrases

{
    "suggestionsIds": [
        55,
        56
    ]
}

Ignore suggestions (dismiss them permanently): DELETE /rank-tracker/groups/{groupId}/suggested-phrases

{
    "suggestionsIds": [
        57,
        58
    ]
}

On-demand AI keyword suggestions: GET /rank-tracker/suggested-keywords returns up to 300 keyword suggestions generated by SoldScope AI.

Supply either:

• groupId — to base suggestions on an existing group's products and current keywords.
• asins[] + marketplace — to get suggestions for any set of ASINs without a group.

---

5. View keyword rankings

GET /rank-tracker/groups/{groupId}/products/{productId}/phrases/v2 returns the current ranking data for every keyword in the group for a specific product.

Each phrase in the response includes:

• id — the unique keyword ID within this group (used for deleting, tagging, or toggling boost).
• dataId — the phrase–product record ID (used to fetch position history).
• organicPosition, organicPage, organicAsin, organicPreviousPosition — current and previous organic rank data.
• sponsoredPosition, sponsoredPage, sponsoredAsin, sponsoredPreviousPosition — current and previous sponsored rank data.
• searchVolume, cpc, cpcMin, cpcMax — market data.
• abaSearchFrequencyRank, abaTotalClickShare, abaTotalConvShare — Amazon Brand Analytics data, when available.

---

6. View position history

GET /rank-tracker/groups/{groupId}/positions-chart-data/{id} returns the full rank history for a specific keyword–product pair, suitable for rendering a chart.

The {id} path parameter is the dataId field returned by GET /rank-tracker/groups/{groupId}/products/{productId}/phrases/v2.

Pass type=2 to retrieve sponsored rank history instead of organic (default type=1).

---

Boost

Boosting a keyword signals SoldScope to collect rank data more frequently for that phrase.

Requirements: search volume ≥ 500.

Toggle boost on or off: POST /rank-tracker/groups/{groupId}/phrases/{phraseId}/toggle-boost-state

{
    "isBoosted": true
}

---

Tags

Tags let you label and filter groups, products, and keywords. Tags are account-wide — the same tag can be applied across multiple groups, products, and phrases.

List all tags: GET /rank-tracker/tags

Create a tag: POST /rank-tracker/tags

{
    "title": "High priority",
    "color": "#FF5733"
}

Rename / recolor a tag: PUT /rank-tracker/tags/{tag}

Delete a tag: DELETE /rank-tracker/tags/{tag} — the tag is automatically detached from all groups, products, and phrases.

Assigning tags

Target	Endpoint
Group	POST /rank-tracker/groups/{groupId}/tags
Product	POST /rank-tracker/groups/{groupId}/products/{productId}/tags
Keyword	POST /rank-tracker/groups/{groupId}/phrases/{phraseId}/tags

All three endpoints accept the same body and replace the current tag set:

{
    "tagsIds": [
        1,
        3
    ]
}

Pass an empty array to remove all tags from the entity.

---

Export

Two export modes are available in Rank Tracker:

• Simple export — up to 92 days of daily organic positions for one product, returned synchronously in a single API call. No file download required.
• Async export — full position history (organic + sponsored) over any date range, exported to a CSV/JSON file and processed in the background.

---

Simple export (heatmap mode)

The simplest way to extract historical rank data is to use the existing keyword positions endpoint in heatmap mode. Instead of a file, the data comes back as regular JSON — one object per keyword, with a r_YYYY-MM-DD field for each day in the requested range.

Call GET /rank-tracker/groups/{groupId}/products/{productId}/phrases/v2 with the following parameters:

heatmap=true
heatmapDateFrom=2026-02-01
heatmapDateTo=2026-04-28
perPage=10000

Maximum date range is 92 days. Set perPage high enough to cover the entire keyword list in one page.

Each item in data[] is a standard RtPhrase object extended with one extra field per calendar day. Each r_YYYY-MM-DD field is an object with three keys:

Key	Type	Description
date	string	The calendar date in YYYY-MM-DD format.
rank	integer | null	Organic position for that day. null = no data collected. 0 = product not found in results.
amazon_choice	boolean	Whether the tracked product held the "Amazon's Choice" badge on this keyword on that day.

{
    "id": 101,
    "phrase": "wireless earbuds",
    "searchVolume": 45000,
    "organicPosition": 7,
    "r_2026-02-01": {
        "date": "2026-02-01",
        "rank": 12,
        "amazon_choice": false
    },
    "r_2026-02-02": {
        "date": "2026-02-02",
        "rank": 11,
        "amazon_choice": true
    },
    "r_2026-02-03": {
        "date": "2026-02-03",
        "rank": null,
        "amazon_choice": false
    },
    "r_2026-04-28": {
        "date": "2026-04-28",
        "rank": 7,
        "amazon_choice": false
    }
}

The rank field in each heatmap object reflects the position type controlled by resultsType: organic (default) or sponsored. Both types are available in synchronous heatmap mode; the async export is only needed for full multi-product history over longer periods.

When to use this approach:

• You need daily rank data per keyword for a single product over up to 3 months.
• You want a simple synchronous response without polling or file downloads.
• You are building a dashboard or chart and want to page through keywords incrementally.

---

Heatmap summary widgets

Instead of fetching per-keyword daily data, you can get pre-aggregated daily metrics in a single call:

GET /rank-tracker/groups/{groupId}/products/{productId}/heatmap-widgets

Pass the same heatmapDateFrom, heatmapDateTo, resultsType, search, and onlyBoosted parameters as the phrases endpoint. The response contains four arrays sorted newest-to-oldest:

Widget	value type	Description
visibility	float 0–100	Search-volume-weighted rank score. Each keyword is weighted by √(searchVolume) × rankWeight (CTR model). Higher = better.
average	integer	Average rank across all keywords. Keywords not found in results count as position 306. Lower = better.
amazonChoice	integer	Number of keywords for which the tracked product held the "Amazon's Choice" badge.
distribution	object	Keyword count per rank bucket: 1-3, 4-10, 11-50, 51-100, 100+, notTracked.

Each entry in visibility, average, and amazonChoice also carries:

• complete — true when all keywords have been scraped for that day (false for today while scraping is in progress).
• coverage — percentage of keywords scraped (0–100). Always 100 for past dates.

---

Async export (historical keyword positions)

The async export generates a CSV or JSON file with historical keyword position data. Because the data volume can be large, the export is processed in the background.

The granularity field controls row density:

Value	Default	Row density	Date column format
raw	yes	One row per keyword per snapshot	YYYY-MM-DD HH:MM
daily		One row per keyword per calendar day	YYYY-MM-DD

In daily mode, positions are aggregated using the median of all snapshots for that day.

Columns in the output file:

Column	Description
#	Row number
Date	Snapshot timestamp or calendar date, depending on granularity
Parent ASIN	ASIN of the tracked product
Keyword	Keyword phrase
Amazon Choice	true if the product held the "Amazon's Choice" badge at this snapshot
Organic Position	Organic rank
Organic ASIN	ASIN that held the organic position
Sponsored Position	Sponsored rank
Sponsored ASIN	ASIN that held the sponsored position
Search Volume (7 days)	Weekly search volume closest to the snapshot date
Search Volume (30 days)	Monthly search volume closest to the snapshot date

Workflow

Step 1 — start the export

Call POST /rank-tracker/export:

{
    "groupId": 12,
    "dateFrom": "2026-01-01",
    "dateTo": "2026-04-28",
    "format": "csv",
    "granularity": "daily"
}

The response is returned immediately with status: 0 (pending):

{
    "data": {
        "id": 42,
        "groupId": 12,
        "status": 0,
        "filename": null,
        "format": "csv",
        "granularity": "daily",
        "dateFrom": "2026-01-01",
        "dateTo": "2026-04-28",
        "products": null,
        "createdAt": "2026-04-28T10:00:00.000000Z",
        "updatedAt": null
    }
}

Save the id — you will need it to poll for completion.

Step 2 — poll until ready

Call GET /rank-tracker/export/{id} every few seconds. The status field indicates progress:

Value	Meaning
0	Pending — still processing
1	Completed — filename contains the download URL
2	Failed

Step 3 — download the file

When status is 1, the filename field contains a pre-signed S3 URL valid for 15 minutes. Download the file immediately — the URL expires.

Filtering exported keywords

By default, all products and all keywords in the group are exported. You can narrow the scope:

Specific products — pass an array of ASINs:

{
    "products": [
        "B08N5WRWNW"
    ]
}

Specific keywords — pass an array of keyword IDs (the id field from GET .../phrases/v2):

{
    "keywords": [
        101,
        102,
        103
    ]
}

Active table filters — pass the same filters that are applied in the keywords table. Takes precedence over keywords when provided:

{
    "filters": {
        "search": "bluetooth",
        "tags": [
            1,
            3
        ],
        "boosts": true
    }
}

tags uses AND logic — keywords must have all listed tags.

---

Deleting groups

DELETE /rank-tracker/groups with a groups array of group IDs in the request body.

Review Analyzer

Customer review topics, star rating impact, monthly trends, and category return reasons for an Amazon product. The data comes from Amazon's own analysis of customer reviews over the last 6 months and is updated by Amazon once a week.

Available marketplaces: US, UK, DE, FR, IT, ES, JP. Any ASIN can be analyzed, not only your own. Pass a child ASIN: parent ASINs have no data.

The tool requires a connected Amazon Seller or Vendor account. Without one, every request returns 403 with type: sp_token_required. The connected account does not have to cover the requested marketplace.

Two formats, one quota

Endpoint	Format	Use it for
GET /review-analyzer	Full: every topic with metrics for the ASIN, its parent ASIN and the category, all review snippets, subtopics, monthly trends, category benchmarks and return reasons	Building dashboards and reports
GET /review-analyzer/short	Compact: one line of numbers per topic, one quote, subtopics as strings	LLM agents and quick summaries

Both endpoints count against the same RVA_ANALYSES limit. One use is charged per ASIN and marketplace per hour: repeating the request for the same ASIN within an hour, in either format, is free. Products without review data are not charged. Exhausted limits return 402. If Amazon's review data for the product could not be fetched at all, the response is 503 and no use is charged; retry later.

Reading the numbers

• Percentages (occurrence_pct, pct) are the share of reviews that mention the topic, from 0 to 100.
• star_rating_impact is the estimated effect of the topic on the star rating, from about -2 to 2. It is null for topics outside Amazon's star-impact ranking.
• Trend points are monthly and sorted by end. When the product has no mentions of a topic in a month, all three values of that point are 0.
• Topics may differ between marketplaces and can be in the marketplace language (for example, German topics on DE).
• incomplete: true means some data could not be fetched from Amazon this time; the full format lists the affected sections in unavailable_sections. Repeating the request within an hour is free, so it is safe to retry.
• period shows the review window Amazon used. It is not always the most recent 6 months for products with few reviews.

SQP Analyzer

Export Amazon Search Query Performance (SQP) data for a connected seller account. Compare your ASINs with market totals for impressions, clicks, cart additions, and purchases, alongside matching PPC metrics when available.

The public API currently provides only GET /sqp-analyzer/{sellerId}/export. The endpoint reads reports already imported into SoldScope. Connect the seller account and configure SQP data collection in the application before exporting. The caller needs SQP Analyzer view or manage permission and permission to manage the connected seller account.

Export data

Send your Bearer token, the Amazon seller ID, marketplace, report period type, period end dates, and a grouping level:

curl --get 'https://www.soldscope.com/api/sqp-analyzer/A1EXAMPLESELLER/export' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Accept: application/json' \
  --data-urlencode 'marketplace=US' \
  --data-urlencode 'period_type=months' \
  --data-urlencode 'periods[]=2026-07-31' \
  --data-urlencode 'periods[]=2026-08-31' \
  --data-urlencode 'group=keyword' \
  --data-urlencode 'asins[]=B08N5WRWNW' \
  --data-urlencode 'sort_by=queryVolume' \
  --data-urlencode 'sort_desc=true'

Use months with month-end dates or weeks with week-end dates, in YYYY-MM-DD format. Repeat periods[] to select multiple reports and asins[] to select multiple ASINs. Omit asins[] to include all ASINs with matching data for the seller and marketplace.

group	Row key
period	Report period end date
keyword	Search query text
asin	ASIN

The response is synchronous JSON: data contains all matching rows and meta.total contains their count. Convert the rows to CSV or XLSX in your client. There is no pagination, nested drilldown, export job, or download URL. If no data matches, the response is {"data": [], "meta": {"total": 0}}.

Filters and sorting

Filters use bracket notation in query parameters and apply before grouping:

Parameter	Behavior
filters[searchQueryVolume][min], filters[searchQueryVolume][max]	Inclusive query volume bounds. Values must be nonnegative; zero leaves the bound unset.
filters[wordCount][min], filters[wordCount][max]	Inclusive bounds on whitespace-separated word count, each at least 1.
filters[phrasesContain][value]	Case-insensitive substring, up to 255 characters.
filters[phrasesContain][mode]	1 (default): contains the substring; 2: does not contain it.
filters[excludeKeywords]	Comma-separated substrings to exclude, case-insensitive, up to 1000 characters in total.

For example, add --data-urlencode 'filters[searchQueryVolume][min]=1000' to the request above to keep source queries with volume of at least 1,000.

Set sort_by to a response metric field or key. All row fields except dataPeriods and dataPeriodsCount are sortable. An omitted, unknown, or none sort field falls back to key. Sorting is ascending by default; sort_desc=true or sort_desc=1 selects descending order. Nulls sort last ascending and first descending.

Reading the metrics

• market* counts describe the market for the matching queries. Shared market figures are deduplicated across ASINs for each query and period, then summed. queryVolume follows the same rule.
• my* counts sum the selected ASINs' metrics. queryScore sums the lowest score per query and period and is null when the sum is zero.
• Shares, CTR, and CVR are percentages: 5.25 means 5.25%. CTR is clicks divided by impressions; CVR is purchases divided by clicks. SQP rates are zero when their denominator is zero. ctrDelta and cvrDelta are your rate minus the market rate, in percentage points.
• Median purchase prices are medians of positive reported median prices, expressed in major currency units, and are null when unavailable.
• dataPeriods lists the report end dates contributing to the row; dataPeriodsCount is their count. These may cover fewer periods than requested when reports have no matching data.
• ppc_* fields contain matching advertising totals and derived metrics. All are null when matching PPC data is absent. PPC CTR, ACoS, and CVR are percentages; PPC CVR uses units sold divided by clicks. PPC spend, sales, and CPC use major currency units. Derived PPC metrics are null when their denominator is zero.

The export operation's response schema lists every returned field. Invalid query parameters return 422; an unknown connected seller returns 404; export processing failures return 500 with a message field.