{ "openapi": "3.0.0", "info": { "title": "SoldScope API", "description": "The SoldScope API gives you programmatic access to SoldScope tools -\nautomate your workflows, retrieve data, and build integrations on top of\nthe same functionality you use in the app.\n\n---\n\n## Rate Limits & Quotas\n\nThe SoldScope API uses a **monthly quota of API requests** based on your subscription\nplan. Endpoints marked with the **Metered** badge (and prefixed with **\u25c8** in the\nsidebar) count toward this quota; everything else (authentication, listing your\naccount, fetching saved data) is free to call.\n\n### Checking your usage\n\nEvery metered endpoint response includes rate limit headers:\n\n```http\nHTTP\/1.1 200 OK\nX-API-RateLimit-Limit: 1000\nX-API-RateLimit-Remaining: 847\nX-API-RateLimit-Reset: 2026-01-01\n```\n\n- **`X-API-RateLimit-Limit`** - total API requests in your current period\n- **`X-API-RateLimit-Remaining`** - requests left until reset\n- **`X-API-RateLimit-Reset`** - Date of the next reset (YYYY-MM-DD)\n\n### What happens when you hit the limit\n\nOnce your monthly quota is exhausted, metered endpoints respond with\n**`402 Payment Required`**:\n\n```http\nHTTP\/1.1 402 Payment Required\nContent-Type: application\/json\n\n{\n\"message\": \"API requests limit exceeded\"\n}\n```\n\nThis status indicates that the request is valid but cannot be processed\nuntil your quota resets or you upgrade your plan - automatic retries\nwill not succeed. Free endpoints (auth, account info) remain available.\nQuotas reset on the first day of each billing cycle.\n\n### Need more?\n\nIf you regularly hit the limit, consider upgrading your plan - see\npricing<\/a> for details.\n\n---\n\n## Authentication\n\nAll API requests require a **Personal Access Token** passed as a Bearer token\nin the `Authorization` header:\n\n```\nAuthorization: Bearer \n```\n\n**How to get a token:**\n\n1. Open [API Access](https:\/\/app.soldscope.com\/api-access) in your SoldScope account.\n2. Click **Create token**, give it a name, and copy the token \u2014 it is shown only once.\n3. Use that token in every API request.\n\n---\n\n## Quick start\n\nTo verify your token is working, call:\n\n```http\nGET \/auth\/check\nAuthorization: Bearer \n```\n\nA `200` response with your user and account info means you're all set.", "version": "1.0.0" }, "servers": [ { "url": "https:\/\/www.soldscope.com\/api" } ], "paths": { "\/auth\/check": { "get": { "tags": [ "Auth" ], "summary": "Verify API token", "description": "Checks that your token is valid and returns basic information about the authenticated user and account. Use this as a quick sanity check before building any integration.", "operationId": "auth_check", "responses": { "200": { "description": "Token is valid", "content": { "application\/json": { "schema": { "properties": { "user": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" } }, "type": "object" }, "account": { "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "example": "My Store" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "\/keyword-research\/searches\/asin\/single": { "post": { "tags": [ "Keyword Research" ], "summary": "\u25c8 Run a single-ASIN keyword search", "description": "Executes a keyword research search for a single ASIN. The search runs synchronously \u2014 the response already has `status: 2` (completed). Fetch keyword results immediately via `GET \/keyword-research\/searches\/asin\/single\/{id}`.", "operationId": "kr_search_asin", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "marketplace", "asin" ], "properties": { "marketplace": { "$ref": "#\/components\/schemas\/KrAvailableMarketplace" }, "asin": { "$ref": "#\/components\/schemas\/Asin" }, "dateFrom": { "description": "Start of the date range for keyword data (Y-m-d). Defaults to 3 months ago.", "type": "string", "format": "date", "example": "2026-02-01", "nullable": true }, "dateTo": { "description": "End of the date range for keyword data (Y-m-d). Defaults to today.", "type": "string", "format": "date", "example": "2026-05-01", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Search completed", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/KrSearch" } }, "type": "object" } } } }, "400": { "description": "Invalid ASIN", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "402": { "description": "Search limit reached", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "429": { "description": "Limit reached", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "422": { "description": "Validation error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-badges": [ { "name": "Metered", "color": "#1f2937", "position": "before" } ] } }, "\/keyword-research\/searches\/asin\/single\/{search}": { "get": { "tags": [ "Keyword Research" ], "summary": "Get single-ASIN search results", "description": "Returns paginated keyword results for a completed single-ASIN search. Use `fullDataMode=true` to retrieve all keywords at once (requires the Export feature).", "operationId": "kr_get_asin_results", "parameters": [ { "name": "search", "in": "path", "description": "Search ID. Returned as `id` in the response when creating a search (`POST \/keyword-research\/searches\/asin\/single`), or found in the `id` field when listing searches (`GET \/keyword-research\/searches`).", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "example": 50, "maximum": 1000, "minimum": 1 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "example": "searchVolume", "default": "searchVolume", "enum": [ "searchVolume", "keyword", "opportunityScore", "abaSearchFrequencyRank", "abaTotalClickShare", "abaTotalConversionShare", "totalResultCount", "sponsoredProducts", "organicRank", "sponsoredRank", "svTrend", "cpc", "containsBrand" ] } }, { "name": "sortDesc", "in": "query", "required": false, "schema": { "type": "boolean", "example": true } }, { "name": "fullDataMode", "in": "query", "description": "Return all keywords without pagination. Requires Export feature access.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "filters[searchVolume][min]", "in": "query", "description": "Estimated number of customer searches for this keyword over the past 30 days. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[searchVolume][max]", "in": "query", "description": "Estimated number of customer searches for this keyword over the past 30 days. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[opportunityScore][min]", "in": "query", "description": "Calculated from search volume and competing products. Higher scores indicate stronger demand and lower competition. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[opportunityScore][max]", "in": "query", "description": "Calculated from search volume and competing products. Higher scores indicate stronger demand and lower competition. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[organicRank][min]", "in": "query", "description": "Organic search position detected for that keyword for the analyzed product. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[organicRank][max]", "in": "query", "description": "Organic search position detected for that keyword for the analyzed product. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[sponsoredRank][min]", "in": "query", "description": "Sponsored position detected for that keyword for the analyzed product. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[sponsoredRank][max]", "in": "query", "description": "Sponsored position detected for that keyword for the analyzed product. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[sponsoredProducts][min]", "in": "query", "description": "Total number of unique sponsored products for this keyword. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[sponsoredProducts][max]", "in": "query", "description": "Total number of unique sponsored products for this keyword. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[wordCount][min]", "in": "query", "description": "How many words are in the keyword phrase. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[wordCount][max]", "in": "query", "description": "How many words are in the keyword phrase. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[abaRank][min]", "in": "query", "description": "Amazon Brand Analytics Rank for keyword. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[abaRank][max]", "in": "query", "description": "Amazon Brand Analytics Rank for keyword. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[svTrend][min]", "in": "query", "description": "Trend of Search Volume over the past 30 days (%). Min value.", "required": false, "schema": { "type": "number" } }, { "name": "filters[svTrend][max]", "in": "query", "description": "Trend of Search Volume over the past 30 days (%). Max value.", "required": false, "schema": { "type": "number" } }, { "name": "filters[cpc][min]", "in": "query", "description": "Suggested Cost Per Click estimated from recent winning bids for similar ads. Min value.", "required": false, "schema": { "type": "number" } }, { "name": "filters[cpc][max]", "in": "query", "description": "Suggested Cost Per Click estimated from recent winning bids for similar ads. Max value.", "required": false, "schema": { "type": "number" } }, { "name": "filters[productsCount][min]", "in": "query", "description": "Total number of competing products for this keyword (filters on `totalResultCount`). Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[productsCount][max]", "in": "query", "description": "Total number of competing products for this keyword (filters on `totalResultCount`). Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[matchType][]", "in": "query", "description": "Source from which a keyword is drawn. Only return keywords that have ALL of the specified match types. Pass multiple values as repeated query params: `filters[matchType][]=1&filters[matchType][]=2`.", "required": false, "schema": { "type": "array", "items": { "$ref": "#\/components\/schemas\/KrMatchType" } } }, { "name": "filters[amazonChoice][]", "in": "query", "description": "Filter by Amazon's Choice badge status. Pass one or more values as repeated query params: `filters[amazonChoice][]=0`.", "required": false, "schema": { "type": "array", "items": { "$ref": "#\/components\/schemas\/KrAmazonChoice" } } }, { "name": "filters[excludeKeywords]", "in": "query", "description": "Comma-separated list of phrases to exclude. Keywords containing any of these phrases will be removed from results.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "filters[phrasesContain][value]", "in": "query", "description": "Only include (or exclude) keywords that contain this term. Behavior is controlled by `filters[phrasesContain][mode]`.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "filters[phrasesContain][mode]", "in": "query", "required": false, "schema": { "$ref": "#\/components\/schemas\/KrPhrasesContainMode" } }, { "name": "filters[excludeVariations]", "in": "query", "description": "Exclude all product variations (e.g. size\/color) from the results.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Keyword results", "content": { "application\/json": { "schema": { "properties": { "data": { "properties": { "productDetails": { "oneOf": [ { "$ref": "#\/components\/schemas\/KrProductDetails" } ], "nullable": true, "description": "Product details for the searched ASIN. `null` if not available." }, "keywords": { "type": "array", "items": { "$ref": "#\/components\/schemas\/KrKeyword" } }, "keywordDistribution": { "properties": { "totalKeywords": { "type": "integer", "example": 6519 }, "totalOrganic": { "type": "integer", "example": 6441 }, "totalSponsored": { "type": "integer", "example": 302 } }, "type": "object" }, "searchStat": { "properties": { "totalSearchVolume": { "type": "integer", "example": 9562213 }, "avgSearchVolume": { "type": "integer", "example": 1467 }, "wordsCount": { "type": "integer", "example": 987 }, "wordFrequency": { "type": "array", "items": { "properties": { "word": { "type": "string", "example": "dog" }, "count": { "type": "integer", "example": 4149 } }, "type": "object" } } }, "type": "object" }, "topProducts": { "description": "Always an empty array in the public API (reserved for internal use).", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "meta": { "$ref": "#\/components\/schemas\/KrResultMeta" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "402": { "description": "Export feature not available", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "\/keyword-research\/searches\/asin\/multi": { "post": { "tags": [ "Keyword Research" ], "summary": "\u25c8 Run a multi-ASIN keyword search", "description": "Starts an asynchronous keyword research search comparing 2\u201310 ASINs. Returns the search object with `searchStatus=0` (**STARTED**). Poll `GET \/keyword-research\/searches\/{search}\/progress` until `searchStatus=2` (COMPLETED), then fetch results via `GET \/keyword-research\/searches\/multi\/{search}`. Consumes one search credit per ASIN.", "operationId": "kr_search_multi_asin", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "marketplace", "asins" ], "properties": { "marketplace": { "$ref": "#\/components\/schemas\/KrAvailableMarketplace" }, "asins": { "description": "2 to 10 ASINs to compare", "type": "array", "items": { "$ref": "#\/components\/schemas\/Asin" }, "example": [ "B08N5WRWNW", "B07XJ8C8F5" ], "maxItems": 10, "minItems": 2 }, "dateFrom": { "description": "Start of the date range for keyword data (Y-m-d). Defaults to 3 months ago.", "type": "string", "format": "date", "example": "2026-02-01", "nullable": true }, "dateTo": { "description": "End of the date range for keyword data (Y-m-d). Defaults to today.", "type": "string", "format": "date", "example": "2026-05-01", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Search started", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/KrSearch" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "402": { "description": "Search limit reached", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "429": { "description": "Limit reached", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "422": { "description": "Validation error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-badges": [ { "name": "Metered", "color": "#1f2937", "position": "before" } ] } }, "\/keyword-research\/searches": { "get": { "tags": [ "Keyword Research" ], "summary": "List keyword research searches", "description": "Returns a paginated list of **COMPLETED** (`status: 2`) keyword research searches for the authenticated account. Searches with other statuses (**STARTED**, **FAILED**) are not included.", "operationId": "kr_list_searches", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "example": 100, "maximum": 1000, "minimum": 1 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "example": "createdAt", "default": "createdAt", "enum": [ "createdAt", "product", "keyword", "searchType" ] } }, { "name": "sortDesc", "in": "query", "required": false, "schema": { "type": "boolean", "example": true } }, { "name": "filters[titleAsinKeyword]", "in": "query", "required": false, "schema": { "type": "string", "example": "B08N5WRWNW" } } ], "responses": { "200": { "description": "Paginated list of searches", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/KrSearch" } }, "links": { "$ref": "#\/components\/schemas\/PaginationLinks" }, "meta": { "$ref": "#\/components\/schemas\/PaginationMeta" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/keyword-research\/searches\/keyword\/single": { "post": { "tags": [ "Keyword Research" ], "summary": "\u25c8 Run a single-keyword search", "description": "Starts an asynchronous keyword research search by a single keyword phrase. Returns the search object with `status: 0` (STARTED). The response immediately includes `mainAsin` and `asins` (top 10 ASINs for the keyword), while `mainAsinTitle` and `mainAsinImageUrl` remain `null` until processing completes. Poll `GET \/keyword-research\/searches\/{id}\/progress` until `searchStatus: 2` (COMPLETED) or `searchStatus: 13` (FAILED \u2014 no results found for the keyword). On success, fetch results via `GET \/keyword-research\/searches\/multi\/{id}`.", "operationId": "kr_search_keyword", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "marketplace", "keyword" ], "properties": { "marketplace": { "$ref": "#\/components\/schemas\/KrAvailableMarketplace" }, "keyword": { "description": "A single keyword phrase", "type": "string", "example": "wireless earbuds" }, "dateFrom": { "description": "Start of the date range for keyword data (Y-m-d). Defaults to 3 months ago.", "type": "string", "format": "date", "example": "2026-02-01", "nullable": true }, "dateTo": { "description": "End of the date range for keyword data (Y-m-d). Defaults to today.", "type": "string", "format": "date", "example": "2026-05-01", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Search started", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/KrSearch" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "402": { "description": "Search limit reached", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "429": { "description": "Limit reached", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "422": { "description": "Validation error", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ], "x-badges": [ { "name": "Metered", "color": "#1f2937", "position": "before" } ] } }, "\/keyword-research\/searches\/multi\/{search}": { "get": { "tags": [ "Keyword Research" ], "summary": "Get multi-ASIN or keyword search results", "description": "Returns paginated keyword results for a completed multi-ASIN search (`searchType: 1`) or keyword search (`searchType: 2`). Each keyword includes per-ASIN ranking data in `asinsPositions`. Use `fullDataMode=true` to retrieve all keywords at once (requires Export feature access).", "operationId": "kr_get_multi_results", "parameters": [ { "name": "search", "in": "path", "description": "Search ID. Returned as `id` in the response when creating a search (`POST \/keyword-research\/searches\/asin\/multi` or `POST \/keyword-research\/searches\/keyword\/single`), or found in the `id` field when listing searches (`GET \/keyword-research\/searches`).", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "example": 50, "maximum": 1000, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "Can also sort by per-ASIN rank using `{asin}-organic` or `{asin}-sponsored` format, e.g. `B08N5WRWNW-organic`", "required": false, "schema": { "type": "string", "example": "searchVolume", "default": "searchVolume", "enum": [ "searchVolume", "keyword", "organicRankAvg", "sponsoredRankAvg", "opportunityScore", "mainOrganicRank", "mainOrgRelativeRank", "organicAsinsCount", "sponsoredAsinsCount", "totalResultCount", "abaSearchFrequencyRank", "abaTotalClickShare", "abaTotalConversionShare", "svTrend", "cpc", "containsBrand" ] } }, { "name": "sortDesc", "in": "query", "required": false, "schema": { "type": "boolean", "example": true } }, { "name": "fullDataMode", "in": "query", "description": "Return all keywords without pagination. Requires Export feature access.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "filters[searchVolume][min]", "in": "query", "description": "Estimated number of customer searches for this keyword over the past 30 days. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[searchVolume][max]", "in": "query", "description": "Estimated number of customer searches for this keyword over the past 30 days. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[opportunityScore][min]", "in": "query", "description": "Calculated from search volume and competing products. Higher scores indicate stronger demand and lower competition. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[opportunityScore][max]", "in": "query", "description": "Calculated from search volume and competing products. Higher scores indicate stronger demand and lower competition. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[mainOrganicRank][min]", "in": "query", "description": "Position the first ASIN (in a multi-ASIN search) holds in Amazon's organic results. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[mainOrganicRank][max]", "in": "query", "description": "Position the first ASIN (in a multi-ASIN search) holds in Amazon's organic results. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[organicRankAvg][min]", "in": "query", "description": "Average position of ASINs in organic search results. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[organicRankAvg][max]", "in": "query", "description": "Average position of ASINs in organic search results. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[sponsoredRankAvg][min]", "in": "query", "description": "Average position of ASINs in sponsored (ad) listings. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[sponsoredRankAvg][max]", "in": "query", "description": "Average position of ASINs in sponsored (ad) listings. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[organicAsinsCount][min]", "in": "query", "description": "Number of ASINs that appear in organic results for this keyword. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[organicAsinsCount][max]", "in": "query", "description": "Number of ASINs that appear in organic results for this keyword. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[sponsoredAsinsCount][min]", "in": "query", "description": "Number of ASINs that appear in sponsored results for this keyword. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[sponsoredAsinsCount][max]", "in": "query", "description": "Number of ASINs that appear in sponsored results for this keyword. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[wordCount][min]", "in": "query", "description": "How many words are in the keyword phrase. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[wordCount][max]", "in": "query", "description": "How many words are in the keyword phrase. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[abaRank][min]", "in": "query", "description": "Amazon Brand Analytics Rank for keyword. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[abaRank][max]", "in": "query", "description": "Amazon Brand Analytics Rank for keyword. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[svTrend][min]", "in": "query", "description": "Trend of Search Volume over the past 30 days (%). Min value.", "required": false, "schema": { "type": "number" } }, { "name": "filters[svTrend][max]", "in": "query", "description": "Trend of Search Volume over the past 30 days (%). Max value.", "required": false, "schema": { "type": "number" } }, { "name": "filters[cpc][min]", "in": "query", "description": "Suggested Cost Per Click estimated from recent winning bids for similar ads. Min value.", "required": false, "schema": { "type": "number" } }, { "name": "filters[cpc][max]", "in": "query", "description": "Suggested Cost Per Click estimated from recent winning bids for similar ads. Max value.", "required": false, "schema": { "type": "number" } }, { "name": "filters[mainOrgRelativeRank][min]", "in": "query", "description": "Rank of the main ASIN relative to its competitors. For example, if two competitors rank better than the main ASIN, its relative rank is 3. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[mainOrgRelativeRank][max]", "in": "query", "description": "Rank of the main ASIN relative to its competitors. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[sponsoredProducts][min]", "in": "query", "description": "Total number of unique sponsored products for this keyword. Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[sponsoredProducts][max]", "in": "query", "description": "Total number of unique sponsored products for this keyword. Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[productsCount][min]", "in": "query", "description": "Total number of competing products for this keyword (filters on `totalResultCount`). Min value.", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[productsCount][max]", "in": "query", "description": "Total number of competing products for this keyword (filters on `totalResultCount`). Max value.", "required": false, "schema": { "type": "integer" } }, { "name": "filters[matchType][]", "in": "query", "description": "Source from which a keyword is drawn. Only return keywords that have ALL of the specified match types. Pass multiple values as repeated query params: `filters[matchType][]=1&filters[matchType][]=2`.", "required": false, "schema": { "type": "array", "items": { "$ref": "#\/components\/schemas\/KrMatchType" } } }, { "name": "filters[amazonChoice][]", "in": "query", "description": "Filter by Amazon's Choice badge status. Pass one or more values as repeated query params: `filters[amazonChoice][]=0`.", "required": false, "schema": { "type": "array", "items": { "$ref": "#\/components\/schemas\/KrAmazonChoice" } } }, { "name": "filters[excludeKeywords]", "in": "query", "description": "Comma-separated list of phrases to exclude. Keywords containing any of these phrases will be removed from results.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "filters[phrasesContain][value]", "in": "query", "description": "Only include (or exclude) keywords that contain this term. Behavior is controlled by `filters[phrasesContain][mode]`.", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "filters[phrasesContain][mode]", "in": "query", "required": false, "schema": { "$ref": "#\/components\/schemas\/KrPhrasesContainMode" } }, { "name": "filters[excludeVariations]", "in": "query", "description": "Exclude all product variations (e.g. size\/color) from the results.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Keyword results", "content": { "application\/json": { "schema": { "properties": { "data": { "properties": { "productDetails": { "description": "Brief product info for each compared ASIN, in the order they were submitted.", "type": "array", "items": { "properties": { "asin": { "$ref": "#\/components\/schemas\/Asin" }, "parentAsin": { "type": "string", "example": "B07XJ8C8F5", "nullable": true }, "brand": { "type": "string", "example": "Benebone", "nullable": true }, "marketplace": { "$ref": "#\/components\/schemas\/KrAvailableMarketplace" }, "title": { "type": "string", "example": "Dog Toy for Aggressive Chewers" }, "coverImage": { "type": "string", "format": "uri", "nullable": true }, "productType": { "type": "string", "example": "PET_SUPPLIES", "nullable": true } }, "type": "object" } }, "keywords": { "type": "array", "items": { "$ref": "#\/components\/schemas\/KrMultiKeyword" } }, "productsSummary": { "description": "Per-ASIN summary stats keyed by ASIN string, plus a `\"median\"` key with aggregate counts across all compared ASINs.", "properties": { "median": { "description": "Aggregate counts across all compared ASINs. Each numeric field contains the number of ASINs that have a value for that field.", "properties": { "brand": { "description": "Number of ASINs with a brand value.", "type": "integer", "example": 3 }, "asin": { "description": "Number of ASINs in the comparison.", "type": "integer", "example": 3 }, "category": { "description": "Category distribution across compared ASINs.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Pet Supplies" }, "count": { "type": "integer", "example": 3 } }, "type": "object" } } }, "type": "object" } }, "type": "object", "additionalProperties": { "$ref": "#\/components\/schemas\/KrProductSummary" } }, "keywordDistribution": { "properties": { "totalKeywords": { "type": "integer", "example": 11208 }, "totalOrganic": { "type": "integer", "example": 4779 }, "totalSponsored": { "type": "integer", "example": 9449 } }, "type": "object" }, "searchStat": { "properties": { "totalSearchVolume": { "type": "integer", "example": 11226361 }, "avgSearchVolume": { "type": "integer", "example": 1002 }, "wordsCount": { "type": "integer", "example": 2702 }, "wordFrequency": { "type": "array", "items": { "properties": { "word": { "type": "string", "example": "dog" }, "count": { "type": "integer", "example": 6715 } }, "type": "object" } } }, "type": "object" }, "topProducts": { "description": "Always an empty array in the public API (reserved for internal use).", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "meta": { "$ref": "#\/components\/schemas\/KrResultMeta" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "402": { "description": "Export feature not available", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "\/keyword-research\/searches\/multi\/{search}\/word-frequency": { "get": { "tags": [ "Keyword Research" ], "summary": "Get word frequency for a multi-ASIN search", "description": "Returns word frequency data for the keywords in a multi-ASIN search, optionally filtered. Accepts the same `filters` parameters as the multi results endpoint.", "operationId": "5282cb74b9d8d6b5b30394df355dd9a9", "parameters": [ { "name": "search", "in": "path", "description": "Search ID. Returned as `id` in the response when creating a search, or found in the `id` field when listing searches (`GET \/keyword-research\/searches`).", "required": true, "schema": { "type": "integer" } }, { "name": "filters[searchVolume][min]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[searchVolume][max]", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "filters[excludeKeywords]", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "filters[phrasesContain][value]", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "filters[phrasesContain][mode]", "in": "query", "required": false, "schema": { "$ref": "#\/components\/schemas\/KrPhrasesContainMode" } }, { "name": "filters[excludeVariations]", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Word frequency list", "content": { "application\/json": { "schema": { "properties": { "data": { "description": "Array of word frequency entries, sorted by count descending.", "type": "array", "items": { "properties": { "count": { "description": "Number of keywords containing this word.", "type": "integer", "example": 16097 }, "word": { "type": "string", "example": "dog" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "\/keyword-research\/searches\/{search}\/progress": { "get": { "tags": [ "Keyword Research" ], "summary": "Get search progress", "description": "Returns the current processing progress for an asynchronous search (multi-ASIN or keyword). Poll this endpoint until `searchStatus=2` (completed) or `searchStatus=13` (failed).", "operationId": "kr_get_search_progress", "parameters": [ { "name": "search", "in": "path", "description": "Search ID. Returned as `id` in the response when creating a search, or found in the `id` field when listing searches (`GET \/keyword-research\/searches`).", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Progress data", "content": { "application\/json": { "schema": { "properties": { "data": { "properties": { "progress": { "description": "Completion percentage", "type": "integer", "example": 65, "maximum": 100, "minimum": 0 }, "searchStatus": { "$ref": "#\/components\/schemas\/KrSearchStatus" } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "\/keyword-research\/searches\/{search}": { "get": { "tags": [ "Keyword Research" ], "summary": "Get a search", "description": "Returns metadata for a single keyword research search.", "operationId": "kr_get_search", "parameters": [ { "name": "search", "in": "path", "description": "Search ID. Returned as `id` in the response when creating a search, or found in the `id` field when listing searches (`GET \/keyword-research\/searches`).", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Search object", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/KrSearch" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "\/keyword-research\/searches\/asin\/single\/{search}\/word-frequency": { "get": { "tags": [ "Keyword Research" ], "summary": "Get word frequency for a single-ASIN search", "description": "Returns word frequency data for the keywords in a single-ASIN search, optionally filtered. Accepts the same `filters` parameters as the results endpoint.", "operationId": "0736ddb4c86cb8c277d048881bc94014", "parameters": [ { "name": "search", "in": "path", "description": "Search ID. Returned as `id` in the response when creating a search, or found in the `id` field when listing searches (`GET \/keyword-research\/searches`).", "required": true, "schema": { "type": "integer" } }, { "name": "filters[searchVolume][min]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "filters[searchVolume][max]", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "filters[excludeKeywords]", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "filters[phrasesContain][value]", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 255 } }, { "name": "filters[phrasesContain][mode]", "in": "query", "required": false, "schema": { "$ref": "#\/components\/schemas\/KrPhrasesContainMode" } }, { "name": "filters[excludeVariations]", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Word frequency list", "content": { "application\/json": { "schema": { "properties": { "data": { "description": "Array of word frequency entries, sorted by count descending.", "type": "array", "items": { "properties": { "count": { "description": "Number of keywords containing this word.", "type": "integer", "example": 2346 }, "word": { "type": "string", "example": "dog" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Not found", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "\/product-research\/categories": { "get": { "tags": [ "Product Research" ], "summary": "List categories", "description": "Returns a flat list of Amazon categories for the given marketplace. \n\n**Two main use cases:**\n- Pass `level=2` to get all top-level (root) categories \u2014 useful for browsing.\n- Pass `nodeIds[]` to fetch specific categories by their `nodeId` \u2014 useful for resolving saved filter sets.\n\nUse the `nodeId` field of each returned category as the value for `filters[categories][]` in `GET \/product-research\/products`.", "operationId": "d7bb89798075fa65b1255ecf212b59d2", "parameters": [ { "name": "marketplace", "in": "query", "required": true, "schema": { "$ref": "#\/components\/schemas\/PrMarketplace" } }, { "name": "level", "in": "query", "description": "Filter by category depth level. Use `level=2` to retrieve root-level categories.", "required": false, "schema": { "type": "integer", "example": 2, "maximum": 20, "minimum": 2 } }, { "name": "nodeIds[]", "in": "query", "description": "Fetch specific categories by their Amazon `nodeId` values.", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "7141124011", "1055398" ] } } ], "responses": { "200": { "description": "Flat list of categories", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PrCategory" } } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/product-research\/categories-tree": { "get": { "tags": [ "Product Research" ], "summary": "Search categories (tree)", "description": "Searches Amazon categories by keyword and returns matching results as a nested tree. Use this endpoint to let users pick categories interactively. Collect the `nodeId` values of the selected nodes and pass them as `filters[categories][]` to `GET \/product-research\/products`.", "operationId": "pr_get_categories_tree", "parameters": [ { "name": "marketplace", "in": "query", "required": true, "schema": { "$ref": "#\/components\/schemas\/PrMarketplace" } }, { "name": "searchQuery", "in": "query", "description": "Keyword to search for \u2014 minimum 3 characters. Matches category names and their ancestors.", "required": true, "schema": { "type": "string", "example": "Electronics", "minLength": 3 } } ], "responses": { "200": { "description": "Nested category tree matching the search query", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PrCategoryTreeNode" } } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/product-research\/categories\/{id}\/children": { "get": { "tags": [ "Product Research" ], "summary": "Get category children", "description": "Returns the direct subcategories of a given category. \n\n> **Important:** `{id}` is the internal **database `id`** field from `PrCategory`, not the `nodeId`. Use the `id` returned by `GET \/product-research\/categories` or `GET \/product-research\/categories-tree`.", "operationId": "3e76cefaad17426c59a9e86d1a62cfbd", "parameters": [ { "name": "id", "in": "path", "description": "Internal database `id` of the parent category (from `PrCategory.id`).", "required": true, "schema": { "type": "integer", "example": 4851 } } ], "responses": { "200": { "description": "Direct subcategories of the given category", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PrCategory" } } }, "type": "object" } } } }, "404": { "description": "Category not found", "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/Error" } ] }, "example": { "message": "Not Found" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/product-research\/searches": { "get": { "tags": [ "Product Research" ], "summary": "List past searches", "description": "Returns a paginated list of past Product Research searches for the authenticated account. The `id` of each search can be passed as `searchId` to `GET \/product-research\/products` to replay it without consuming a search credit.", "operationId": "9df3038c1f3413d0fd2eb0b77afb032b", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "example": 50, "maximum": 1000, "minimum": 1 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "example": "createdAt", "default": "createdAt", "enum": [ "createdAt", "resultsNumber" ] } }, { "name": "sortDesc", "in": "query", "required": false, "schema": { "type": "boolean", "example": true } } ], "responses": { "200": { "description": "Paginated list of past searches", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PrSearch" } }, "links": { "$ref": "#\/components\/schemas\/PaginationLinks" }, "meta": { "$ref": "#\/components\/schemas\/PaginationMeta" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/product-research\/products\/{id}\/media": { "get": { "tags": [ "Product Research" ], "summary": "Get product images or videos", "description": "Lazily fetches media for a specific product \u2014 either all listing images or all videos. The main search response only contains counts (`imagesCount`, `sellerVideosCount`, etc.); use this endpoint to retrieve the actual filenames\/data when needed. Image values are filenames (same format as `PrProduct.image`), not full URLs.", "operationId": "32273f21d166658d5a82887bc1b40dc5", "parameters": [ { "name": "id", "in": "path", "description": "Internal product `id` from `PrProduct.id`.", "required": true, "schema": { "type": "integer", "example": 104728391 } }, { "name": "type", "in": "query", "description": "`images` \u2014 returns all listing image URLs. `video` \u2014 returns seller, influencer, and customer videos.", "required": true, "schema": { "type": "string", "example": "images", "enum": [ "images", "video" ] } } ], "responses": { "200": { "description": "Media data for the requested type", "content": { "application\/json": { "schema": { "properties": { "data": { "oneOf": [ { "title": "Images response", "properties": { "images": { "description": "Ordered list of listing image filenames (same format as `PrProduct.image`).", "type": "array", "items": { "type": "string" }, "example": [ "31Wsz5aOw6L._AC_.jpg", "41d4evtpcBL._AC_.jpg", "41OfS7130hL._AC_.jpg" ] } }, "type": "object" }, { "title": "Video response", "properties": { "video": { "properties": { "seller_videos": { "description": "Videos uploaded by the seller.", "type": "array", "items": { "$ref": "#\/components\/schemas\/PrVideo" } }, "influencers_videos": { "description": "Videos created by influencers.", "type": "array", "items": { "$ref": "#\/components\/schemas\/PrVideo" } }, "customer_videos": { "description": "Videos uploaded by customers.", "type": "array", "items": { "$ref": "#\/components\/schemas\/PrVideo" } } }, "type": "object" } }, "type": "object" } ] } }, "type": "object" } } } }, "404": { "description": "Product not found", "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/Error" } ] }, "example": { "message": "Not Found" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/product-research\/products": { "get": { "tags": [ "Product Research" ], "summary": "\u25c8 Search products", "description": "Searches for Amazon products using the given filters and returns a paginated list. Each unique combination of filters consumes one search credit. To re-paginate or re-sort the same search without spending another credit, pass the `searchId` returned in `meta.searchId`. Use `fullDataMode=true` to retrieve all products at once (requires the Export feature).", "operationId": "pr_search_products", "parameters": [ { "name": "marketplace", "in": "query", "required": true, "schema": { "$ref": "#\/components\/schemas\/PrMarketplace" } }, { "name": "searchId", "in": "query", "description": "ID of a previous search. When provided, filters are loaded from that saved search and no search credit is charged.", "required": false, "schema": { "type": "integer", "example": 1042 } }, { "name": "fullDataMode", "in": "query", "description": "Return all products without pagination. Requires Export feature access.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "page", "in": "query", "description": "Page number (1-based). Required when `fullDataMode` is `false` or omitted; ignored when `fullDataMode` is `true`.", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Number of results per page (max 100). Required when `fullDataMode` is `false` or omitted; ignored when `fullDataMode` is `true`.", "required": false, "schema": { "type": "integer", "example": 50, "maximum": 100, "minimum": 1 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "example": "bsr", "default": "bsr", "enum": [ "bsr", "sales", "revenue", "price", "rating", "ratingsCount", "bbSeller", "sellerCountry", "brand", "weight", "manufacturer", "imagesCount", "parentAsin", "variationsCount", "lqs", "yearlySales", "bestSalesPeriod", "listingAge", "netPrice", "netRevenue", "hasAPlusContent" ] } }, { "name": "sortDesc", "in": "query", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "filters[title]", "in": "query", "description": "Include products that contain specific terms in their title to narrow down your niche. Comma separated.", "required": false, "schema": { "type": "string", "example": "wireless earbuds" } }, { "name": "filters[excludeTitle]", "in": "query", "description": "Hide products containing specific words (e.g. \"plastic\", \"kit\", \"replacement\") from your results. Comma separated.", "required": false, "schema": { "type": "string", "example": "refurbished" } }, { "name": "filters[brand]", "in": "query", "description": "Show results only from specific brands you want to analyze. Comma separated. If your brand name has a comma in it, wrap it in quotes: \"EFG's Inc.\"", "required": false, "schema": { "type": "string", "example": "Sony" } }, { "name": "filters[excludeBrands]", "in": "query", "description": "Remove dominant brands or direct competitors to see more diverse opportunities. Comma separated. If your brand name has a comma in it, wrap it in quotes: \"EFG's Inc.\"", "required": false, "schema": { "type": "string", "example": "Amazon,Apple" } }, { "name": "filters[seller]", "in": "query", "description": "Analyze the inventory and performance of a specific competitor by their Seller Name. Comma separated. If a seller name has a comma in it, wrap it in quotes: \"EFG's Inc.\"", "required": false, "schema": { "type": "string", "example": "Amazon.com" } }, { "name": "filters[excludeSellers]", "in": "query", "description": "Exclude sellers by name, separated by commas. If a seller name has a comma in it, wrap it in quotes: \"EFG's Inc.\"", "required": false, "schema": { "type": "string", "example": "SomeStore,AnotherStore" } }, { "name": "filters[countries][]", "in": "query", "description": "Filter products based on the seller's registered business location. Two-letter country codes.", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "US", "GB" ] } }, { "name": "filters[excludeCountries][]", "in": "query", "description": "Remove sellers from specific regions (e.g. China) to focus on local or international competition. Two-letter country codes.", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "CN" ] } }, { "name": "filters[upcGtin][]", "in": "query", "description": "Directly search for specific products using UPC\/GTIN\/EAN\/ISBN\/ASIN. Up to 500 identifiers.", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "840268902000" ] } }, { "name": "filters[categories][]", "in": "query", "description": "Filter your search by specific Amazon categories or sub-categories. Use `GET \/product-research\/categories` to obtain category node IDs.", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "7141124011" ] } }, { "name": "filters[bsr][min]", "in": "query", "description": "Minimum Best Sellers Rank. The product's ranking within its primary category \u2014 lower rank means higher sales volume.", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "filters[bsr][max]", "in": "query", "description": "Maximum Best Sellers Rank.", "required": false, "schema": { "type": "integer", "example": 10000, "minimum": 1 } }, { "name": "filters[price][min]", "in": "query", "description": "Minimum Buy Box price in the marketplace currency.", "required": false, "schema": { "type": "number", "format": "float", "example": 10, "minimum": 0.01 } }, { "name": "filters[price][max]", "in": "query", "description": "Maximum Buy Box price in the marketplace currency.", "required": false, "schema": { "type": "number", "format": "float", "example": 100, "minimum": 0.01 } }, { "name": "filters[priceChange][min]", "in": "query", "description": "Minimum price change over the past 90 days (%). Helps identify price wars or stability. Range: -100 to 100.", "required": false, "schema": { "type": "integer", "example": -20, "maximum": 100, "minimum": -100 } }, { "name": "filters[priceChange][max]", "in": "query", "description": "Maximum price change over the past 90 days (%). Range: -100 to 100.", "required": false, "schema": { "type": "integer", "example": 20, "maximum": 100, "minimum": -100 } }, { "name": "filters[sales][min]", "in": "query", "description": "Minimum estimated monthly sales (last 30 days). For products with variations this represents combined total sales across all variations under the Parent ASIN.", "required": false, "schema": { "type": "integer", "example": 100, "minimum": 1 } }, { "name": "filters[sales][max]", "in": "query", "description": "Maximum estimated monthly sales (last 30 days).", "required": false, "schema": { "type": "integer", "example": 5000, "minimum": 1 } }, { "name": "filters[salesChange][min]", "in": "query", "description": "Minimum sales change over the past 90 days (%). High positive values can signal a trending product.", "required": false, "schema": { "type": "integer", "example": -50 } }, { "name": "filters[salesChange][max]", "in": "query", "description": "Maximum sales change over the past 90 days (%).", "required": false, "schema": { "type": "integer", "example": 200 } }, { "name": "filters[revenue][min]", "in": "query", "description": "Minimum projected monthly gross revenue (last 30 days, before taxes and fees) in the marketplace currency. Helps identify high-income opportunities.", "required": false, "schema": { "type": "number", "format": "float", "example": 1000, "minimum": 1 } }, { "name": "filters[revenue][max]", "in": "query", "description": "Maximum projected monthly gross revenue in the marketplace currency.", "required": false, "schema": { "type": "number", "format": "float", "example": 100000, "minimum": 1 } }, { "name": "filters[yearlySales][min]", "in": "query", "description": "Minimum estimated yearly sales (last 365 days). For products with variations this represents combined total sales across all variations under the Parent ASIN.", "required": false, "schema": { "type": "integer", "example": 1000, "minimum": 1 } }, { "name": "filters[yearlySales][max]", "in": "query", "description": "Maximum estimated yearly sales (last 365 days).", "required": false, "schema": { "type": "integer", "example": 60000, "minimum": 1 } }, { "name": "filters[netPrice][min]", "in": "query", "description": "Minimum estimated net price after deducting Amazon Referral and FBA fees. Helps in calculating your potential margins.", "required": false, "schema": { "type": "number", "format": "float", "example": 5 } }, { "name": "filters[netPrice][max]", "in": "query", "description": "Maximum estimated net price after deducting Amazon Referral and FBA fees.", "required": false, "schema": { "type": "number", "format": "float", "example": 80 } }, { "name": "filters[netRevenue][min]", "in": "query", "description": "Minimum total projected net revenue over the past 30 days after Amazon's core fees are subtracted.", "required": false, "schema": { "type": "number", "format": "float", "example": 500 } }, { "name": "filters[netRevenue][max]", "in": "query", "description": "Maximum total projected net revenue over the past 30 days after Amazon's core fees are subtracted.", "required": false, "schema": { "type": "number", "format": "float", "example": 50000 } }, { "name": "filters[fulfillment][]", "in": "query", "description": "Filter by how the product is shipped: FBA (Amazon), FBM (Merchant), or Sold by Amazon. See `PrFulfillmentType` schema for values.", "required": false, "schema": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PrFulfillmentType" }, "example": [ 2 ] } }, { "name": "filters[weight][min]", "in": "query", "description": "Minimum shipping weight in pounds. Heavier items often result in higher FBA fees and shipping costs.", "required": false, "schema": { "type": "number", "format": "float", "example": 0.5, "minimum": 0 } }, { "name": "filters[weight][max]", "in": "query", "description": "Maximum shipping weight in pounds.", "required": false, "schema": { "type": "number", "format": "float", "example": 5, "minimum": 0 } }, { "name": "filters[sizeTier][]", "in": "query", "description": "Amazon's FBA size classification (e.g. Standard, Oversize). This determines storage and fulfillment costs. Integer codes match the `sizeTier` integer values used internally.", "required": false, "schema": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2 ] } }, { "name": "filters[variationsCount][min]", "in": "query", "description": "Minimum number of child products (colors, sizes) under one parent listing.", "required": false, "schema": { "type": "integer", "example": 2, "minimum": 1 } }, { "name": "filters[variationsCount][max]", "in": "query", "description": "Maximum number of child products (colors, sizes) under one parent listing.", "required": false, "schema": { "type": "integer", "example": 20, "minimum": 1 } }, { "name": "filters[listingAge][min]", "in": "query", "description": "Minimum listing age in months \u2014 how long the product has been live on Amazon.", "required": false, "schema": { "type": "number", "format": "float", "example": 6, "minimum": 1 } }, { "name": "filters[listingAge][max]", "in": "query", "description": "Maximum listing age in months.", "required": false, "schema": { "type": "number", "format": "float", "example": 60, "minimum": 1 } }, { "name": "filters[reviewCount][min]", "in": "query", "description": "Minimum total number of customer ratings. Helps gauge how established the competition is.", "required": false, "schema": { "type": "integer", "example": 50, "minimum": 1 } }, { "name": "filters[reviewCount][max]", "in": "query", "description": "Maximum total number of customer ratings.", "required": false, "schema": { "type": "integer", "example": 10000, "minimum": 1 } }, { "name": "filters[reviewRating][min]", "in": "query", "description": "Minimum average customer star rating (1\u20135).", "required": false, "schema": { "type": "number", "format": "float", "example": 4, "maximum": 5, "minimum": 1 } }, { "name": "filters[reviewRating][max]", "in": "query", "description": "Maximum average customer star rating (1\u20135).", "required": false, "schema": { "type": "number", "format": "float", "example": 5, "maximum": 5, "minimum": 1 } }, { "name": "filters[numberOfImages][min]", "in": "query", "description": "Minimum number of images in the listing. Fewer than 7 images often suggests an unoptimized listing.", "required": false, "schema": { "type": "integer", "example": 4, "minimum": 1 } }, { "name": "filters[numberOfImages][max]", "in": "query", "description": "Maximum number of images in the listing.", "required": false, "schema": { "type": "integer", "example": 9, "minimum": 1 } }, { "name": "filters[videosCount][min]", "in": "query", "description": "Minimum total video count on the product page, including seller, influencer, and customer videos.", "required": false, "schema": { "type": "number", "format": "float", "example": 1, "minimum": 0 } }, { "name": "filters[videosCount][max]", "in": "query", "description": "Maximum total video count on the product page.", "required": false, "schema": { "type": "number", "format": "float", "example": 20, "minimum": 0 } }, { "name": "filters[lqs][min]", "in": "query", "description": "Minimum Listing Quality Score (0\u2013100). Evaluates how well the listing is optimized for SEO and conversions.", "required": false, "schema": { "type": "number", "format": "float", "example": 70, "maximum": 100, "minimum": 0 } }, { "name": "filters[lqs][max]", "in": "query", "description": "Maximum Listing Quality Score (0\u2013100).", "required": false, "schema": { "type": "number", "format": "float", "example": 100, "maximum": 100, "minimum": 0 } }, { "name": "filters[hasAPlusContent]", "in": "query", "description": "Filter for products that use A+ Content in their descriptions. `true` \u2014 only with A+ Content, `false` \u2014 only without.", "required": false, "schema": { "type": "boolean", "example": true } }, { "name": "filters[returnRate]", "in": "query", "description": "Filter by Amazon return frequency badge: 1 \u2014 fewer returns (\"keep this item\"), 2 \u2014 frequently returned.", "required": false, "schema": { "type": "integer", "example": 1, "maximum": 2, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated product list", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PrProduct" } }, "meta": { "properties": { "searchId": { "description": "ID of the saved search. Pass back as `searchId` to re-paginate without consuming another search credit.", "type": "integer", "example": 1042, "nullable": true }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "description": "Total number of matching products.", "type": "integer", "example": 1847 } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ], "x-badges": [ { "name": "Metered", "color": "#1f2937", "position": "before" } ] } }, "\/product-research\/products\/{id}\/variations": { "get": { "tags": [ "Product Research" ], "summary": "Get product variations", "description": "Returns all variations for a product from a previously executed search. \n\n> **Note:** Variations are served from an in-memory cache that lives for **1 hour** after the original search. If the cache has expired, the endpoint returns `404`. Re-run the search via `GET \/product-research\/products?searchId={id}` to refresh the cache.", "operationId": "pr_get_variations", "parameters": [ { "name": "id", "in": "path", "description": "Internal product ID returned in `PrProduct.id`.", "required": true, "schema": { "type": "integer", "example": 104728391 } }, { "name": "searchId", "in": "query", "description": "ID of the search that produced this product (from `meta.searchId`).", "required": true, "schema": { "type": "integer", "example": 1042 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "example": "bsr", "default": "bsr", "enum": [ "bsr", "sales", "revenue", "price", "rating", "ratingsCount", "bbSeller", "sellerCountry", "brand", "weight", "manufacturer", "imagesCount", "parentAsin", "variationsCount", "lqs", "yearlySales", "bestSalesPeriod", "listingAge", "netPrice", "netRevenue", "hasAPlusContent" ] } }, { "name": "sortDesc", "in": "query", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "List of product variations", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PrProduct" } } }, "type": "object" } } } }, "404": { "description": "Search cache expired or product not found. Re-run the original search to refresh.", "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/Error" } ] }, "example": { "message": "Search not found" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/export\/{id}": { "get": { "tags": [ "Rank Tracker" ], "summary": "Get export status", "description": "Returns the current status of an export request. Poll this endpoint every few seconds after calling `POST \/rank-tracker\/export`. When `status` is `1` (completed), `filename` contains a pre-signed S3 download URL valid for **15 minutes** \u2014 download the file immediately. When `status` is `2`, the export failed.", "operationId": "rt_get_export", "parameters": [ { "name": "id", "in": "path", "description": "Export ID returned by `POST \/rank-tracker\/export`.", "required": true, "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Export status", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/RtExport" } }, "type": "object" } } } }, "404": { "description": "Export not found" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/export": { "post": { "tags": [ "Rank Tracker" ], "summary": "Start async export", "description": "Starts an asynchronous export of historical keyword position data for a Rank Tracker group. The response is returned immediately with `status: 0` (pending) or null. Poll `GET \/rank-tracker\/export\/{id}` every few seconds until `status` becomes `1` (completed) or `2` (failed). When completed, `filename` contains a pre-signed S3 download URL valid for 15 minutes \u2014 download the file immediately. \n\nThe `granularity` field controls the row density of the exported file: `raw` (default) \u2014 one row per keyword per tracking snapshot, `Date` is `YYYY-MM-DD HH:MM`; `daily` \u2014 one row per keyword per calendar day, positions are aggregated by median, `Date` is `YYYY-MM-DD`. Columns: `#`, `Date`, `Parent ASIN`, `Keyword`, `Amazon Choice`, `Organic Position`, `Organic ASIN`, `Sponsored Position`, `Sponsored ASIN`, `Search Volume (7 days)`, `Search Volume (30 days)`.", "operationId": "rt_init_export", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "groupId", "dateFrom", "dateTo", "format" ], "properties": { "groupId": { "description": "ID of the group to export. Returned by `GET \/rank-tracker\/groups`.", "type": "integer", "example": 12 }, "dateFrom": { "description": "Start of the date range (inclusive). Must be \u2264 `dateTo`.", "type": "string", "format": "date", "example": "2026-01-01" }, "dateTo": { "description": "End of the date range (inclusive). Must be \u2265 `dateFrom`.", "type": "string", "format": "date", "example": "2026-04-28" }, "format": { "description": "Output file format.", "type": "string", "example": "csv", "enum": [ "csv", "json" ] }, "products": { "description": "ASINs to include. Omit or pass an empty array to export all products in the group.", "type": "array", "items": { "type": "string", "example": "B08N5WRWNW" }, "nullable": true }, "keywords": { "description": "Explicit list of keyword IDs to export (the `id` field from `GET ...\/phrases`). Ignored when `filters` is provided. Omit to export all keywords.", "type": "array", "items": { "type": "integer" }, "nullable": true }, "granularity": { "description": "Row density of the exported file. `raw` (default) \u2014 one row per tracking snapshot, `Date` column contains timestamp `YYYY-MM-DD HH:MM`. `daily` \u2014 one row per keyword per calendar day, positions are aggregated by median, `Date` column contains only the date `YYYY-MM-DD`.", "type": "string", "nullable": true, "default": "raw", "enum": [ "raw", "daily" ] }, "filters": { "description": "Apply the same filters that are active in the keywords table. When provided, takes precedence over `keywords`. Omit to export all keywords.", "properties": { "search": { "description": "Filter keywords by phrase text (case-insensitive partial match).", "type": "string", "example": "bluetooth", "nullable": true }, "tags": { "description": "Filter by tag IDs. Keywords must have ALL listed tags.", "type": "array", "items": { "type": "integer" }, "nullable": true }, "boosts": { "description": "When `true`, export only boosted keywords.", "type": "boolean", "example": false, "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Export started", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/RtExport" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/attach-tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Attach tags to groups", "description": "Attaches tags to multiple groups. Each tag ID is attached to each provided group ID.", "operationId": "rt_attach_group_tags_batch", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagIds", "groupIds" ], "properties": { "tagIds": { "description": "Tag IDs to attach. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 1, 3 ], "maxItems": 10, "minItems": 1 }, "groupIds": { "description": "Group IDs that should receive the provided tags. Use the `id` field from `GET \/rank-tracker\/groups`.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 12, 13 ], "maxItems": 5000, "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags attached" }, "422": { "description": "Validation error - `tagIds` or `groupIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups": { "get": { "tags": [ "Rank Tracker" ], "summary": "List groups", "description": "Returns a paginated list of Rank Tracker groups for the selected account. Each group contains the primary product info and aggregated keyword ranking statistics.", "operationId": "rt_list_groups", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination, starting from 1.", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Number of results per page.", "required": false, "schema": { "type": "integer", "example": 15, "minimum": 1 } }, { "name": "marketplace", "in": "query", "description": "Filter by marketplace.", "required": false, "schema": { "$ref": "#\/components\/schemas\/RtMarketplace" } }, { "name": "search", "in": "query", "description": "Search by ASIN or product title (case-insensitive).", "required": false, "schema": { "type": "string", "example": "B08N5WRWNW" } }, { "name": "tags[]", "in": "query", "description": "Filter by tag IDs. Groups must have ALL listed tags.", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "sort", "in": "query", "description": "Field to sort results by.", "required": false, "schema": { "type": "string", "default": "title", "enum": [ "title", "products_count", "phrases_count", "top_10_phrases", "top_50_phrases", "top_10_sv", "top_50_sv", "top_10_sponsored_phrases", "top_50_sponsored_phrases", "top_10_sponsored_sv", "top_50_sponsored_sv", "created_at" ] } }, { "name": "sortDesc", "in": "query", "description": "When `true`, results are sorted in descending order.", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Paginated list of groups", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RtGroupExtended" } }, "links": { "$ref": "#\/components\/schemas\/PaginationLinks" }, "meta": { "$ref": "#\/components\/schemas\/PaginationMeta" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Rank Tracker" ], "summary": "Create group", "description": "Creates a new Rank Tracker group for the specified ASIN on the given marketplace, with an initial list of keywords to track.", "operationId": "rt_create_group", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "marketplace", "asin", "phrases" ], "properties": { "marketplace": { "$ref": "#\/components\/schemas\/RtMarketplace" }, "asin": { "description": "Amazon product identifier (10 characters).", "type": "string", "example": "B08N5WRWNW" }, "phrases": { "description": "Initial list of keywords to track.", "type": "array", "items": { "type": "string" }, "example": [ "wireless earbuds", "bluetooth headphones" ], "minItems": 1 }, "trackAllVariations": { "description": "Whether to track only the given ASIN or all its variations. If a child ASIN is provided and this is `true`, the parent ASIN will be tracked together with all its variations.", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "201": { "description": "Group created", "content": { "application\/json": { "schema": { "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/RtGroup" }, { "properties": { "product": { "oneOf": [ { "$ref": "#\/components\/schemas\/RtProduct" } ], "nullable": true, "description": "Primary product details." } }, "type": "object" } ] } }, "type": "object" } } } }, "402": { "description": "Phrase limit exceeded" }, "422": { "description": "Validation error" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Rank Tracker" ], "summary": "Delete groups", "description": "Permanently deletes multiple Rank Tracker groups by their IDs.", "operationId": "rt_delete_groups_batch", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "groups" ], "properties": { "groups": { "description": "Array of group IDs to delete.", "type": "array", "items": { "type": "integer" }, "example": [ 12, 15, 18 ], "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Groups deleted" }, "422": { "description": "Validation error \u2014 `groups` is missing or empty" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/detach-tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Detach tags from groups", "description": "Detaches tags from multiple groups.", "operationId": "rt_detach_group_tags_batch", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagIds", "groupIds" ], "properties": { "tagIds": { "description": "Tag IDs to detach. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 1, 3 ], "maxItems": 10, "minItems": 1 }, "groupIds": { "description": "Group IDs to detach tags from. Use the `id` field from `GET \/rank-tracker\/groups`.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 12, 13 ], "maxItems": 5000, "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags detached" }, "422": { "description": "Validation error - `tagIds` or `groupIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}": { "get": { "tags": [ "Rank Tracker" ], "summary": "Get group", "description": "Returns a single Rank Tracker group with phrase\/product counts.", "operationId": "rt_get_group", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "responses": { "200": { "description": "Group details", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/RtGroup" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Group not found" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Update group tags", "description": "Replaces the tag set on a group. Pass an empty array to remove all tags.", "operationId": "rt_update_group_tags", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagsIds" ], "properties": { "tagsIds": { "description": "Tag IDs to assign. Replaces the current tag set. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 1, 3 ] } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags updated" }, "422": { "description": "Validation error \u2014 `tagsIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "deprecated": true, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/phrases\/attach-tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Attach tags to keywords", "description": "Attaches tags to multiple keywords. Each tag ID is attached to each provided keyword ID.", "operationId": "rt_attach_phrase_tags_batch", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagIds", "phraseIds" ], "properties": { "tagIds": { "description": "Tag IDs to attach. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 1, 3 ], "maxItems": 10, "minItems": 1 }, "phraseIds": { "description": "Keyword IDs that should receive the provided tags. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases`.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 101, 102 ], "maxItems": 5000, "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags attached" }, "422": { "description": "Validation error - `tagIds` or `phraseIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/phrases": { "delete": { "tags": [ "Rank Tracker" ], "summary": "Remove keywords", "description": "Removes multiple keywords from a group.", "operationId": "rt_delete_phrases_batch", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "phrases" ], "properties": { "phrases": { "description": "IDs of the keywords to remove. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases`.", "type": "array", "items": { "type": "integer" }, "example": [ 101, 102, 103 ], "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Keywords removed" }, "400": { "description": "phrases array is empty or no matching keywords found in the group" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/phrases\/detach-tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Detach tags from keywords", "description": "Detaches tags from multiple keywords.", "operationId": "rt_detach_phrase_tags_batch", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagIds", "phraseIds" ], "properties": { "tagIds": { "description": "Tag IDs to detach. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 1, 3 ], "maxItems": 10, "minItems": 1 }, "phraseIds": { "description": "Keyword IDs to detach tags from. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases`.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 101, 102 ], "maxItems": 5000, "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags detached" }, "422": { "description": "Validation error - `tagIds` or `phraseIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/phrases-list": { "get": { "tags": [ "Rank Tracker" ], "summary": "Get keyword list", "description": "Returns the full list of keywords tracked in a group as a flat array. Each item includes the phrase text, search volume, and flags indicating whether it is used in this group (`isUsedForCurrentProduct`) or in another group of the company (`isUsedForAnotherProduct`).", "operationId": "rt_get_phrases_list", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "responses": { "200": { "description": "Keyword list", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "phrase": { "type": "string", "example": "wireless earbuds" }, "searchVolume": { "type": "integer", "example": 45000, "nullable": true }, "isNew": { "type": "boolean", "example": false }, "isUsedForCurrentProduct": { "type": "boolean", "example": true }, "isUsedForAnotherProduct": { "type": "boolean", "example": false } }, "type": "object" } } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Rank Tracker" ], "summary": "Replace keyword list", "description": "Replaces the entire keyword list for a group with the provided array. Keywords not present in the new list are removed; new keywords are added and queued for tracking. Returns 402 if the resulting total phrase count across the company would exceed the plan limit.", "operationId": "rt_set_phrases_list", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "phrases" ], "properties": { "phrases": { "description": "Full replacement keyword list.", "type": "array", "items": { "type": "string" }, "example": [ "wireless earbuds", "bluetooth earphones", "noise cancelling headphones" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated group", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/RtGroup" } }, "type": "object" } } } }, "402": { "description": "Phrase limit exceeded" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/positions-chart-data\/{id}": { "get": { "tags": [ "Rank Tracker" ], "summary": "Get position history", "description": "Returns the full position history for a specific keyword\u2013product pair, useful for rendering a rank history chart.", "operationId": "rt_get_positions_chart", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } }, { "name": "id", "in": "path", "description": "The phrase\u2013product data record ID. Use the `dataId` field from `GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases`.", "required": true, "schema": { "type": "integer", "example": 205 } }, { "name": "type", "in": "query", "description": "Position type to retrieve. `1` = ORGANIC(default),`2` = SPONSORED.", "required": false, "schema": { "type": "integer", "default": 1, "enum": [ 1, 2 ] } } ], "responses": { "200": { "description": "Position history", "content": { "application\/json": { "schema": { "properties": { "data": { "properties": { "product": { "properties": { "id": { "type": "integer", "example": 7 }, "marketplace": { "$ref": "#\/components\/schemas\/RtMarketplace" }, "asin": { "type": "string", "example": "B08N5WRWNW" }, "title": { "type": "string", "example": "Echo Dot (4th Gen)" }, "image": { "type": "string", "format": "uri", "nullable": true }, "variationsCount": { "type": "integer", "example": 3, "nullable": true } }, "type": "object" }, "history": { "type": "array", "items": { "properties": { "created_at": { "description": "Unix timestamp of the recorded position.", "type": "integer", "example": 1777031712 }, "position": { "type": "integer", "example": 7, "nullable": true }, "asin": { "type": "string", "example": "B08N5WRWNW", "nullable": true } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/heatmap-widgets": { "get": { "tags": [ "Rank Tracker" ], "summary": "Get heatmap summary widgets", "description": "Returns pre-aggregated daily summary widgets for the heatmap date range: visibility score, average rank, Amazon's Choice count, and rank distribution. Accepts the same filters as `GET ...\/phrases\/v2` (search, onlyBoosted, resultsType). Requires `heatmapDateFrom` and `heatmapDateTo` (max 92 days). Each widget array is sorted from newest to oldest date.", "operationId": "rt_heatmap_widgets", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } }, { "name": "productId", "in": "path", "description": "The ID of the product within the group. Returned by `GET \/rank-tracker\/groups\/{groupId}\/products`.", "required": true, "schema": { "type": "integer", "example": 7 } }, { "name": "heatmapDateFrom", "in": "query", "description": "Start date for the summary range (YYYY-MM-DD). Required.", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-04-05" } }, { "name": "heatmapDateTo", "in": "query", "description": "End date for the summary range (YYYY-MM-DD). Max range: 92 days. Required.", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-05-04" } }, { "name": "resultsType", "in": "query", "description": "Which position type to aggregate. `organic` (default) or `sponsored`.", "required": false, "schema": { "type": "string", "default": "organic", "enum": [ "organic", "sponsored" ] } }, { "name": "search", "in": "query", "description": "Filter keywords by phrase text before aggregating.", "required": false, "schema": { "type": "string", "example": "bluetooth" } }, { "name": "onlyBoosted", "in": "query", "description": "When `true`, aggregate only boosted keywords.", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Heatmap summary widgets", "content": { "application\/json": { "schema": { "properties": { "data": { "properties": { "visibility": { "description": "Daily search-volume-weighted visibility score (0\u2013100). Each ranked keyword contributes its \u221a(searchVolume) \u00d7 rankWeight, where rankWeight follows Amazon's SERP CTR distribution (1.0 for position 1, down to 0.005 for positions 49\u2013100, 0 beyond 100 or not found). Higher is better.", "type": "array", "items": { "$ref": "#\/components\/schemas\/HeatmapWidgetDay" } }, "average": { "description": "Daily average rank across all keywords in the set. Keywords not found in results are counted as position 306. Lower is better.", "type": "array", "items": { "$ref": "#\/components\/schemas\/HeatmapWidgetDay" } }, "amazonChoice": { "description": "Daily count of keywords for which the tracked product held the \"Amazon's Choice\" badge.", "type": "array", "items": { "$ref": "#\/components\/schemas\/HeatmapWidgetDay" } }, "distribution": { "description": "Daily breakdown of keywords by rank bucket.", "type": "array", "items": { "properties": { "date": { "description": "Calendar date (YYYY-MM-DD).", "type": "string", "format": "date", "example": "2026-04-23" }, "notTracked": { "description": "Keywords with no data collected for this day (null rank).", "type": "integer", "example": 0 }, "100+": { "description": "Keywords ranked beyond position 100 or not found in results.", "type": "integer", "example": 3 }, "51-100": { "description": "Keywords ranked 51\u2013100.", "type": "integer", "example": 1 }, "11-50": { "description": "Keywords ranked 11\u201350.", "type": "integer", "example": 2 }, "4-10": { "description": "Keywords ranked 4\u201310.", "type": "integer", "example": 1 }, "1-3": { "description": "Keywords ranked 1\u20133.", "type": "integer", "example": 3 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Invalid or missing date range" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases\/v2": { "get": { "tags": [ "Rank Tracker" ], "summary": "List keyword positions", "description": "Returns the current organic and sponsored rank positions for every tracked keyword of a specific product in a group. Supports optional heatmap mode (pass `heatmap=true` with `heatmapDateFrom` and `heatmapDateTo`): each keyword item in the response will include additional fields named `r_YYYY-MM-DD` (one per day in the requested range). Each field is an object with three keys: `date` (string, YYYY-MM-DD), `rank` (integer or `null` \u2014 `null` means no data was collected for that day, `0` means the product was not found in search results), and `amazon_choice` (boolean). Example: `\"r_2026-04-23\": {\"date\": \"2026-04-23\", \"rank\": null, \"amazon_choice\": false}`. The `rank` value reflects the position type selected by `resultsType` (organic or sponsored). Maximum date range: 92 days.", "operationId": "rt_list_phrases", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } }, { "name": "productId", "in": "path", "description": "The ID of the product within the group. Returned by `GET \/rank-tracker\/groups\/{groupId}\/products`.", "required": true, "schema": { "type": "integer", "example": 7 } }, { "name": "page", "in": "query", "description": "Page number for pagination, starting from 1.", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Number of results per page.", "required": false, "schema": { "type": "integer", "example": 25, "minimum": 1 } }, { "name": "resultsType", "in": "query", "description": "Which position type to use for sorting. `organic` (default) or `sponsored`.", "required": false, "schema": { "type": "string", "default": "organic", "enum": [ "organic", "sponsored" ] } }, { "name": "sort", "in": "query", "description": "Field to sort results by.", "required": false, "schema": { "type": "string", "default": "phrase", "enum": [ "phrase", "organic_position", "sponsored_position", "search_volume", "results_number", "aba_search_frequency_rank", "aba_total_click_share", "aba_total_conv_share", "cpc", "tracked_at", "created_at" ] } }, { "name": "sortDesc", "in": "query", "description": "When `true`, results are sorted in descending order.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "search", "in": "query", "description": "Filter keywords by phrase text.", "required": false, "schema": { "type": "string", "example": "bluetooth" } }, { "name": "tags[]", "in": "query", "description": "Filter keywords by tag IDs.", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "onlyBoosted", "in": "query", "description": "When `true`, return only boosted keywords.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "heatmap", "in": "query", "description": "Enable heatmap mode. Requires `heatmapDateFrom` and `heatmapDateTo`.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "heatmapDateFrom", "in": "query", "description": "Start date for heatmap mode (YYYY-MM-DD). Required when `heatmap=true`.", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-03-01" } }, { "name": "heatmapDateTo", "in": "query", "description": "End date for heatmap mode (YYYY-MM-DD). Max range: 92 days. Required when `heatmap=true`.", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-03-31" } } ], "responses": { "200": { "description": "Paginated list of tracked keywords with positions", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RtPhrase" } }, "meta": { "$ref": "#\/components\/schemas\/SimplePaginationMeta" } }, "type": "object" } } } }, "400": { "description": "Invalid date range" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/phrases\/{phraseId}\/toggle-boost-state": { "post": { "tags": [ "Rank Tracker" ], "summary": "Toggle keyword boost", "description": "Enables or disables high-frequency tracking (boost) for a keyword. Boost is only available for keywords with search volume \u2265 500. An active boost automatically expires after 168 hours. Returns 402 if the plan boost limit is reached.", "operationId": "rt_toggle_phrase_boost", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } }, { "name": "phraseId", "in": "path", "description": "The unique ID of the keyword within this group. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases`.", "required": true, "schema": { "type": "integer", "example": 101 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "isBoosted" ], "properties": { "isBoosted": { "description": "`true` to enable boost, `false` to disable.", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Boost state updated", "content": { "application\/json": { "schema": { "properties": { "data": { "properties": { "remainingBoostTime": { "description": "Seconds until the boost expires. `null` when boost is disabled.", "type": "integer", "example": 86400, "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Search volume too low (< 500)" }, "402": { "description": "Boost limit reached" }, "422": { "description": "Validation error \u2014 isBoosted is missing or not a boolean" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/phrases\/{phraseId}\/tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Update keyword tags", "description": "Replaces the tag set on a keyword. Pass an empty array to remove all tags.", "operationId": "rt_update_phrase_tags", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } }, { "name": "phraseId", "in": "path", "description": "The unique ID of the keyword within this group. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases`.", "required": true, "schema": { "type": "integer", "example": 101 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagsIds" ], "properties": { "tagsIds": { "description": "Tag IDs to assign. Replaces the current tag set. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 1 ] } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags updated" }, "422": { "description": "Validation error - `tagsIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "deprecated": true, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/products\/attach-tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Attach tags to products", "description": "Attaches tags to multiple products. Each tag ID is attached to each provided product ID.", "operationId": "rt_attach_product_tags_batch", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagIds", "productIds" ], "properties": { "tagIds": { "description": "Tag IDs to attach. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 1, 3 ], "maxItems": 10, "minItems": 1 }, "productIds": { "description": "Product IDs that should receive the provided tags. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/products`.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 7, 8 ], "maxItems": 5000, "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags attached" }, "422": { "description": "Validation error - `tagIds` or `productIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/products": { "get": { "tags": [ "Rank Tracker" ], "summary": "List products in group", "description": "Returns all products (ASINs) attached to a group, without ranking statistics.", "operationId": "rt_list_products", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "responses": { "200": { "description": "List of products", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RtProduct" } } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Rank Tracker" ], "summary": "Add products to group", "description": "Attaches one or more products (ASINs) to an existing group. Product details (title, image) are fetched from Amazon automatically. ASINs already in the group are rejected by validation. If the product limit is reached, the request succeeds but no products are added.", "operationId": "rt_attach_products", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "required": [ "asin", "trackAllVariations" ], "properties": { "asin": { "description": "Amazon product identifier (10 characters).", "type": "string", "example": "B07XJ8C8F5" }, "trackAllVariations": { "description": "Whether to track only the given ASIN or all its variations. If a child ASIN is provided and this is `true`, the parent ASIN will be tracked together with all its variations.", "type": "boolean", "example": false } }, "type": "object" }, "minItems": 1 } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated group", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/RtGroup" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Rank Tracker" ], "summary": "Remove products from group", "description": "Removes multiple products from a group. The primary product is automatically excluded from deletion even if its ID is listed.", "operationId": "rt_delete_products_batch", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "products" ], "properties": { "products": { "description": "Product IDs to remove.", "type": "array", "items": { "type": "integer" }, "example": [ 8, 9 ] } }, "type": "object" } } } }, "responses": { "200": { "description": "IDs of deleted products", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "type": "integer" }, "example": [ 8, 9 ] } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/products\/detach-tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Detach tags from products", "description": "Detaches tags from multiple products.", "operationId": "rt_detach_product_tags_batch", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagIds", "productIds" ], "properties": { "tagIds": { "description": "Tag IDs to detach. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 1, 3 ], "maxItems": 10, "minItems": 1 }, "productIds": { "description": "Product IDs to detach tags from. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/products`.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 7, 8 ], "maxItems": 5000, "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags detached" }, "422": { "description": "Validation error - `tagIds` or `productIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/products-with-stats": { "get": { "tags": [ "Rank Tracker" ], "summary": "List products with ranking stats", "description": "Returns a paginated list of products in a group enriched with aggregated ranking metrics (average organic\/sponsored rank, number of ranking keywords, total ranked search volume).", "operationId": "rt_list_products_with_stats", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } }, { "name": "page", "in": "query", "description": "Page number for pagination, starting from 1.", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Number of results per page.", "required": false, "schema": { "type": "integer", "example": 15, "minimum": 1 } }, { "name": "productId", "in": "query", "description": "Filter to a specific product ID. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/products`.", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search by ASIN or title.", "required": false, "schema": { "type": "string", "example": "B08N5WRWNW" } }, { "name": "tags[]", "in": "query", "description": "Filter by tag IDs. Use the `id` field from `GET \/rank-tracker\/groups\/{groupId}\/tags`.", "required": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "name": "sort", "in": "query", "description": "Field to sort results by.", "required": false, "schema": { "type": "string", "default": "id", "enum": [ "id", "title", "asin", "variations_count", "avg_organic_rank", "avg_sponsored_rank", "ranking_organic_keywords", "ranking_sponsored_keywords", "ranked_organic_sv", "ranked_sponsored_sv", "created_at", "data_updated_at" ] } }, { "name": "sortDesc", "in": "query", "description": "When `true`, results are sorted in descending order.", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Paginated list of products with stats", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RtProductWithStats" } }, "links": { "$ref": "#\/components\/schemas\/PaginationLinks" }, "meta": { "$ref": "#\/components\/schemas\/PaginationMeta" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/tags": { "post": { "tags": [ "Rank Tracker" ], "summary": "Update product tags", "description": "Replaces the tag set on a product. Pass an empty array to remove all tags.", "operationId": "rt_update_product_tags", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } }, { "name": "productId", "in": "path", "description": "The ID of the product within the group. Returned by `GET \/rank-tracker\/groups\/{groupId}\/products`.", "required": true, "schema": { "type": "integer", "example": 7 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "tagsIds" ], "properties": { "tagsIds": { "description": "Tag IDs to assign. Replaces the current tag set. Use `GET \/rank-tracker\/tags` to retrieve available IDs.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 2 ] } }, "type": "object" } } } }, "responses": { "204": { "description": "Tags updated" }, "422": { "description": "Validation error - `tagsIds` is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "deprecated": true, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/groups\/{groupId}\/suggested-phrases": { "get": { "tags": [ "Rank Tracker" ], "summary": "List suggested phrases", "description": "Returns a paginated list of keywords suggested by SoldScope for a group, excluding those that have already been ignored.", "operationId": "rt_list_suggested_phrases", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } }, { "name": "page", "in": "query", "description": "Page number for pagination, starting from 1.", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Number of results per page.", "required": false, "schema": { "type": "integer", "example": 15, "minimum": 1 } }, { "name": "search", "in": "query", "description": "Filter by keyword text.", "required": false, "schema": { "type": "string", "example": "earbuds" } }, { "name": "sort", "in": "query", "description": "Field to sort results by.", "required": false, "schema": { "type": "string", "default": "id", "enum": [ "id", "keyword", "search_volume" ] } }, { "name": "sortDesc", "in": "query", "description": "When `true`, results are sorted in descending order.", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Paginated list of suggested phrases", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RtSuggestedPhrase" } }, "links": { "$ref": "#\/components\/schemas\/PaginationLinks" }, "meta": { "$ref": "#\/components\/schemas\/PaginationMeta" } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Rank Tracker" ], "summary": "Apply suggested phrases", "description": "Adds selected suggested phrases to the group's tracked keyword list. If none of the provided IDs match pending suggestions, the request succeeds with no changes. Returns 402 if accepting them would exceed the phrase limit.", "operationId": "rt_apply_suggested_phrases", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "suggestionsIds" ], "properties": { "suggestionsIds": { "description": "Suggestion IDs to accept (use `suggestionId` from the list response).", "type": "array", "items": { "type": "integer" }, "example": [ 55, 56 ], "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Phrases added to tracking" }, "402": { "description": "Phrase limit exceeded" }, "422": { "description": "Validation error \u2014 suggestionsIds is missing or contains invalid values" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Rank Tracker" ], "summary": "Ignore suggested phrases", "description": "Marks selected suggestions as ignored so they no longer appear in the list. If none of the provided IDs match pending suggestions, the request succeeds with no changes.", "operationId": "rt_ignore_suggested_phrases", "parameters": [ { "name": "groupId", "in": "path", "description": "The ID of the Rank Tracker group. Returned by `GET \/rank-tracker\/groups`.", "required": true, "schema": { "type": "integer", "example": 12 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "suggestionsIds" ], "properties": { "suggestionsIds": { "description": "Suggestion IDs to ignore.", "type": "array", "items": { "type": "integer" }, "example": [ 57, 58 ], "minItems": 1 } }, "type": "object" } } } }, "responses": { "204": { "description": "Suggestions ignored" }, "422": { "description": "Validation error \u2014 suggestionsIds is missing or empty" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/suggested-keywords": { "get": { "tags": [ "Rank Tracker" ], "summary": "Get AI-suggested keywords", "description": "Returns up to 300 keyword suggestions generated by SoldScope AI. Provide either `groupId` (to base suggestions on an existing group) or `asins` + `marketplace` (to get suggestions for specific ASINs). Requires the AI Suggestions feature on the plan.", "operationId": "rt_get_suggested_keywords", "parameters": [ { "name": "groupId", "in": "query", "description": "The ID of the group to generate suggestions for (returned by `GET \/rank-tracker\/groups`). Required if `asins` is omitted.", "required": false, "schema": { "type": "integer", "example": 12 } }, { "name": "asins[]", "in": "query", "description": "ASINs to generate suggestions for (max 10). Required if `groupId` is omitted.", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, { "name": "marketplace", "in": "query", "description": "Marketplace for ASIN-based suggestions. Required if `groupId` is omitted.", "required": false, "schema": { "$ref": "#\/components\/schemas\/RtMarketplace" } } ], "responses": { "200": { "description": "Suggested keywords. Returns an empty array if no suggestions are found.", "content": { "application\/json": { "schema": { "properties": { "keywords": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 993 }, "keyword": { "type": "string", "example": "wireless earbuds sport" } }, "type": "object" }, "example": [ { "id": 993, "keyword": "wireless earbuds sport" }, { "id": 994, "keyword": "bluetooth earphones running" } ] } }, "type": "object" } } } }, "402": { "description": "AI Suggestions feature not available on current plan" }, "404": { "description": "Group not found" }, "422": { "description": "Validation error \u2014 neither groupId nor asins+marketplace provided" }, "429": { "description": "Rate limit exceeded (10 req\/min)" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/tags": { "get": { "tags": [ "Rank Tracker" ], "summary": "List tags", "description": "Returns all tags created in the selected account, sorted by title. Each tag includes a count of how many groups and phrases use it.", "operationId": "rt_list_tags", "responses": { "200": { "description": "List of tags", "content": { "application\/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RtTag" } } }, "type": "object" } } } }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Rank Tracker" ], "summary": "Create tag", "description": "Creates a new tag for the selected account. If a tag with the same title and color already exists, the existing tag is returned.", "operationId": "rt_create_tag", "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "title", "color" ], "properties": { "title": { "description": "Tag label displayed in the UI.", "type": "string", "example": "Best sellers", "maxLength": 255 }, "color": { "description": "Hex color code.", "type": "string", "example": "#FF5733" } }, "type": "object" } } } }, "responses": { "201": { "description": "Tag created", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/RtTag" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" } }, "security": [ { "bearerAuth": [] } ] } }, "\/rank-tracker\/tags\/{tag}": { "put": { "tags": [ "Rank Tracker" ], "summary": "Update tag", "description": "Updates the title and color of an existing tag. Both fields are required.", "operationId": "rt_update_tag", "parameters": [ { "name": "tag", "in": "path", "description": "The ID of the tag. Returned by `GET \/rank-tracker\/tags`.", "required": true, "schema": { "type": "integer", "example": 1 } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "required": [ "title", "color" ], "properties": { "title": { "description": "Tag label displayed in the UI.", "type": "string", "example": "Top performers", "maxLength": 255 }, "color": { "description": "Hex color code.", "type": "string", "example": "#33FF57" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated tag", "content": { "application\/json": { "schema": { "properties": { "data": { "$ref": "#\/components\/schemas\/RtTag" } }, "type": "object" } } } }, "422": { "description": "Validation error" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Tag not found" } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Rank Tracker" ], "summary": "Delete tag", "description": "Permanently deletes a tag. It is automatically detached from all groups, products, and phrases.", "operationId": "rt_delete_tag", "parameters": [ { "name": "tag", "in": "path", "description": "The ID of the tag. Returned by `GET \/rank-tracker\/tags`.", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "204": { "description": "Tag deleted" }, "401": { "$ref": "#\/components\/responses\/Unauthenticated" }, "403": { "$ref": "#\/components\/responses\/Forbidden" }, "404": { "description": "Tag not found" } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "schemas": { "KrSearch": { "properties": { "id": { "type": "integer", "example": 42 }, "accountId": { "description": "The ID of the account this search belongs to.", "type": "integer", "example": 1 }, "searchType": { "$ref": "#\/components\/schemas\/KrSearchType" }, "marketplace": { "$ref": "#\/components\/schemas\/KrAvailableMarketplace" }, "dateFrom": { "description": "Start of the date range used for keyword data.", "type": "string", "format": "date", "example": "2026-02-01", "nullable": true }, "dateTo": { "description": "End of the date range used for keyword data.", "type": "string", "format": "date", "example": "2026-05-01", "nullable": true }, "keywords": { "type": "string", "example": "wireless earbuds", "nullable": true }, "mainAsin": { "type": "string", "example": "B08N5WRWNW", "nullable": true }, "mainAsinTitle": { "type": "string", "example": "Echo Dot (4th Gen)", "nullable": true }, "mainAsinImageUrl": { "type": "string", "format": "uri", "example": "https:\/\/m.media-amazon.com\/images\/I\/example.jpg", "nullable": true }, "asins": { "type": "array", "items": { "type": "string" }, "example": [ "B08N5WRWNW", "B07XJ8C8F5" ], "nullable": true }, "status": { "$ref": "#\/components\/schemas\/KrSearchStatus" }, "lastFilters": { "description": "Last applied result filters. `null` if no filters were ever saved, `[]` if filters were cleared, otherwise an object with filter keys and their values.", "nullable": true, "oneOf": [ { "type": "object" }, { "type": "array", "items": {} } ] }, "deletedKeywords": { "description": "Keywords excluded from results", "type": "array", "items": { "type": "string" }, "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:31:00.000000Z" } }, "type": "object" }, "Asin": { "description": "Amazon ASIN (10-character alphanumeric identifier)", "type": "string", "example": "B08N5WRWNW" }, "Error": { "properties": { "message": { "type": "string", "example": "Error message." } }, "type": "object" }, "KrAmazonChoice": { "description": "0 = the analyzed product has the badge, 1 = other products have the badge, 2 = no badge for this keyword", "type": "integer", "example": 0, "enum": [ 0, 1, 2 ] }, "KrAsinPosition": { "description": "Ranking position data for a specific ASIN on a keyword.", "properties": { "organicAsin": { "oneOf": [ { "$ref": "#\/components\/schemas\/Asin" } ], "nullable": true }, "organicRank": { "type": "integer", "example": 125, "nullable": true }, "organicScrapeEventDate": { "type": "string", "format": "date", "example": "2026-03-22", "nullable": true }, "sponsoredAsin": { "oneOf": [ { "$ref": "#\/components\/schemas\/Asin" } ], "nullable": true }, "sponsoredRank": { "type": "integer", "example": null, "nullable": true }, "sponsoredScrapeEventDate": { "type": "string", "format": "date", "example": null, "nullable": true } }, "type": "object" }, "KrAvailableMarketplace": { "description": "Amazon marketplace supported by Keyword Research", "type": "string", "example": "US", "enum": [ "US", "CA", "MX", "UK", "DE", "ES", "FR", "IT" ] }, "KrKeyword": { "description": "Keyword entry from a single-ASIN search result.", "properties": { "id": { "type": "integer", "example": 460 }, "keyword": { "type": "string", "example": "dog toys" }, "marketplace": { "$ref": "#\/components\/schemas\/KrAvailableMarketplace" }, "searchVolume": { "description": "Estimated number of customer searches for this keyword over the past 30 days.", "type": "integer", "example": 784244, "nullable": true }, "totalResultCount": { "description": "Approximate number of products shown in Amazon search results for this keyword.", "type": "integer", "example": 61736, "nullable": true }, "organicRank": { "description": "Organic search position of the analyzed product (or its variations) for this keyword.", "type": "integer", "example": 133, "nullable": true }, "organicAsin": { "oneOf": [ { "$ref": "#\/components\/schemas\/Asin" } ], "nullable": true, "description": "The specific ASIN (may be a variation of the searched product) found in organic results." }, "organicScrapeEventDate": { "description": "Date when the organic rank was last collected.", "type": "string", "format": "date", "example": "2026-04-15", "nullable": true }, "sponsoredRank": { "description": "Sponsored position of the analyzed product (or its variations) for this keyword.", "type": "integer", "example": 64, "nullable": true }, "sponsoredAsin": { "oneOf": [ { "$ref": "#\/components\/schemas\/Asin" } ], "nullable": true, "description": "The specific ASIN (may be a variation) found in sponsored results." }, "sponsoredScrapeEventDate": { "description": "Date when the sponsored rank was last collected.", "type": "string", "format": "date", "example": "2026-03-04", "nullable": true }, "sponsoredProducts": { "description": "Total number of unique Sponsored Products recently shown in Amazon search results for this keyword.", "type": "integer", "example": 575, "nullable": true }, "opportunityScore": { "description": "Estimated potential of this keyword based on demand and competition. Score 1000+ = Excellent, 500\u20131000 = Good, 100\u2013500 = Moderate, <100 = Poor.", "type": "integer", "example": 354, "nullable": true }, "opportunityScoreAvg": { "description": "Average opportunity score across the keyword's category.", "type": "number", "format": "float", "example": 116.65, "nullable": true }, "svTrend": { "description": "Trend of Search Volume over the past 30 days (%).", "type": "number", "format": "float", "example": 2.3, "nullable": true }, "cpc": { "description": "Estimated suggested cost-per-click bid for sponsored ads targeting this keyword.", "type": "number", "format": "float", "example": 1.21, "nullable": true }, "cpcMin": { "description": "Minimum estimated CPC bid.", "type": "number", "format": "float", "example": 0.87, "nullable": true }, "cpcMax": { "description": "Maximum estimated CPC bid.", "type": "number", "format": "float", "example": 1.55, "nullable": true }, "matchTypes": { "description": "Indicates whether the analyzed product appears in organic results (1), sponsored results (2), or both.", "type": "array", "items": { "$ref": "#\/components\/schemas\/KrMatchType" }, "example": [ 1, 2 ] }, "amazonChoice": { "oneOf": [ { "$ref": "#\/components\/schemas\/KrAmazonChoice" } ], "nullable": true, "description": "Amazon's Choice badge status for this keyword.", "example": 1 }, "categories": { "description": "Categories associated with this keyword based on products from search results.", "type": "array", "items": { "type": "string" }, "example": [ "Pet Supplies" ] }, "abaSearchFrequencyRank": { "description": "Popularity rank of this keyword from Amazon Brand Analytics. Lower rank means higher search volume. Available only with an active Brand Analytics token.", "type": "integer", "example": null, "nullable": true }, "abaTotalClickShare": { "description": "Total percentage of clicks captured by the top 3 clicked ASINs for this keyword in Amazon Brand Analytics. Available only with an active Brand Analytics token.", "type": "number", "format": "float", "example": null, "nullable": true }, "abaTotalConversionShare": { "description": "Total percentage of conversions generated by the top 3 ASINs for this keyword in Amazon Brand Analytics. Available only with an active Brand Analytics token.", "type": "number", "format": "float", "example": null, "nullable": true } }, "type": "object" }, "KrMatchType": { "description": "1 = ORGANIC, 2 = SPONSORED", "type": "integer", "example": 1, "enum": [ 1, 2 ] }, "KrMultiKeyword": { "description": "Keyword entry from a multi-ASIN or keyword search result. Contains aggregate stats across all compared ASINs, plus per-ASIN position data in `asinsPositions`.", "properties": { "id": { "type": "integer", "example": 460 }, "keyword": { "type": "string", "example": "dog toys" }, "marketplace": { "$ref": "#\/components\/schemas\/KrAvailableMarketplace" }, "searchVolume": { "description": "Estimated number of customer searches for this keyword over the past 30 days.", "type": "integer", "example": 784244, "nullable": true }, "totalResultCount": { "description": "Approximate number of products shown in Amazon search results for this keyword.", "type": "integer", "example": 61736, "nullable": true }, "mainOrganicRank": { "description": "Position the first (main) ASIN holds in Amazon's organic results for this keyword.", "type": "integer", "example": 125, "nullable": true }, "mainOrgRelativeRank": { "description": "Rank of the main ASIN relative to its competitors. For example, if two competitors rank better than the main ASIN, its relative rank is 3.", "type": "integer", "example": 1, "nullable": true }, "organicRankAvg": { "description": "Average organic position across all compared ASINs for this keyword.", "type": "number", "format": "float", "example": 185.5, "nullable": true }, "organicRankSum": { "description": "Sum of organic ranks across all compared ASINs.", "type": "integer", "example": 371, "nullable": true }, "organicAsinsCount": { "description": "Number of analyzed ASINs ranking in organic search results for this keyword.", "type": "integer", "example": 2, "nullable": true }, "mainSponsoredRank": { "description": "Sponsored position of the first (main) ASIN for this keyword.", "type": "integer", "example": null, "nullable": true }, "mainSpRelativeRank": { "description": "Rank of the main ASIN relative to its competitors in sponsored results.", "type": "integer", "example": null, "nullable": true }, "sponsoredRankAvg": { "description": "Average sponsored position across all compared ASINs for this keyword.", "type": "number", "format": "float", "example": 35, "nullable": true }, "sponsoredRankSum": { "description": "Sum of sponsored ranks across all compared ASINs.", "type": "integer", "example": 35, "nullable": true }, "sponsoredAsinsCount": { "description": "Number of analyzed ASINs ranking in sponsored search results for this keyword.", "type": "integer", "example": 1, "nullable": true }, "sponsoredProducts": { "description": "Total number of unique Sponsored Products recently shown in Amazon search results for this keyword.", "type": "integer", "example": 575, "nullable": true }, "opportunityScore": { "description": "Estimated potential of this keyword based on demand and competition. Score 1000+ = Excellent, 500\u20131000 = Good, 100\u2013500 = Moderate, <100 = Poor.", "type": "integer", "example": 354, "nullable": true }, "opportunityScoreAvg": { "description": "Average opportunity score across the keyword's category.", "type": "number", "format": "float", "example": 116.65, "nullable": true }, "svTrend": { "description": "Trend of Search Volume over the past 30 days (%).", "type": "number", "format": "float", "example": 2.3, "nullable": true }, "cpc": { "description": "Estimated suggested cost-per-click bid for sponsored ads targeting this keyword.", "type": "number", "format": "float", "example": 1.21, "nullable": true }, "cpcMin": { "description": "Minimum estimated CPC bid.", "type": "number", "format": "float", "example": 0.87, "nullable": true }, "cpcMax": { "description": "Maximum estimated CPC bid.", "type": "number", "format": "float", "example": 1.55, "nullable": true }, "matchTypes": { "description": "Indicates whether any of the compared ASINs appear in organic results (1), sponsored results (2), or both.", "type": "array", "items": { "$ref": "#\/components\/schemas\/KrMatchType" }, "example": [ 1, 2 ] }, "amazonChoice": { "oneOf": [ { "$ref": "#\/components\/schemas\/KrAmazonChoice" } ], "nullable": true, "description": "Amazon's Choice badge status for this keyword.", "example": 1 }, "categories": { "description": "Categories associated with this keyword based on products from search results.", "type": "array", "items": { "type": "string" }, "example": [ "Pet Supplies" ] }, "asinsPositions": { "description": "Per-ASIN ranking data. Keys are the ASIN strings passed in the request.", "type": "object", "example": { "B08N5WRWNW": { "organicAsin": "B08N5WRWNW", "organicRank": 125, "organicScrapeEventDate": "2026-03-22", "sponsoredAsin": null, "sponsoredRank": null, "sponsoredScrapeEventDate": null } }, "additionalProperties": { "$ref": "#\/components\/schemas\/KrAsinPosition" } }, "abaSearchFrequencyRank": { "description": "Popularity rank of this keyword from Amazon Brand Analytics. Lower rank means higher search volume. Available only with an active Brand Analytics token.", "type": "integer", "example": null, "nullable": true }, "abaTotalClickShare": { "description": "Total percentage of clicks captured by the top 3 clicked ASINs for this keyword in Amazon Brand Analytics. Available only with an active Brand Analytics token.", "type": "number", "format": "float", "example": null, "nullable": true }, "abaTotalConversionShare": { "description": "Total percentage of conversions generated by the top 3 ASINs for this keyword in Amazon Brand Analytics. Available only with an active Brand Analytics token.", "type": "number", "format": "float", "example": null, "nullable": true } }, "type": "object" }, "KrPhrasesContainMode": { "description": "0 = only include keywords containing the phrase, 1 = exclude keywords containing the phrase", "type": "integer", "example": 0, "enum": [ 0, 1 ] }, "KrProductDetails": { "description": "Full product details for the analyzed ASIN in a single-ASIN search.", "properties": { "asin": { "$ref": "#\/components\/schemas\/Asin" }, "marketplace": { "$ref": "#\/components\/schemas\/KrAvailableMarketplace" }, "isParent": { "description": "Whether this listing is a parent ASIN (has child variations).", "type": "boolean" }, "isVariation": { "description": "Whether this listing is a variation of a parent ASIN.", "type": "boolean" }, "title": { "description": "Product listing title.", "type": "string", "example": "Dog Toy for Aggressive Chewers" }, "coverImage": { "description": "Main product image URL (processed\/resized).", "type": "string", "format": "uri", "example": "https:\/\/m.media-amazon.com\/images\/I\/7100qM5aHZL.jpg", "nullable": true }, "coverImageRaw": { "description": "Main product image filename as returned by Amazon (not a full URL).", "type": "string", "example": "7100qM5aHZL.jpg", "nullable": true }, "parentAsin": { "description": "ASIN of the parent product. `null` if this is already a parent.", "type": "string", "example": "B07XJ8C8F5", "nullable": true }, "parentTitle": { "type": "string", "nullable": true }, "parentCoverImage": { "type": "string", "format": "uri", "example": "https:\/\/m.media-amazon.com\/images\/I\/71his+3e6QL.jpg", "nullable": true }, "parentCoverImageRaw": { "description": "Parent product image filename as returned by Amazon (not a full URL).", "type": "string", "example": "71his+3e6QL.jpg", "nullable": true }, "variations": { "description": "ASINs of all sibling variations (empty for parent-less products).", "type": "array", "items": { "$ref": "#\/components\/schemas\/Asin" } }, "brand": { "type": "string", "example": "Benebone", "nullable": true }, "rating": { "description": "Customer rating stored as an integer \u00d7 10 (e.g. `45` = 4.5 stars). `null` if unavailable.", "type": "integer", "example": 46, "nullable": true }, "reviewCount": { "description": "Total number of customer reviews.", "type": "integer", "example": 12483, "nullable": true }, "listedSince": { "description": "Date the product was first listed on Amazon (ISO 8601). `null` if unavailable.", "type": "string", "format": "date-time", "example": "2020-10-15T00:00:00.000000Z", "nullable": true }, "price": { "description": "Current price in cents (e.g. `1999` = $19.99). `null` if unavailable.", "type": "integer", "example": 1499, "nullable": true }, "fulfillmentType": { "description": "Buy-box fulfillment type: `1` = AMAZON, `2` = FBA, `3` = FBM. `null` if unavailable.", "type": "integer", "example": 2, "nullable": true, "enum": [ 1, 2, 3 ] }, "offersCount": { "description": "Number of active offers for this product.", "type": "integer", "example": 3, "nullable": true }, "productType": { "description": "Amazon product type identifier.", "type": "string", "example": "PET_SUPPLIES", "nullable": true }, "category": { "description": "Top-level Amazon category node.", "properties": { "catId": { "type": "integer", "example": 2619533011 }, "name": { "type": "string", "example": "Pet Supplies" } }, "type": "object", "nullable": true }, "subcategoriesBsr": { "description": "Best Seller Rank by subcategory, keyed by subcategory ID (as a string).", "type": "object", "example": { "2975414011": 66 }, "additionalProperties": { "type": "integer" } } }, "type": "object" }, "KrProductSummary": { "description": "Summary data for a single ASIN in a multi-ASIN search.", "properties": { "asin": { "$ref": "#\/components\/schemas\/Asin" }, "brand": { "type": "string", "example": "Feeko" }, "variationsCount": { "type": "integer", "example": 3, "nullable": true }, "rating": { "description": "Average customer rating on a 0\u20135 scale (e.g. `4.5`).", "type": "number", "format": "float", "example": 4.5, "nullable": true }, "reviewCount": { "description": "Total number of customer reviews.", "type": "integer", "example": 3383, "nullable": true }, "price": { "description": "Current price in the marketplace currency (e.g. `12.99` USD). Exception: for JP marketplace the value is in Yen without division.", "type": "number", "format": "float", "example": 12.99, "nullable": true }, "fulfillmentType": { "description": "Buy-box fulfillment type: `1` = AMAZON, `2` = FBA, `3` = FBM. `null` if unavailable.", "type": "integer", "example": 2, "nullable": true, "enum": [ 1, 2, 3 ] }, "offersCount": { "type": "integer", "example": null, "nullable": true }, "category": { "properties": { "catId": { "type": "integer", "example": 2619533011 }, "name": { "type": "string", "example": "Pet Supplies" } }, "type": "object", "nullable": true }, "listingAge": { "description": "Age of the listing as a PHP DateInterval serialized object.", "properties": { "y": { "description": "Years component.", "type": "integer", "example": 4 }, "m": { "description": "Months component.", "type": "integer", "example": 6 }, "d": { "description": "Days component.", "type": "integer", "example": 12 }, "h": { "description": "Hours component.", "type": "integer", "example": 0 }, "i": { "description": "Minutes component.", "type": "integer", "example": 0 }, "s": { "description": "Seconds component.", "type": "integer", "example": 0 }, "f": { "description": "Microseconds component.", "type": "number", "format": "float", "example": 0 }, "invert": { "description": "`1` if the interval is negative, `0` otherwise.", "type": "integer", "example": 0 }, "days": { "description": "Total number of days in the interval, or `false` if not computed from a date difference.", "example": 1655, "oneOf": [ { "type": "integer" }, { "type": "boolean" } ] }, "from_string": { "description": "Whether the interval was created from a string.", "type": "boolean", "example": false } }, "type": "object", "nullable": true } }, "type": "object" }, "KrResultMeta": { "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 500 } }, "type": "object" }, "KrSearchStatus": { "description": "0 = STARTED, 2 = COMPLETED, 13 = FAILED", "type": "integer", "example": 2, "enum": [ 0, 2, 13 ] }, "KrSearchType": { "description": "0 = SINGLE_ASIN, 1 = MULTI_ASIN, 2 = SINGLE_KEYWORD", "type": "integer", "example": 0, "enum": [ 0, 1, 2 ] }, "Marketplace": { "description": "Amazon marketplace code", "type": "string", "example": "US", "enum": [ "US", "CA", "MX", "BR", "IE", "ES", "UK", "FR", "BE", "NL", "DE", "IT", "SE", "ZA", "PL", "EG", "TR", "SA", "AE", "IN", "SG", "AU", "JP" ] }, "PaginationLinks": { "description": "Cursor links for navigating between pages.", "properties": { "first": { "description": "URL of the first page.", "type": "string", "format": "uri", "nullable": true }, "last": { "description": "URL of the last page.", "type": "string", "format": "uri", "nullable": true }, "prev": { "description": "URL of the previous page. `null` on the first page.", "type": "string", "format": "uri", "nullable": true }, "next": { "description": "URL of the next page. `null` on the last page.", "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "PaginationMeta": { "properties": { "current_page": { "type": "integer", "example": 1 }, "from": { "type": "integer", "example": 1, "nullable": true }, "last_page": { "type": "integer", "example": 5 }, "per_page": { "type": "integer", "example": 100 }, "to": { "type": "integer", "example": 100, "nullable": true }, "total": { "type": "integer", "example": 500 }, "path": { "type": "string", "format": "uri", "example": "https:\/\/www.soldscope.com\/api\/keyword-research\/searches" }, "links": { "description": "Pagination links array generated by Laravel.", "type": "array", "items": { "properties": { "url": { "type": "string", "format": "uri", "nullable": true }, "label": { "type": "string", "example": "1" }, "active": { "type": "boolean", "example": true } }, "type": "object" } } }, "type": "object" }, "PrCategory": { "description": "Amazon category node.", "properties": { "id": { "description": "Internal database ID. Use this value in `GET \/product-research\/categories\/{id}\/children`.", "type": "integer", "example": 4851 }, "nodeId": { "description": "Amazon category node ID. Use this value in `filters[categories][]` when searching products.", "type": "string", "example": "7141124011" }, "nodeName": { "description": "Category display name.", "type": "string", "example": "Electronics" }, "pathById": { "description": "Ordered list of node IDs from the root to this category.", "type": "array", "items": { "type": "string" }, "example": [ "7141123011", "7141124011" ] }, "pathByName": { "description": "Ordered list of category names from the root to this category. For top-level categories (level 2) this array contains only the category name itself.", "type": "array", "items": { "type": "string" }, "example": [ "Electronics" ] }, "marketplace": { "$ref": "#\/components\/schemas\/PrMarketplace" }, "childrenCount": { "description": "Number of direct child subcategories.", "type": "integer", "example": 12 }, "createdAt": { "description": "Format: `YYYY-MM-DD HH:MM:SS` (no timezone offset).", "type": "string", "example": "2025-05-21 07:22:16" }, "updatedAt": { "description": "Format: `YYYY-MM-DD HH:MM:SS` (no timezone offset).", "type": "string", "example": "2025-05-21 07:22:16" } }, "type": "object" }, "PrCategoryTreeNode": { "description": "A node in the category search tree. `nodeId` is the value to pass in `filters[categories][]` when searching products.", "properties": { "id": { "description": "Same as `nodeId` \u2014 Amazon category node ID.", "type": "string", "example": "7141124011" }, "nodeId": { "description": "Amazon category node ID. Use this value in `filters[categories][]` when searching products.", "type": "string", "example": "7141124011" }, "label": { "description": "Category display name.", "type": "string", "example": "Electronics" }, "children": { "description": "Nested subcategories.", "type": "array", "items": { "$ref": "#\/components\/schemas\/PrCategoryTreeNode" } } }, "type": "object" }, "PrFulfillmentType": { "description": "1 = AMAZON, 2 = FBA, 3 = FBM", "type": "integer", "example": 2, "enum": [ 1, 2, 3 ] }, "PrMarketplace": { "description": "Amazon marketplace supported by Product Research.", "type": "string", "example": "US", "enum": [ "US", "CA", "MX", "DE", "ES", "FR", "IT", "UK" ] }, "PrProduct": { "description": "A product returned by the Product Research search.", "properties": { "id": { "type": "integer", "example": 104728391, "nullable": true }, "asin": { "type": "string", "example": "B08N5WRWNW" }, "marketplace": { "$ref": "#\/components\/schemas\/PrMarketplace" }, "title": { "type": "string", "example": "Echo Dot (4th Gen) | Smart speaker with Alexa", "nullable": true }, "brand": { "type": "string", "example": "Amazon", "nullable": true }, "manufacturer": { "type": "string", "example": "Amazon", "nullable": true }, "image": { "description": "Filename of the main product image (not a full URL).", "type": "string", "example": "71Clkx5LaPL.jpg", "nullable": true }, "price": { "description": "Current buy-box price in the marketplace currency.", "type": "number", "format": "float", "example": 29.99, "nullable": true }, "priceTrend": { "description": "Price change over the last 90 days (percentage points).", "type": "number", "format": "float", "example": -5, "nullable": true }, "sales": { "description": "Estimated units sold over the last 30 days.", "type": "integer", "example": 3450, "nullable": true }, "salesTrend": { "description": "Sales change over the last 90 days (percentage points).", "type": "number", "format": "float", "example": 12, "nullable": true }, "yearlySales": { "description": "Estimated units sold over the last 365 days.", "type": "integer", "example": 41400, "nullable": true }, "yearOverYearTrend": { "description": "Sales change compared to the previous year (percentage points).", "type": "number", "format": "float", "example": 8, "nullable": true }, "bestSalesPeriod": { "description": "Start of the month with the highest historical sales (YYYY-MM-DD format, day is always 01).", "type": "string", "format": "date", "example": "2026-03-01", "nullable": true }, "revenue": { "description": "Estimated revenue over the last 30 days in the marketplace currency.", "type": "number", "format": "float", "example": 103455.5, "nullable": true }, "rating": { "description": "Average star rating (1.0\u20135.0).", "type": "number", "format": "float", "example": 4.6, "nullable": true }, "ratingsCount": { "description": "Total number of customer ratings.", "type": "integer", "example": 128500, "nullable": true }, "bsr": { "description": "Best Seller Rank in the root category.", "type": "integer", "example": 4, "nullable": true }, "subcategoriesBsr": { "description": "BSR entries for each subcategory the product appears in.", "type": "array", "items": { "properties": { "nodeId": { "description": "Amazon subcategory node ID.", "type": "integer", "example": 21209096011 }, "nodeName": { "description": "Subcategory display name. May equal the nodeId value when the category name is unavailable.", "type": "string", "example": "Smart Speakers" }, "bsr": { "type": "integer", "example": 1 } }, "type": "object" }, "nullable": true }, "category": { "description": "Root Amazon category node ID.", "type": "string", "example": "2335752011", "nullable": true }, "rootCategory": { "description": "Root category details. `null` if the product's category is not mapped.", "properties": { "id": { "type": "integer", "example": 14 }, "title": { "type": "string", "example": "Cell Phones & Accessories" }, "titleEn": { "type": "string", "example": "Cell Phones & Accessories" }, "websiteDisplayGroup": { "type": "string", "example": "wireless_display_on_website" }, "nodeId": { "type": "string", "example": "2335752011" }, "btgNodeId": { "type": "string", "example": "2335753011" }, "alias": { "type": "string", "example": "wireless" }, "productDatabaseEligible": { "type": "boolean", "example": true }, "salesEstimationAvailable": { "type": "boolean", "example": true }, "nodeIdAliases": { "type": "array", "items": { "type": "string" }, "example": [] } }, "type": "object", "nullable": true }, "subcategories": { "description": "List of subcategory names.", "type": "array", "items": { "type": "string" }, "example": [] }, "parentAsin": { "type": "string", "example": "B08N5WRWNW", "nullable": true }, "variationsCount": { "description": "Number of variations under the parent ASIN.", "type": "integer", "example": 3, "nullable": true }, "variations": { "description": "`true` if this product has variations that can be fetched.", "type": "boolean", "example": true }, "bbSeller": { "description": "Buy-box seller name.", "type": "string", "example": "Amazon.com", "nullable": true }, "bbSellerId": { "description": "Buy-box seller ID.", "type": "string", "example": "ATVPDKIKX0DER", "nullable": true }, "bbSellerType": { "oneOf": [ { "$ref": "#\/components\/schemas\/PrFulfillmentType" } ], "nullable": true }, "bbSellerCountry": { "description": "Two-letter country code of the buy-box seller.", "type": "string", "example": "US", "nullable": true }, "imagesCount": { "description": "Number of images in the listing.", "type": "integer", "example": 7, "nullable": true }, "sellerVideosCount": { "description": "Number of seller-uploaded videos.", "type": "integer", "example": 2, "nullable": true }, "influencersVideosCount": { "description": "Number of influencer videos.", "type": "integer", "example": 5, "nullable": true }, "customerVideosCount": { "description": "Number of customer-uploaded videos.", "type": "integer", "example": 12, "nullable": true }, "lqs": { "description": "Listing Quality Score (0\u2013100).", "type": "number", "format": "float", "example": 87, "nullable": true }, "listingAge": { "description": "Listing age in months.", "type": "integer", "example": 48, "nullable": true }, "sizeTier": { "description": "Amazon FBA size tier name.", "type": "string", "example": "Small standard-size", "nullable": true }, "weight": { "description": "Product weight in pounds.", "type": "number", "format": "float", "example": 0.87, "nullable": true }, "height": { "description": "Product height in inches.", "type": "number", "format": "float", "example": 3.9, "nullable": true }, "length": { "description": "Product length in inches.", "type": "number", "format": "float", "example": 3.9, "nullable": true }, "width": { "description": "Product width in inches.", "type": "number", "format": "float", "example": 3.5, "nullable": true }, "netPrice": { "description": "Estimated net price after FBA fees.", "type": "number", "format": "float", "example": 22.15, "nullable": true }, "netRevenue": { "description": "Estimated net revenue after FBA fees (30-day).", "type": "number", "format": "float", "example": 76444.75, "nullable": true }, "fbaFulfillmentFee": { "description": "Estimated FBA fulfillment fee in USD.", "type": "number", "format": "float", "example": 3.22, "nullable": true }, "referralFee": { "description": "Estimated referral fee in USD.", "type": "number", "format": "float", "example": 4.5, "nullable": true }, "hasAPlusContent": { "description": "`true` if the listing has A+ Content.", "type": "boolean", "example": true, "nullable": true }, "returnRate": { "description": "Amazon return frequency badge: 0 \u2014 unknown, 1 \u2014 fewer returns, 2 \u2014 frequently returned.", "type": "integer", "example": 1, "nullable": true }, "ean": { "description": "EAN barcodes. Empty array when none are available.", "type": "array", "items": { "type": "string" }, "example": [ "0840268902000" ] }, "upc": { "description": "UPC barcodes. Empty array when none are available.", "type": "array", "items": { "type": "string" }, "example": [ "840268902000" ] }, "gtin": { "description": "GTIN identifiers. Empty array when none are available.", "type": "array", "items": { "type": "string" }, "example": [ "00840268902000" ] }, "tm_data": { "description": "USPTO trademark data associated with this product. Returns an empty array `[]` when no trademark data is available.", "properties": { "uspto": { "properties": { "list": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 9916212 }, "prcode": { "description": "International Classification of Goods and Services codes.", "type": "array", "items": { "type": "string" }, "example": [ "009" ] }, "sernum": { "description": "USPTO application serial number.", "type": "integer", "example": 90849661 } }, "type": "object" } }, "count": { "description": "Total number of trademark records for this product.", "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "PrSearch": { "description": "A saved Product Research search (history entry).", "properties": { "id": { "description": "Search ID. Pass as `searchId` to `GET \/product-research\/products` to replay the search without consuming a search credit.", "type": "integer", "example": 1042 }, "marketplace": { "$ref": "#\/components\/schemas\/PrMarketplace" }, "accountId": { "description": "The ID of the account this search belongs to.", "type": "integer", "example": 7 }, "filters": { "description": "The filters applied when the search was created. Always includes `categoriesData` \u2014 an array of raw category objects (snake_case) for any categories that were selected, or an empty array. When categories were selected, a `categories` key is also present with a flat array of node ID strings. Other filter keys (e.g. `bsr`, `price`, `weight`, `videosCount`) appear only when set; each has `min` and `max` sub-keys whose values are strings or `null`.", "type": "object", "example": { "bsr": { "min": "10", "max": null }, "price": { "min": "45", "max": "135" }, "categories": [ "19201451011", "15690151" ], "categoriesData": [] } }, "resultsNumber": { "description": "Total number of products returned by this search.", "type": "integer", "example": 1847 }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000000Z" } }, "type": "object" }, "PrVideo": { "description": "A video associated with a product listing.", "properties": { "id": { "description": "Amazon video ID.", "type": "string", "example": "amzn1.vse.video.0cf81a754ed24bf788e4e0e9a6991385" }, "url": { "description": "HLS stream URL (`.m3u8`).", "type": "string", "format": "uri", "example": "https:\/\/m.media-amazon.com\/images\/S\/vse-vms-transcoding-artifact-us-east-1-prod\/649800dd-9333-49bd-b0ec-4586c218021d\/default.jobtemplate.hls.m3u8" }, "title": { "description": "Video title.", "type": "string", "example": "Mini Mic Pro: Small Mic. Big Sound." }, "preview": { "description": "Thumbnail image URL.", "type": "string", "format": "uri", "example": "https:\/\/m.media-amazon.com\/images\/I\/51Bs24tXhiL._CR1,0,638,360_SR342,193__BG0,0,0__QL65_.jpg" }, "duration": { "description": "Video duration in seconds.", "type": "integer", "example": 37 }, "creatorCode": { "description": "Creator identifier code.", "type": "string", "example": "Z7AX4" }, "creatorName": { "description": "Creator display name.", "type": "string", "example": "Designed in NYC" } }, "type": "object" }, "RtExport": { "description": "Represents an async Rank Tracker export. Poll `GET \/rank-tracker\/export\/{id}` until `status` is `1` or `2`.", "properties": { "id": { "description": "Unique identifier of the export.", "type": "integer", "example": 42 }, "groupId": { "description": "ID of the Rank Tracker group being exported.", "type": "integer", "example": 12 }, "dateFrom": { "description": "Start of the exported date range.", "type": "string", "format": "date", "example": "2026-01-01" }, "dateTo": { "description": "End of the exported date range.", "type": "string", "format": "date", "example": "2026-04-28" }, "products": { "description": "ASINs included in the export. `null` means all products in the group.", "type": "array", "items": { "type": "string" }, "example": [ "B08N5WRWNW" ], "nullable": true }, "filename": { "description": "Temporary download URL (S3 pre-signed, valid for 15 minutes). `null` while the export is still processing.", "type": "string", "format": "uri", "example": null, "nullable": true }, "status": { "description": "`null` or 0 \u2014 PENDING, 1 \u2014 COMPLETED, 2 \u2014 FAILED. `null` is returned immediately after creation before the first status update.", "type": "integer", "example": 0, "nullable": true, "enum": [ null, 0, 1, 2 ] }, "format": { "description": "Output file format.", "type": "string", "example": "csv", "enum": [ "csv", "json" ] }, "granularity": { "description": "`raw` \u2014 one row per tracking snapshot. `daily` \u2014 one row per keyword per calendar day.", "type": "string", "example": "raw", "enum": [ "raw", "daily" ] }, "createdAt": { "description": "When the export was created.", "type": "string", "format": "date-time", "example": "2026-04-28T10:00:00.000000Z" }, "updatedAt": { "description": "When the export was last updated.", "type": "string", "format": "date-time", "example": "2026-04-28T10:00:45.000000Z", "nullable": true } }, "type": "object" }, "RtGroupExtended": { "description": "Rank Tracker group as returned by the list endpoint \u2014 includes aggregated keyword ranking stats.", "properties": { "id": { "description": "Unique identifier of the group.", "type": "integer", "example": 12 }, "accountId": { "description": "The ID of the account this group belongs to.", "type": "integer", "example": 3 }, "marketplace": { "$ref": "#\/components\/schemas\/RtMarketplace" }, "asin": { "description": "ASIN of the primary product in this group.", "type": "string", "example": "B08N5WRWNW" }, "title": { "description": "Title of the primary product.", "type": "string", "example": "Echo Dot (4th Gen)" }, "image": { "description": "Cover image URL of the primary product.", "type": "string", "format": "uri", "example": "https:\/\/m.media-amazon.com\/images\/I\/example.jpg", "nullable": true }, "isParent": { "description": "`true` if the primary product is a parent ASIN (has child variations).", "type": "boolean", "example": true }, "variationsCount": { "description": "Number of child variations under the parent ASIN.", "type": "integer", "example": 3 }, "trackVariations": { "description": "Whether all ASIN variations are tracked together under the parent.", "type": "boolean", "example": false }, "productsCount": { "description": "Total number of products in this group (primary + related).", "type": "integer", "example": 2 }, "relatedProductsCount": { "description": "Number of non-primary products in this group.", "type": "integer", "example": 1 }, "phrasesCount": { "description": "Total number of tracked phrases.", "type": "integer", "example": 48 }, "top10Phrases": { "description": "Number of phrases ranked in organic top 10.", "type": "integer", "example": 5, "nullable": true }, "top50Phrases": { "description": "Number of phrases ranked in organic top 50.", "type": "integer", "example": 21, "nullable": true }, "top10SearchVolume": { "description": "Combined search volume of phrases ranked in organic top 10.", "type": "integer", "example": 85000, "nullable": true }, "top50SearchVolume": { "description": "Combined search volume of phrases ranked in organic top 50.", "type": "integer", "example": 200000, "nullable": true }, "top10SponsoredPhrases": { "description": "Number of phrases ranked in sponsored top 10.", "type": "integer", "example": 3, "nullable": true }, "top50SponsoredPhrases": { "description": "Number of phrases ranked in sponsored top 50.", "type": "integer", "example": 12, "nullable": true }, "top10SponsoredSearchVolume": { "description": "Combined search volume of phrases ranked in sponsored top 10.", "type": "integer", "example": 60000, "nullable": true }, "top50SponsoredSearchVolume": { "description": "Combined search volume of phrases ranked in sponsored top 50.", "type": "integer", "example": 150000, "nullable": true }, "tagsIds": { "description": "IDs of tags assigned to this group.", "type": "array", "items": { "type": "integer" }, "example": [ 1, 4 ] }, "createdAt": { "description": "When the group was created.", "type": "string", "format": "date-time", "example": "2024-03-10T12:00:00.000000Z" }, "miSegmentId": { "description": "Linked Market Intelligence segment ID, if any.", "type": "integer", "example": null, "nullable": true } }, "type": "object" }, "RtGroup": { "description": "Rank Tracker group returned after create \/ show.", "properties": { "id": { "description": "Unique identifier of the group.", "type": "integer", "example": 12 }, "accountId": { "description": "The ID of the account this group belongs to.", "type": "integer", "example": 3 }, "marketplace": { "$ref": "#\/components\/schemas\/RtMarketplace" }, "primaryProductId": { "description": "ID of the main product in this group.", "type": "integer", "example": 7 }, "phrasesCount": { "description": "Total number of keywords being tracked.", "type": "integer", "example": 48 }, "productsCount": { "description": "Total number of products in this group.", "type": "integer", "example": 2 }, "relatedProductsCount": { "description": "Number of non-primary products in this group.", "type": "integer", "example": 1 }, "suggestedPhrasesCount": { "description": "Number of pending AI keyword suggestions.", "type": "integer", "example": 5 }, "searchVolume": { "description": "Sum of search volumes of all tracked phrases.", "type": "integer", "example": 320000, "nullable": true }, "createdAt": { "description": "When the group was created.", "type": "string", "format": "date-time", "example": "2024-03-10T12:00:00.000000Z" }, "miSegmentId": { "description": "Linked Market Intelligence segment ID, if any.", "type": "integer", "example": null, "nullable": true } }, "type": "object" }, "HeatmapWidgetDay": { "description": "One data point in a heatmap summary widget series.", "properties": { "date": { "description": "Calendar date (YYYY-MM-DD).", "type": "string", "format": "date", "example": "2026-04-23" }, "value": { "description": "The metric value for this day. Type depends on the widget: `visibility` returns a float (0\u2013100), `average` and `amazonChoice` return an integer.", "type": "number", "example": 42.4 }, "complete": { "description": "`true` when all keywords in the set were scraped for this day. For today's date this may be `false` while scraping is still in progress.", "type": "boolean", "example": true }, "coverage": { "description": "Percentage of keywords already scraped for this day (0\u2013100). Always 100 for past dates.", "type": "integer", "example": 100 } }, "type": "object" }, "RtMarketplace": { "description": "Amazon marketplace supported by Rank Tracker.", "type": "string", "example": "US", "enum": [ "US", "CA", "MX", "DE", "ES", "FR", "IT", "UK" ] }, "RtPhrase": { "description": "A tracked keyword with current organic and sponsored rank positions for one product.", "properties": { "id": { "description": "Unique ID of this keyword within the group. Used to update tags, delete, or toggle boost.", "type": "integer", "example": 101 }, "dataId": { "description": "Use this ID with `GET \/rank-tracker\/groups\/{group}\/positions-chart-data\/{id}` to retrieve the rank history chart for this keyword\u2013product pair.", "type": "integer", "example": 205, "nullable": true }, "phrase": { "description": "The keyword text.", "type": "string", "example": "wireless earbuds" }, "isBoosted": { "description": "Whether boost (high-frequency tracking) is active for this phrase.", "type": "boolean", "example": false }, "remainingBoostTime": { "description": "Seconds remaining until boost expires. `null` when not boosted.", "type": "integer", "example": null, "nullable": true }, "organicAsin": { "description": "ASIN that holds the organic ranking position.", "type": "string", "example": "B08N5WRWNW", "nullable": true }, "organicPage": { "description": "Search results page where the organic position was found.", "type": "integer", "example": 1, "nullable": true }, "organicPosition": { "description": "Current organic rank position on the search results page.", "type": "integer", "example": 7, "nullable": true }, "organicPreviousPosition": { "description": "Organic rank position from the previous tracking snapshot.", "type": "integer", "example": 9, "nullable": true }, "sponsoredAsin": { "description": "ASIN that holds the sponsored (ad) ranking position.", "type": "string", "example": "B08N5WRWNW", "nullable": true }, "sponsoredPage": { "description": "Search results page where the sponsored position was found.", "type": "integer", "example": 1, "nullable": true }, "sponsoredPosition": { "description": "Current sponsored (ad) rank position on the search results page.", "type": "integer", "example": 3, "nullable": true }, "sponsoredPreviousPosition": { "description": "Sponsored rank position from the previous tracking snapshot.", "type": "integer", "example": 4, "nullable": true }, "resultsPerPage": { "description": "Number of search results shown per page for this keyword.", "type": "integer", "example": 60, "nullable": true }, "resultsNumber": { "description": "Total number of search results returned by Amazon for this keyword.", "type": "integer", "example": 2000, "nullable": true }, "realResultsNumber": { "description": "Actual number of results Amazon shows when browsing to the last page.", "type": "integer", "example": 1987, "nullable": true }, "isNew": { "description": "`true` if the phrase has never been tracked yet (no data collected).", "type": "boolean", "example": false }, "searchVolume": { "description": "Monthly search volume for this keyword.", "type": "integer", "example": 45000, "nullable": true }, "amazonChoiceAsin": { "description": "ASIN carrying the \"Amazon's Choice\" badge for this keyword, if any.", "type": "string", "example": null, "nullable": true }, "cpc": { "description": "Average cost-per-click for ads on this keyword, in cents (divide by 100 to get the value in the marketplace currency).", "type": "integer", "example": 112, "nullable": true }, "cpcMin": { "description": "Minimum CPC estimate for this keyword, in cents (divide by 100 to get the value in the marketplace currency).", "type": "integer", "example": 80, "nullable": true }, "cpcMax": { "description": "Maximum CPC estimate for this keyword, in cents (divide by 100 to get the value in the marketplace currency).", "type": "integer", "example": 145, "nullable": true }, "abaSearchFrequencyRank": { "description": "Amazon Brand Analytics rank. Available only with an active BA token.", "type": "integer", "example": null, "nullable": true }, "abaTotalClickShare": { "description": "Total click share of top 3 ASINs (%). Available only with an active BA token.", "type": "number", "format": "float", "example": null, "nullable": true }, "abaTotalConvShare": { "description": "Total conversion share of top 3 ASINs (%). Available only with an active BA token.", "type": "number", "format": "float", "example": null, "nullable": true }, "updatedAt": { "description": "When ranking data was last collected. `null` if never tracked yet.", "type": "string", "example": "2026-04-24 11:55:12", "nullable": true }, "createdAt": { "description": "When this keyword was added to the group.", "type": "string", "example": "2026-04-24 12:05:13" }, "tagsIds": { "description": "IDs of tags assigned to this keyword.", "type": "array", "items": { "type": "integer" }, "example": [] }, "trend": { "description": "Linear position trend over the heatmap date range. Positive = rank improved; negative = rank worsened. `null` when heatmap mode is off or fewer than 2 data points exist in the range.", "type": "integer", "example": null, "nullable": true }, "r_2026-04-23": { "description": "Example heatmap field. When `heatmap=true`, one such field is returned per calendar day in the requested range, with keys following the pattern `r_YYYY-MM-DD`.", "properties": { "date": { "description": "The calendar date in YYYY-MM-DD format.", "type": "string", "format": "date", "example": "2026-04-23" }, "rank": { "description": "Position for this day. `null` = no data collected. `0` = product not found in results.", "type": "integer", "example": 7, "nullable": true }, "amazon_choice": { "description": "Whether the tracked product held the \"Amazon's Choice\" badge on this keyword that day.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" }, "RtProduct": { "description": "A product tracked inside a Rank Tracker group.", "properties": { "id": { "description": "Unique identifier of the product within the group.", "type": "integer", "example": 7 }, "asin": { "description": "Amazon product identifier.", "type": "string", "example": "B08N5WRWNW" }, "title": { "description": "Product title fetched from Amazon.", "type": "string", "example": "Echo Dot (4th Gen)" }, "image": { "description": "Cover image URL fetched from Amazon.", "type": "string", "format": "uri", "example": "https:\/\/m.media-amazon.com\/images\/I\/example.jpg", "nullable": true }, "isParent": { "description": "`true` if this is a parent ASIN (has child variations).", "type": "boolean", "example": false }, "variationsCount": { "description": "Number of child variations under the parent ASIN.", "type": "integer", "example": 3 }, "trackVariations": { "description": "Whether all ASIN variations are tracked together as a parent.", "type": "boolean", "example": false }, "createdAt": { "description": "When the product was added to the group.", "type": "string", "format": "date-time", "example": "2024-03-10T12:00:00.000000Z" }, "detailsUpdatedAt": { "description": "When the product title and image were last refreshed from Amazon.", "type": "string", "format": "date-time", "example": "2024-03-11T08:00:00.000000Z", "nullable": true } }, "type": "object" }, "RtProductWithStats": { "description": "Product with aggregated ranking statistics for all tracked keywords in its group.", "properties": { "id": { "description": "Unique identifier of the product within the group.", "type": "integer", "example": 7 }, "asin": { "description": "Amazon product identifier.", "type": "string", "example": "B08N5WRWNW" }, "title": { "description": "Product title fetched from Amazon.", "type": "string", "example": "Echo Dot (4th Gen)" }, "image": { "description": "Cover image URL fetched from Amazon.", "type": "string", "format": "uri", "example": "https:\/\/m.media-amazon.com\/images\/I\/example.jpg", "nullable": true }, "isParent": { "description": "`true` if this is a parent ASIN (has child variations).", "type": "boolean", "example": false }, "variationsCount": { "description": "Number of child variations under the parent ASIN.", "type": "integer", "example": 3 }, "trackVariations": { "description": "Whether all ASIN variations are tracked together under the parent.", "type": "boolean", "example": false }, "avgOrganicRank": { "description": "Average organic rank across all ranked keywords (floor-rounded).", "type": "integer", "example": 14, "nullable": true }, "avgSponsoredRank": { "description": "Average sponsored rank across all ranked keywords (floor-rounded).", "type": "integer", "example": 8, "nullable": true }, "rankingOrganicKeywords": { "description": "Number of keywords for which this product has an organic position.", "type": "integer", "example": 22 }, "rankingSponsoredKeywords": { "description": "Number of keywords for which this product has a sponsored position.", "type": "integer", "example": 10 }, "rankedOrganicSv": { "description": "Combined search volume of all organically-ranked keywords.", "type": "integer", "example": 180000, "nullable": true }, "rankedSponsoredSv": { "description": "Combined search volume of all sponsored-ranked keywords.", "type": "integer", "example": 90000, "nullable": true }, "tagsIds": { "description": "IDs of tags assigned to this product.", "type": "array", "items": { "type": "integer" }, "example": [ 2 ] }, "createdAt": { "description": "When the product was added to the group.", "type": "string", "format": "date-time", "example": "2024-03-10T12:00:00.000000Z" }, "detailsUpdatedAt": { "description": "When the product title and image were last refreshed from Amazon.", "type": "string", "format": "date-time", "example": "2024-03-11T08:00:00.000000Z", "nullable": true } }, "type": "object" }, "RtSettings": { "description": "Per-user Rank Tracker display settings.", "properties": { "showHeatmap": { "description": "Whether the heatmap view is enabled by default.", "type": "boolean", "example": true, "nullable": true }, "heatmapPalette": { "description": "Color palette used for the heatmap.", "type": "string", "example": "green", "nullable": true }, "keywordsHeatmapColumnState": { "description": "Serialised column visibility\/order state for the heatmap view.", "type": "string", "example": null, "nullable": true }, "keywordsClassicColumnState": { "description": "Serialised column visibility\/order state for the classic view.", "type": "string", "example": null, "nullable": true } }, "type": "object" }, "RtSuggestedPhrase": { "description": "A keyword suggested by SoldScope for tracking in a group.", "properties": { "suggestionId": { "description": "Unique ID of this suggestion (use when applying or ignoring).", "type": "integer", "example": 55 }, "id": { "description": "Keyword database ID.", "type": "integer", "example": 1024 }, "keyword": { "description": "The suggested keyword text.", "type": "string", "example": "bluetooth speaker waterproof" }, "searchVolume": { "description": "Monthly search volume for this keyword.", "type": "integer", "example": 28000, "nullable": true }, "resultsNumber": { "description": "Total number of search results returned by Amazon for this keyword.", "type": "integer", "example": 3335, "nullable": true }, "opportunityScore": { "description": "SoldScope opportunity score for this keyword.", "type": "integer", "example": 79, "nullable": true }, "abaSearchFrequencyRank": { "description": "Amazon Brand Analytics search frequency rank. Available only with an active BA token.", "type": "integer", "example": null, "nullable": true }, "abaTotalClickShare": { "description": "Total click share of top 3 ASINs (%). Available only with an active BA token.", "type": "number", "format": "float", "example": null, "nullable": true }, "abaTotalConversionShare": { "description": "Total conversion share of top 3 ASINs (%). Available only with an active BA token.", "type": "number", "format": "float", "example": null, "nullable": true }, "createdAt": { "description": "When this keyword was added to the SoldScope database.", "type": "string", "example": "2025-03-12 09:49:22" } }, "type": "object" }, "RtTag": { "description": "A label used to organise Rank Tracker groups, products, and phrases.", "properties": { "id": { "description": "Unique identifier of the tag.", "type": "integer", "example": 1 }, "title": { "description": "Tag label displayed in the UI.", "type": "string", "example": "Best sellers" }, "color": { "description": "Hex color code.", "type": "string", "example": "#FF5733" }, "groupsCount": { "description": "Number of groups using this tag.", "type": "integer", "example": 3, "nullable": true }, "productsCount": { "description": "Number of products using this tag.", "type": "integer", "example": 5, "nullable": true }, "phrasesCount": { "description": "Number of phrases using this tag.", "type": "integer", "example": 12, "nullable": true } }, "type": "object" }, "SimplePaginationMeta": { "description": "Pagination metadata for endpoints that use manual (non-Laravel) pagination.", "properties": { "current_page": { "type": "integer", "example": 1 }, "from": { "type": "integer", "example": 1, "nullable": true }, "last_page": { "type": "integer", "example": 5 }, "per_page": { "type": "integer", "example": 25 }, "to": { "type": "integer", "example": 25, "nullable": true }, "total": { "type": "integer", "example": 100 } }, "type": "object" } }, "responses": { "Unauthenticated": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/Error" } ] }, "example": { "message": "Unauthenticated." } } } }, "Forbidden": { "description": "Forbidden", "content": { "application\/json": { "schema": { "allOf": [ { "$ref": "#\/components\/schemas\/Error" } ] }, "example": { "message": "Forbidden." } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Personal Access Token. Generate one in your account settings under API Access.", "bearerFormat": "PersonalAccessToken", "scheme": "bearer" } } }, "tags": [ { "name": "Auth", "description": "## Authentication\n\nAll API requests require a **Personal Access Token** passed as a Bearer token\nin the `Authorization` header:\n\n```\nAuthorization: Bearer \n```\n\n**How to get a token:**\n\n1. Open [API Access](https:\/\/app.soldscope.com\/api-access) in your SoldScope account.\n2. Click **Create token**, give it a name, and copy the token \u2014 it is shown only once.\n3. Use that token in every API request.\n\n---" }, { "name": "Keyword Research", "description": "## Keyword Research workflow\n\nThere are three search types. The response always contains a `searchType` field that tells you which type was created.\n\n---\n\n### Single-ASIN search (`searchType: 0`) \u2014 synchronous\n\nThe search runs immediately and returns `status: 2` (completed) right away. No polling needed.\n\n1. `POST \/keyword-research\/searches\/asin\/single` with `{ \"asin\": \"B08N5WRWNW\", \"marketplace\": \"US\" }`\n2. `GET \/keyword-research\/searches\/asin\/single\/{id}` \u2014 fetch keyword results.\n\n---\n\n### Multi-ASIN search (`searchType: 1`) \u2014 asynchronous\n\nCompares 2\u201310 ASINs. The search runs in the background \u2014 poll for progress, then fetch results.\n\n1. `POST \/keyword-research\/searches\/asin\/multi` with `{ \"asins\": [\"B08N5WRWNW\", \"B07XJ8C8F5\"], \"marketplace\": \"US\" }` \u2014\n returns `status: 0` (started).\n2. `GET \/keyword-research\/searches\/{id}\/progress` \u2014 poll until `searchStatus: 2` (completed) or `searchStatus: 13` (\n failed). Stop polling on either.\n3. `GET \/keyword-research\/searches\/multi\/{id}` \u2014 fetch results.\n\n---\n\n### Keyword search (`searchType: 2`) \u2014 asynchronous\n\nSearches by a single keyword phrase. The search runs in the background. Results are returned in the same format as\nmulti-ASIN.\n\n1. `POST \/keyword-research\/searches\/keyword\/single` with `{ \"keyword\": \"dog toys\", \"marketplace\": \"US\" }` \u2014 returns\n `status: 0` (started). Accepts exactly one keyword phrase.\n2. `GET \/keyword-research\/searches\/{id}\/progress` \u2014 poll until `searchStatus: 2` (completed) or `searchStatus: 13` (\n failed).\n3. `GET \/keyword-research\/searches\/multi\/{id}` \u2014 fetch results.\n\n---\n\n### Search statuses\n\n| Status | Meaning |\n|--------|----------------------------------------------|\n| 0 | Started \u2014 search is running |\n| 2 | Completed \u2014 results are ready |\n| 13 | Failed \u2014 keyword or ASIN produced no results |" }, { "name": "Product Research", "description": "## Product Research workflow\n\nUse Product Research to discover Amazon products that match specific criteria: niche, price range, BSR, sales volume,\nfulfillment type, and more.\n\n---\n\n### Basic product search\n\n1. `GET \/product-research\/products?marketplace=US&filters[bsr][max]=5000&filters[price][min]=20`\n \u2014 run a new search. Returns a paginated list of matching products and a `meta.searchId`. Each unique search consumes\n one search credit.\n2. Paginate through results using `page` and `perPage`.\n Pass `searchId` on subsequent page requests to continue the same search without consuming another credit.\n3. `GET \/product-research\/products\/{id}\/variations?searchId={searchId}`\n \u2014 fetch variations for a product (only when `PrProduct.variations` is `true`).\n\n---\n\n### Filtering by category\n\nCategories let you scope a search to a specific Amazon browse node. The workflow mirrors how the app's category picker\nworks:\n\n**Option A \u2014 Search by keyword (interactive picker)**\n\n1. `GET \/product-research\/categories-tree?marketplace=US&searchQuery=Electronics`\n \u2014 returns a nested tree of matching categories.\n2. Pick the desired nodes, collect their `nodeId` values.\n3. Pass them as `filters[categories][]=7141124011&filters[categories][]=1055398` to `GET \/product-research\/products`.\n\n**Option B \u2014 Browse root categories then drill down**\n\n1. `GET \/product-research\/categories?marketplace=US&level=2`\n \u2014 returns all top-level categories (level 2 = root nodes available in Product Research).\n2. `GET \/product-research\/categories\/{id}\/children`\n \u2014 use the **`id`** field (not `nodeId`) to fetch direct subcategories.\n Repeat to traverse the tree as deep as needed.\n3. Collect `nodeId` values and pass them to `filters[categories][]`.\n\n> **`id` vs `nodeId`:** `id` is the internal database integer \u2014 used only in the `\/{id}\/children` path parameter.\n`nodeId` is the Amazon node identifier \u2014 this is what goes into `filters[categories][]`.\n\n---\n\n### Variation cache\n\nVariations are served from an in-memory cache populated during the original search (TTL: **1 hour**).\nIf the cache has expired, `GET \/product-research\/products\/{id}\/variations` returns `404` \u2014\nre-run the search via `GET \/product-research\/products?searchId={id}` to refresh it.\n\n---\n\n### Browsing past searches\n\n`GET \/product-research\/searches` lists all past searches for your account.\nUse the returned `id` as `searchId` to replay any past search without consuming a search credit." }, { "name": "Rank Tracker", "description": "# Rank Tracker\n\nMonitor keyword rankings for your Amazon products across organic and sponsored search results.\n\n---\n\n## Concepts\n\n**Group** \u2014 the central entity in Rank Tracker. Each group tracks one primary product (ASIN) on a specific marketplace\nand holds a list of keywords to monitor.\n\n**Product** \u2014 an ASIN attached to a group. The first product becomes the primary product. Add more products to compare\nranking performance across the same keyword set side by side.\n\n**Phrase** \u2014 a keyword being tracked inside a group. Each phrase stores the current organic and sponsored rank for every\nproduct in the group, along with search volume, CPC, ABA data (when available), and full position history.\n\n**Tag** \u2014 a label (with a custom color) used to organise groups, products, and phrases for filtering.\n\n**Boost** \u2014 a flag on a phrase that signals SoldScope to collect position data more frequently for that keyword.\nRequires search volume \u2265 500.\n\n**Suggested phrase** \u2014 a keyword suggested by SoldScope based on competitor analysis. Suggested phrases can be reviewed\nand applied to (or ignored from) a group's keyword list.\n\n---\n\n## Typical workflow\n\n### 1. Create a group\n\nCall [`POST \/rank-tracker\/groups`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/groups) with\nthe\nprimary ASIN, marketplace, and an initial list of keywords:\n\n```json\n{\n \"asin\": \"B08N5WRWNW\",\n \"marketplace\": \"US\",\n \"trackAllVariations\": false,\n \"phrases\": [\n \"wireless earbuds\",\n \"bluetooth headphones sport\"\n ]\n}\n```\n\n> If `trackAllVariations` is `true` and the ASIN is a child variation, SoldScope automatically resolves it to the parent\n> ASIN and tracks all child variations under the group.\n\nThe response contains the new group's `id` \u2014 save it, you will need it for all subsequent calls.\n\n---\n\n### 2. Browse groups\n\n[`GET \/rank-tracker\/groups`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups) returns a\npaginated list of all groups for the selected account, each enriched with aggregated keyword stats (top-10\/50 keywords\nby organic and sponsored rank, total search volume in those positions).\n\nFilter by `marketplace`, `search` (ASIN or title), or `tags[]` to narrow the list.\n\n---\n\n### 3. Manage products\n\nA group can track multiple products against the same keyword set.\n\n**List products:**\n[\n`GET \/rank-tracker\/groups\/{groupId}\/products`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/products)\n\n**List products with aggregated ranking stats:**\n[\n`GET \/rank-tracker\/groups\/{groupId}\/products-with-stats`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/products-with-stats)\nreturns average organic\/sponsored rank, number of ranking keywords, and total ranked search volume per product.\n\n**Add products:**\n[\n`POST \/rank-tracker\/groups\/{groupId}\/products`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/groups\/{groupId}\/products)\n\n```json\n{\n \"products\": [\n {\n \"asin\": \"B07XJ8C8F5\",\n \"trackAllVariations\": false\n },\n {\n \"asin\": \"B09B8YWXDF\",\n \"trackAllVariations\": false\n }\n ]\n}\n```\n\n**Remove products:**\n[\n`DELETE \/rank-tracker\/groups\/{groupId}\/products`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/DELETE\/rank-tracker\/groups\/{groupId}\/products)\nwith a `products` array of product IDs in the request body.\n\n---\n\n### 4. Manage keywords\n\n**Read the current keyword list:**\n[\n`GET \/rank-tracker\/groups\/{groupId}\/phrases-list`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/phrases-list)\nreturns the raw list of tracked keywords for a group.\n\n**Replace the entire keyword list:**\n[\n`POST \/rank-tracker\/groups\/{groupId}\/phrases-list`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/groups\/{groupId}\/phrases-list)\nreplaces all tracked keywords with the supplied list. Use this for bulk updates.\n\n```json\n{\n \"phrases\": [\n \"wireless earbuds\",\n \"sport bluetooth earphones\",\n \"running headphones\"\n ]\n}\n```\n\n**Delete keywords:**\n[\n`DELETE \/rank-tracker\/groups\/{groupId}\/phrases`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/DELETE\/rank-tracker\/groups\/{groupId}\/phrases)\nwith a `phrases` array of keyword IDs in the request body.\n\n#### Suggested keywords\n\nSoldScope can automatically discover new keywords for a group based on competitor data and AI analysis.\n\n[\n`GET \/rank-tracker\/groups\/{groupId}\/suggested-phrases`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/suggested-phrases)\nreturns a paginated list of pending keyword suggestions for a group.\n\n**Apply suggestions** (add them to the keyword list):\n[\n`POST \/rank-tracker\/groups\/{groupId}\/suggested-phrases`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/groups\/{groupId}\/suggested-phrases)\n\n```json\n{\n \"suggestionsIds\": [\n 55,\n 56\n ]\n}\n```\n\n**Ignore suggestions** (dismiss them permanently):\n[\n`DELETE \/rank-tracker\/groups\/{groupId}\/suggested-phrases`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/DELETE\/rank-tracker\/groups\/{groupId}\/suggested-phrases)\n\n```json\n{\n \"suggestionsIds\": [\n 57,\n 58\n ]\n}\n```\n\n**On-demand AI keyword suggestions:**\n[\n`GET \/rank-tracker\/suggested-keywords`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/suggested-keywords)\nreturns up to 300 keyword suggestions generated by SoldScope AI.\n\nSupply either:\n\n- `groupId` \u2014 to base suggestions on an existing group's products and current keywords.\n- `asins[]` + `marketplace` \u2014 to get suggestions for any set of ASINs without a group.\n\n---\n\n### 5. View keyword rankings\n\n[\n`GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases\/v2`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases\/v2)\nreturns the current ranking data for every keyword in the group for a specific product.\n\nEach phrase in the response includes:\n\n- `id` \u2014 the unique keyword ID within this group (used for deleting, tagging, or toggling boost).\n- `dataId` \u2014 the phrase\u2013product record ID (used to fetch position history).\n- `organicPosition`, `organicPage`, `organicAsin`, `organicPreviousPosition` \u2014 current and previous organic rank data.\n- `sponsoredPosition`, `sponsoredPage`, `sponsoredAsin`, `sponsoredPreviousPosition` \u2014 current and previous sponsored\n rank data.\n- `searchVolume`, `cpc`, `cpcMin`, `cpcMax` \u2014 market data.\n- `abaSearchFrequencyRank`, `abaTotalClickShare`, `abaTotalConvShare` \u2014 Amazon Brand Analytics data, when available.\n\n---\n\n### 6. View position history\n\n[\n`GET \/rank-tracker\/groups\/{groupId}\/positions-chart-data\/{id}`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/positions-chart-data\/{id})\nreturns the full rank history for a specific keyword\u2013product pair, suitable for rendering a chart.\n\nThe `{id}` path parameter is the `dataId` field returned by\n[\n`GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases\/v2`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases\/v2).\n\nPass `type=2` to retrieve sponsored rank history instead of organic (default `type=1`).\n\n---\n\n## Boost\n\nBoosting a keyword signals SoldScope to collect rank data more frequently for that phrase.\n\n**Requirements:** search volume \u2265 500.\n\nToggle boost on or off:\n[\n`POST \/rank-tracker\/groups\/{groupId}\/phrases\/{phraseId}\/toggle-boost-state`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/groups\/{groupId}\/phrases\/{phraseId}\/toggle-boost-state)\n\n```json\n{\n \"isBoosted\": true\n}\n```\n\n---\n\n## Tags\n\nTags let you label and filter groups, products, and keywords. Tags are account-wide \u2014 the same tag can be applied across\nmultiple groups, products, and phrases.\n\n**List all tags:**\n[`GET \/rank-tracker\/tags`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/tags)\n\n**Create a tag:**\n[`POST \/rank-tracker\/tags`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/tags)\n\n```json\n{\n \"title\": \"High priority\",\n \"color\": \"#FF5733\"\n}\n```\n\n**Rename \/ recolor a tag:**\n[`PUT \/rank-tracker\/tags\/{tag}`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/PUT\/rank-tracker\/tags\/{tag})\n\n**Delete a tag:**\n[`DELETE \/rank-tracker\/tags\/{tag}`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/DELETE\/rank-tracker\/tags\/{tag})\n\u2014 the tag is automatically detached from all groups, products, and phrases.\n\n### Assigning tags\n\n| Target | Endpoint |\n|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Group | [`POST \/rank-tracker\/groups\/{groupId}\/tags`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/groups\/{groupId}\/tags) |\n| Product | [`POST \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/tags`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/tags) |\n| Keyword | [`POST \/rank-tracker\/groups\/{groupId}\/phrases\/{phraseId}\/tags`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/groups\/{groupId}\/phrases\/{phraseId}\/tags) |\n\nAll three endpoints accept the same body and **replace** the current tag set:\n\n```json\n{\n \"tagsIds\": [\n 1,\n 3\n ]\n}\n```\n\nPass an empty array to remove all tags from the entity.\n\n---\n\n## Export\n\nTwo export modes are available in Rank Tracker:\n\n- **Simple export** \u2014 up to 92 days of daily organic positions for one product, returned synchronously in a single API\n call. No file download required.\n- **Async export** \u2014 full position history (organic + sponsored) over any date range, exported to a CSV\/JSON file and\n processed in the background.\n\n---\n\n### Simple export (heatmap mode)\n\nThe simplest way to extract historical rank data is to use the existing keyword positions endpoint in **heatmap mode**.\nInstead of a file, the data comes back as regular JSON \u2014 one object per keyword, with a `r_YYYY-MM-DD` field for each\nday in the requested range.\n\nCall\n[\n`GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases\/v2`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases\/v2)\nwith the following parameters:\n\n```\nheatmap=true\nheatmapDateFrom=2026-02-01\nheatmapDateTo=2026-04-28\nperPage=10000\n```\n\n> Maximum date range is **92 days**. Set `perPage` high enough to cover the entire keyword list in one page.\n\nEach item in `data[]` is a standard `RtPhrase` object extended with one extra field per calendar day.\nEach `r_YYYY-MM-DD` field is an object with three keys:\n\n| Key | Type | Description |\n|-----------------|-----------------|------------------------------------------------------------------------------------------------|\n| `date` | string | The calendar date in `YYYY-MM-DD` format. |\n| `rank` | integer \\| null | Organic position for that day. `null` = no data collected. `0` = product not found in results. |\n| `amazon_choice` | boolean | Whether the tracked product held the \"Amazon's Choice\" badge on this keyword on that day. |\n\n```json\n{\n \"id\": 101,\n \"phrase\": \"wireless earbuds\",\n \"searchVolume\": 45000,\n \"organicPosition\": 7,\n \"r_2026-02-01\": {\n \"date\": \"2026-02-01\",\n \"rank\": 12,\n \"amazon_choice\": false\n },\n \"r_2026-02-02\": {\n \"date\": \"2026-02-02\",\n \"rank\": 11,\n \"amazon_choice\": true\n },\n \"r_2026-02-03\": {\n \"date\": \"2026-02-03\",\n \"rank\": null,\n \"amazon_choice\": false\n },\n \"r_2026-04-28\": {\n \"date\": \"2026-04-28\",\n \"rank\": 7,\n \"amazon_choice\": false\n }\n}\n```\n\nThe `rank` field in each heatmap object reflects the position type controlled by `resultsType`: organic (default) or\nsponsored.\nBoth types are available in synchronous heatmap mode; the async export is only needed for full multi-product history\nover longer periods.\n\n**When to use this approach:**\n\n- You need daily rank data per keyword for a single product over up to 3 months.\n- You want a simple synchronous response without polling or file downloads.\n- You are building a dashboard or chart and want to page through keywords incrementally.\n\n---\n\n### Heatmap summary widgets\n\nInstead of fetching per-keyword daily data, you can get pre-aggregated daily metrics in a single call:\n\n[\n`GET \/rank-tracker\/groups\/{groupId}\/products\/{productId}\/heatmap-widgets`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/heatmap-widgets)\n\nPass the same `heatmapDateFrom`, `heatmapDateTo`, `resultsType`, `search`, and `onlyBoosted` parameters as the phrases\nendpoint. The response contains four arrays sorted newest-to-oldest:\n\n| Widget | `value` type | Description |\n|----------------|--------------|---------------------------------------------------------------------------------------------------------------------------|\n| `visibility` | float 0\u2013100 | Search-volume-weighted rank score. Each keyword is weighted by \u221a(searchVolume) \u00d7 rankWeight (CTR model). Higher = better. |\n| `average` | integer | Average rank across all keywords. Keywords not found in results count as position 306. Lower = better. |\n| `amazonChoice` | integer | Number of keywords for which the tracked product held the \"Amazon's Choice\" badge. |\n| `distribution` | object | Keyword count per rank bucket: `1-3`, `4-10`, `11-50`, `51-100`, `100+`, `notTracked`. |\n\nEach entry in `visibility`, `average`, and `amazonChoice` also carries:\n\n- `complete` \u2014 `true` when all keywords have been scraped for that day (`false` for today while scraping is in\n progress).\n- `coverage` \u2014 percentage of keywords scraped (0\u2013100). Always `100` for past dates.\n\n---\n\n### Async export (historical keyword positions)\n\nThe async export generates a CSV or JSON file with historical keyword position data.\nBecause the data volume can be large, the export is processed in the background.\n\nThe `granularity` field controls row density:\n\n| Value | Default | Row density | `Date` column format |\n|---------|---------|--------------------------------------|----------------------|\n| `raw` | yes | One row per keyword per snapshot | `YYYY-MM-DD HH:MM` |\n| `daily` | | One row per keyword per calendar day | `YYYY-MM-DD` |\n\nIn `daily` mode, positions are aggregated using the **median** of all snapshots for that day.\n\n**Columns in the output file:**\n\n| Column | Description |\n|---------------------------|-------------------------------------------------------------------------|\n| `#` | Row number |\n| `Date` | Snapshot timestamp or calendar date, depending on `granularity` |\n| `Parent ASIN` | ASIN of the tracked product |\n| `Keyword` | Keyword phrase |\n| `Amazon Choice` | `true` if the product held the \"Amazon's Choice\" badge at this snapshot |\n| `Organic Position` | Organic rank |\n| `Organic ASIN` | ASIN that held the organic position |\n| `Sponsored Position` | Sponsored rank |\n| `Sponsored ASIN` | ASIN that held the sponsored position |\n| `Search Volume (7 days)` | Weekly search volume closest to the snapshot date |\n| `Search Volume (30 days)` | Monthly search volume closest to the snapshot date |\n\n#### Workflow\n\n**Step 1 \u2014 start the export**\n\nCall [`POST \/rank-tracker\/export`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/POST\/rank-tracker\/export):\n\n```json\n{\n \"groupId\": 12,\n \"dateFrom\": \"2026-01-01\",\n \"dateTo\": \"2026-04-28\",\n \"format\": \"csv\",\n \"granularity\": \"daily\"\n}\n```\n\nThe response is returned immediately with `status: 0` (pending):\n\n```json\n{\n \"data\": {\n \"id\": 42,\n \"groupId\": 12,\n \"status\": 0,\n \"filename\": null,\n \"format\": \"csv\",\n \"granularity\": \"daily\",\n \"dateFrom\": \"2026-01-01\",\n \"dateTo\": \"2026-04-28\",\n \"products\": null,\n \"createdAt\": \"2026-04-28T10:00:00.000000Z\",\n \"updatedAt\": null\n }\n}\n```\n\nSave the `id` \u2014 you will need it to poll for completion.\n\n**Step 2 \u2014 poll until ready**\n\nCall [`GET \/rank-tracker\/export\/{id}`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/export\/{id})\nevery few seconds. The `status` field indicates progress:\n\n| Value | Meaning |\n|-------|--------------------------------------------------|\n| `0` | Pending \u2014 still processing |\n| `1` | Completed \u2014 `filename` contains the download URL |\n| `2` | Failed |\n\n**Step 3 \u2014 download the file**\n\nWhen `status` is `1`, the `filename` field contains a **pre-signed S3 URL valid for 15 minutes**.\nDownload the file immediately \u2014 the URL expires.\n\n#### Filtering exported keywords\n\nBy default, all products and all keywords in the group are exported. You can narrow the scope:\n\n**Specific products** \u2014 pass an array of ASINs:\n\n```json\n{\n \"products\": [\n \"B08N5WRWNW\"\n ]\n}\n```\n\n**Specific keywords** \u2014 pass an array of keyword IDs (the `id` field from\n[\n`GET ...\/phrases\/v2`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/GET\/rank-tracker\/groups\/{groupId}\/products\/{productId}\/phrases\/v2)):\n\n```json\n{\n \"keywords\": [\n 101,\n 102,\n 103\n ]\n}\n```\n\n**Active table filters** \u2014 pass the same filters that are applied in the keywords table. Takes precedence over\n`keywords` when provided:\n\n```json\n{\n \"filters\": {\n \"search\": \"bluetooth\",\n \"tags\": [\n 1,\n 3\n ],\n \"boosts\": true\n }\n}\n```\n\n`tags` uses AND logic \u2014 keywords must have **all** listed tags.\n\n---\n\n## Deleting groups\n\n[`DELETE \/rank-tracker\/groups`](https:\/\/www.soldscope.com\/api-docs#tag\/rank-tracker\/DELETE\/rank-tracker\/groups)\nwith a `groups` array of group IDs in the request body." } ] }