Amazon Rank Tracking API
Track keyword positions
Track where an ASIN stands in Amazon search for a keyword, checked every day.
https://api.screamingdata.dev/v1/amazon/rank_tracking/add- Authentication
- API key (HTTP Basic)
- Cost
- $0.0040 per check
List price · volume rates on request
- Body
- Array of up to 100 tasks
Overview
Starts tracking where each ASIN stands in Amazon search for a keyword on a marketplace. Every tracked keyword is checked once a day in Amazon's default search (all departments); the first check follows within minutes of adding it. Read the positions with rank_tracking/history (every check) or rank_tracking/daily (by day).
A listing of one of the product's variants or other editions counts as the product: matched_asin says which listing was found. Positions count organic results only; sponsored placements are left out.
Adding the same ASIN, marketplace and keyword again changes nothing and does not create a duplicate. Letter case and repeated spaces do not make another keyword.
Adding is free; every check delivered to a tracked keyword is charged at the rank tracking rate. If your balance cannot cover a check, your tracked keywords switch to paused_balance and resume automatically once balance is added. A keyword added while your balance is below that rate, or while your tracked keywords are paused, starts as paused_balance.
An account can track up to 2,000 keywords; beyond that the task fails with 40000. A keyword whose product is not found for 30 days in a row stops being tracked; add it again to resume.
Cost
Request
POST /v1/amazon/rank_tracking/add with Content-Type: application/json.
Body fields
The request body is a JSON array of 1–100 task objects. Each object has these fields:
asinASIN of the product. Case-insensitive; must be 10 letters or digits after uppercasing.
- Pattern
^[A-Z0-9]{10}$ - Example
B0EXAMPLE1
marketplaceMarketplace code. The aliases us and usa (for com) and gb (for uk) are also accepted. See Marketplaces.
- Allowed
comukdefresitnlcaaujpmxin - Example
com
keywordThe search term, up to 200 characters. It is kept as you sent it (trimmed); letter case and repeated spaces do not make another keyword, so Wireless Earbuds and wireless earbuds are one search.
- Max length200 characters
- Example
wireless earbuds
Request example
The examples read your credentials from the API_LOGIN and API_KEY environment variables.
curl --request POST \
--url "https://api.screamingdata.dev/ v1/ amazon/ rank_tracking/ add" \
--user "$API_LOGIN:$API_KEY" \
--header "Content-Type: application/json" \
--data '[
{
"asin": "B0EXAMPLE1",
"marketplace": "com",
"keyword": "wireless earbuds"
},
{
"asin": "B0EXAMPLE1",
"marketplace": "com",
"keyword": "noise cancelling headphones"
}
]'import os
import requests
response = requests.post(
"https://api.screamingdata.dev/ v1/ amazon/ rank_tracking/ add",
auth=(os.environ["API_LOGIN"], os.environ["API_KEY"]),
json=[
{
"asin": "B0EXAMPLE1",
"marketplace": "com",
"keyword": "wireless earbuds",
},
{
"asin": "B0EXAMPLE1",
"marketplace": "com",
"keyword": "noise cancelling headphones",
},
],
timeout=30,
)
data = response.json()
print(data["status_code"], data["status_message"], "cost:", data["cost"])
for task in data["tasks"]:
print(task["id"], task["status_code"], task["status_message"])const auth = Buffer.from(`${process.env.API_LOGIN}:${process.env.API_KEY}`).toString("base64");
const response = await fetch("https://api.screamingdata.dev/ v1/ amazon/ rank_tracking/ add", {
method: "POST",
headers: {
Authorization: `Basic ${auth}`,
"Content-Type": "application/json",
},
body: JSON.stringify([
{
asin: "B0EXAMPLE1",
marketplace: "com",
keyword: "wireless earbuds",
},
{
asin: "B0EXAMPLE1",
marketplace: "com",
keyword: "noise cancelling headphones",
},
]),
});
const data = await response.json();
console.log(data.status_code, data.status_message, "cost:", data.cost);
for (const task of data.tasks) {
console.log(task.id, task.status_code, task.status_message);
}Response
HTTP 200. The body is the standard response envelope; check status_code at the top level and in every task.
{
"version": "1.0.0",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0262 sec.",
"cost": 0,
"tasks_count": 2,
"tasks_error": 0,
"tasks": [
{
"id": "10030814-5c2e-4a1b-9d3f-7e8a2b6c4d10",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0049 sec.",
"cost": 0,
"result_count": 1,
"path": [
"v1",
"amazon",
"rank_tracking",
"add"
],
"data": {
"api": "amazon",
"function": "rank_tracking",
"asin": "B0EXAMPLE1",
"marketplace": "com",
"keyword": "wireless earbuds"
},
"result": [
{
"id": 5120,
"asin": "B0EXAMPLE1",
"marketplace": "com",
"keyword": "wireless earbuds",
"status": "active",
"created_at": "2026-10-03T08:14:20Z",
"last_checked_at": null,
"next_check_at": "2026-10-03T08:14:20Z"
}
]
},
{
"id": "10030814-8b1d-4e6f-a2c7-3d9e5f1a0b29",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0049 sec.",
"cost": 0,
"result_count": 1,
"path": [
"v1",
"amazon",
"rank_tracking",
"add"
],
"data": {
"api": "amazon",
"function": "rank_tracking",
"asin": "B0EXAMPLE1",
"marketplace": "com",
"keyword": "noise cancelling headphones"
},
"result": [
{
"id": 5121,
"asin": "B0EXAMPLE1",
"marketplace": "com",
"keyword": "noise cancelling headphones",
"status": "active",
"created_at": "2026-10-03T08:14:20Z",
"last_checked_at": null,
"next_check_at": "2026-10-03T08:14:20Z"
}
]
}
]
}Result fields
Each element of tasks[].result is a tracked keyword. One ASIN tracked for one keyword on one marketplace. rank_tracking/add returns it without latest.
idTracking id. Use it with rank_tracking/delete.
asinTracked ASIN.
marketplaceMarketplace code.
keywordThe keyword as you sent it (trimmed).
statusactive, or paused_balance while the balance cannot cover checks (resumes automatically once balance is added).
created_atWhen tracking started, ISO 8601 in UTC.
last_checked_atThe latest check delivered, ISO 8601 in UTC; null before the first one.
next_check_atWhen the keyword is due to be checked next, ISO 8601 in UTC; null while paused.
latestThe latest position record, or null before the first check. Returned by rank_tracking/list only.
Status codes
Codes this endpoint can return, at the request or task level. See Status codes for handling advice.
| Code | Message | HTTP | Level | When |
|---|---|---|---|---|
| 20000 | Ok. | 200 | Request / task | The request, or the individual task, was processed successfully. |
| 40000 | Bad Request. | 400 / 200 | Request / task | The body is not valid JSON or does not have the expected shape (for example, not an array of task objects, or more than one task for live). Also returned with HTTP 413 for bodies larger than 1 MiB and with HTTP 405 for a wrong HTTP method. As a task-level code (HTTP 200) it means the task cannot be carried out as asked, for example because the account already has the maximum number of API keys or monitored products. |
| 40001 | Too many tasks in one request (max 100). | 400 | Request | A POST body contains more task objects than allowed. |
| 40100 | Authentication failed. | 401 | Request | The Authorization header is missing or malformed, or the login and API key do not match. |
| 40101 | API key revoked. | 401 | Request | The API key was revoked. Use another active key or create a new one. |
| 40102 | Account disabled. | 401 | Request | The account is disabled. Contact support. |
| 40202 | Rate limit exceeded. | 429 | Request | Too many requests or tasks per minute for this account, or too many access requests from one IP address. The Retry-After header says how many seconds to wait. |
| 40501 | Invalid field: `<name>`. | 400 / 200 | Request / task | A field has a wrong type, format or value; the message names the field, for example "Invalid field: `priority`." |
| 40502 | Unknown marketplace. | 200 | Task | The marketplace is not one of the 12 supported codes or their aliases. |
| 40503 | Invalid ASIN. | 200 | Task | The ASIN does not match ^[A-Z0-9]{10}$ after uppercasing. |
| 40600 | Feature not available on your plan. | 403 | Request | The requested feature is not enabled for this account. |
| 50000 | Internal error. | 500 | Request | Unexpected server error. The request can be retried; contact support if it persists. |
Related endpoints
- GETlistList tracked keywordsYour tracked keywords with the latest position of each.
- POSThistoryPosition recordsEvery check of the keywords you track for an ASIN, newest first.
- POSTdailyPositions by dayOne row per keyword and UTC day: the median, best and worst position.
- POSTdeleteStop tracking keyword positionsStop tracking keywords by id, or every keyword (or one) of an ASIN.