Skip to content
Screaming Data
Documentation menu

Amazon Rank Tracking API

Track keyword positions

Track where an ASIN stands in Amazon search for a keyword, checked every day.

POST
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

Adding is free; each check delivered to a tracked keyword is charged. List price: $0.0040 per delivered check — volume rates on request; the charges appear in your usage. See pricing · Get a quote

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:

asin
stringrequired

ASIN of the product. Case-insensitive; must be 10 letters or digits after uppercasing.

  • 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
stringrequired

The 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
  • Examplewireless 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"
  }
]'

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.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.

id
integer

Tracking id. Use it with rank_tracking/delete.

asin
string

Tracked ASIN.

marketplace
string

Marketplace code.

keyword
string

The keyword as you sent it (trimmed).

status
string

active, or paused_balance while the balance cannot cover checks (resumes automatically once balance is added).

created_at
string (date-time)

When tracking started, ISO 8601 in UTC.

last_checked_at
string (date-time)· nullable

The latest check delivered, ISO 8601 in UTC; null before the first one.

next_check_at
string (date-time)· nullable

When the keyword is due to be checked next, ISO 8601 in UTC; null while paused.

latest
object· nullable

The 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.

CodeMessageHTTPLevelWhen
20000Ok.200Request / taskThe request, or the individual task, was processed successfully.
40000Bad Request.400 / 200Request / taskThe 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.
40001Too many tasks in one request (max 100).400RequestA POST body contains more task objects than allowed.
40100Authentication failed.401RequestThe Authorization header is missing or malformed, or the login and API key do not match.
40101API key revoked.401RequestThe API key was revoked. Use another active key or create a new one.
40102Account disabled.401RequestThe account is disabled. Contact support.
40202Rate limit exceeded.429RequestToo 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.
40501Invalid field: `<name>`.400 / 200Request / taskA field has a wrong type, format or value; the message names the field, for example "Invalid field: `priority`."
40502Unknown marketplace.200TaskThe marketplace is not one of the 12 supported codes or their aliases.
40503Invalid ASIN.200TaskThe ASIN does not match ^[A-Z0-9]{10}$ after uppercasing.
40600Feature not available on your plan.403RequestThe requested feature is not enabled for this account.
50000Internal error.500RequestUnexpected server error. The request can be retried; contact support if it persists.