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

Product Research workflow

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

---

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. Each unique search consumes one search credit.
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).

---

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.