Amazon Rank Tracking API

Position records

Every check of the keywords you track for an ASIN, newest first.

POST

https://api.screamingdata.dev/v1/amazon/rank_tracking/history

Authentication: API key (HTTP Basic)
Cost: Free
Body: Array of up to 100 tasks

Overview

Returns the position records of the keywords you track (or tracked) for an ASIN, newest first — one per check. Narrow them to one keyword and to a range of UTC days.

A product that was not found has organic_rank null: it is not among the first checked_depth organic results of that check.

Cost

Free.

Request

POST /v1/amazon/rank_tracking/history with Content-Type: application/json.

Body fields

The request body is a JSON array of 1–100 task objects. Each object has these fields:

asin

stringrequired

ASIN you track or tracked.

Pattern^[A-Z0-9]{10}$
ExampleB0EXAMPLE1

marketplace

stringrequired

Marketplace code. The aliases us and usa (for com) and gb (for uk) are also accepted. See Marketplaces.

Allowedcomukdefresitnlcaaujpmxin
Examplecom

keyword

stringoptional

Only this keyword; every keyword you track or tracked for the ASIN when absent.

Max length200 characters
Examplewireless earbuds

date_from

string (date)optional

First UTC day, YYYY-MM-DD.

Example2026-09-01

date_to

string (date)optional

Last UTC day, YYYY-MM-DD.

Example2026-09-30

limit

integeroptional

Maximum number of records to return, newest first.

Default100
Range1 – 1000
Example100

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/history" \
  --user "$API_LOGIN:$API_KEY" \
  --header "Content-Type: application/json" \
  --data '[
  {
    "asin": "B0EXAMPLE1",
    "marketplace": "com",
    "keyword": "wireless earbuds",
    "date_from": "2026-09-30",
    "date_to": "2026-10-03",
    "limit": 100
  }
]'

import os

import requests

response = requests.post(
    "https://api.screamingdata.dev/v1/amazon/rank_tracking/history",
    auth=(os.environ["API_LOGIN"], os.environ["API_KEY"]),
    json=[
        {
            "asin": "B0EXAMPLE1",
            "marketplace": "com",
            "keyword": "wireless earbuds",
            "date_from": "2026-09-30",
            "date_to": "2026-10-03",
            "limit": 100,
        },
    ],
    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/history", {
  method: "POST",
  headers: {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    {
      asin: "B0EXAMPLE1",
      marketplace: "com",
      keyword: "wireless earbuds",
      date_from: "2026-09-30",
      date_to: "2026-10-03",
      limit: 100,
    },
  ]),
});
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.

Response example

{
  "version": "1.0.0",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0022 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "10031503-9f2b-4d6a-8c1e-3b7a5d0e2f84",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0022 sec.",
      "cost": 0,
      "result_count": 3,
      "path": [
        "v1",
        "amazon",
        "rank_tracking",
        "history"
      ],
      "data": {
        "api": "amazon",
        "function": "rank_tracking",
        "asin": "B0EXAMPLE1",
        "marketplace": "com",
        "keyword": "wireless earbuds",
        "date_from": "2026-09-30",
        "date_to": "2026-10-03",
        "limit": 100
      },
      "result": [
        {
          "asin": "B0EXAMPLE1",
          "marketplace": "com",
          "keyword": "wireless earbuds",
          "observed_at": "2026-10-03T05:02:41Z",
          "organic_rank": 7,
          "organic_page": 1,
          "checked_depth": 100,
          "total_results": 27435,
          "matched_asin": "B0EXAMPLE1",
          "matched_format": null
        },
        {
          "asin": "B0EXAMPLE1",
          "marketplace": "com",
          "keyword": "wireless earbuds",
          "observed_at": "2026-10-02T05:01:58Z",
          "organic_rank": 9,
          "organic_page": 1,
          "checked_depth": 100,
          "total_results": 27435,
          "matched_asin": "B0EXAMPLE1",
          "matched_format": null
        },
        {
          "asin": "B0EXAMPLE1",
          "marketplace": "com",
          "keyword": "wireless earbuds",
          "observed_at": "2026-10-01T05:03:12Z",
          "organic_rank": 12,
          "organic_page": 1,
          "checked_depth": 100,
          "total_results": 27435,
          "matched_asin": "B0EXAMPLE2",
          "matched_format": null
        }
      ]
    }
  ]
}

Result fields

Each element of tasks[].result is a position record. One check of a tracked keyword: where the product stood among Amazon's organic search results.

asin

string

The tracked ASIN.

marketplace

string

Marketplace code.

keyword

string

The keyword as it was searched.

observed_at

string (date-time)

When the search was checked, ISO 8601 in UTC.

organic_rank

integer· nullable

Position among the organic (not sponsored) results, 1 = first. null when the product is not among the first checked_depth of them.

organic_page

integer· nullable

Search result page of that position, when known.

checked_depth

integer· nullable

How many organic positions the check covered (usually 100, more when the product was missing the day before).

total_results

integer· nullable

Number of results Amazon reported for the search.

matched_asin

string· nullable

The listing that was found: the ASIN itself or one of its variants or other editions, which count as the product.

matched_format

string· nullable

The label the matching listing carried in search (an edition or format), when it had one.

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.

Overview#

Request#

Body fields

Request example#

Response#

Result fields#

Status codes#

Related endpoints#

Overview

Request

Request example

Response

Result fields

Status codes

Related endpoints