Amazon Product API

Get product history

Stored observations of a product, newest first — BSR, price and rating over time.

POST

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

Authentication: API key (HTTP Basic)
Cost: $0.0005 per product
List price · volume rates on request
Body: Array of up to 100 tasks

Overview

Returns stored observations of one product, newest first. Every item has the shape of the product object, so you can chart BSR, price, rating and ratings count over time.

History includes every observation stored for the product, whichever request or subscription produced it. A product that has never been requested has no history yet — post a task or add monitoring to start one.

Use date_from, date_to, limit and offset to page through long histories.

Cost

Charged per element of the request body (one product, up to 1,000 rows), also when the product has no stored observations yet. List price: $0.0005 per product — volume rates on request; every response reports the exact cost. See pricing · Get a quote

Request

POST /v1/amazon/product/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 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

date_from

string (date)optional

Earliest day to include, YYYY-MM-DD (UTC, inclusive).

Example2026-09-01

date_to

string (date)optional

Latest day to include, YYYY-MM-DD (UTC, inclusive).

Example2026-09-24

limit

integeroptional

Maximum number of observations to return.

Default100
Range1 – 1000
Example100

offset

integeroptional

Number of observations to skip, for paging.

Default0
Range0 – 1000000
Example0

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/product/history" \
  --user "$API_LOGIN:$API_KEY" \
  --header "Content-Type: application/json" \
  --data '[
  {
    "asin": "B0EXAMPLE1",
    "marketplace": "com",
    "date_from": "2026-09-01",
    "date_to": "2026-09-24",
    "limit": 2,
    "offset": 0
  }
]'

import os

import requests

response = requests.post(
    "https://api.screamingdata.dev/v1/amazon/product/history",
    auth=(os.environ["API_LOGIN"], os.environ["API_KEY"]),
    json=[
        {
            "asin": "B0EXAMPLE1",
            "marketplace": "com",
            "date_from": "2026-09-01",
            "date_to": "2026-09-24",
            "limit": 2,
            "offset": 0,
        },
    ],
    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/product/history", {
  method: "POST",
  headers: {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    {
      asin: "B0EXAMPLE1",
      marketplace: "com",
      date_from: "2026-09-01",
      date_to: "2026-09-24",
      limit: 2,
      offset: 0,
    },
  ]),
});
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.0298 sec.",
  "cost": 0.0005,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "09241243-5b7f-4e2d-9a61-0c8e3f2d1b45",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0165 sec.",
      "cost": 0.0005,
      "result_count": 2,
      "path": [
        "v1",
        "amazon",
        "product",
        "history"
      ],
      "data": {
        "api": "amazon",
        "function": "product",
        "asin": "B0EXAMPLE1",
        "marketplace": "com",
        "date_from": "2026-09-01",
        "date_to": "2026-09-24",
        "limit": 2,
        "offset": 0
      },
      "result": [
        {
          "asin": "B0EXAMPLE1",
          "marketplace": "com",
          "url": "https://www.amazon.com/dp/B0EXAMPLE1",
          "observed_at": "2026-09-24T12:35:41Z",
          "status": "ok",
          "title": "Acme Wireless Noise Cancelling Headphones, Black",
          "byline": [
            "Acme"
          ],
          "variant": "Black",
          "variants": [
            {
              "name": "Black",
              "asin": "B0EXAMPLE1"
            },
            {
              "name": "White",
              "asin": "B0EXAMPLE2"
            },
            {
              "name": "Navy Blue",
              "asin": "B0EXAMPLE3"
            }
          ],
          "price": {
            "amount": 59.99,
            "currency": "USD"
          },
          "bsr": {
            "rank": 1432,
            "category": "Electronics",
            "scope": "main",
            "subcategories": [
              {
                "rank": 12,
                "category": "Over-Ear Headphones"
              },
              {
                "rank": 31,
                "category": "Noise-Cancelling Headphones"
              }
            ]
          },
          "rating": 4.5,
          "ratings_count": 2318,
          "image_url": "https://m.media-amazon.com/images/I/example._AC_SL1500_.jpg",
          "details": {
            "brand": "Acme",
            "color": "Black",
            "connectivity_technology": "Wireless",
            "date_first_available": "March 4, 2025",
            "item_model_number": "AC-WH400",
            "item_weight": "8.8 ounces",
            "manufacturer": "Acme",
            "product_dimensions": "7.3 x 6.5 x 3.1 inches"
          }
        },
        {
          "asin": "B0EXAMPLE1",
          "marketplace": "com",
          "url": "https://www.amazon.com/dp/B0EXAMPLE1",
          "observed_at": "2026-09-23T12:36:02Z",
          "status": "ok",
          "title": "Acme Wireless Noise Cancelling Headphones, Black",
          "byline": [
            "Acme"
          ],
          "variant": "Black",
          "variants": [
            {
              "name": "Black",
              "asin": "B0EXAMPLE1"
            },
            {
              "name": "White",
              "asin": "B0EXAMPLE2"
            },
            {
              "name": "Navy Blue",
              "asin": "B0EXAMPLE3"
            }
          ],
          "price": {
            "amount": 64.99,
            "currency": "USD"
          },
          "bsr": {
            "rank": 1518,
            "category": "Electronics",
            "scope": "main",
            "subcategories": [
              {
                "rank": 13,
                "category": "Over-Ear Headphones"
              },
              {
                "rank": 33,
                "category": "Noise-Cancelling Headphones"
              }
            ]
          },
          "rating": 4.5,
          "ratings_count": 2311,
          "image_url": "https://m.media-amazon.com/images/I/example._AC_SL1500_.jpg",
          "details": {
            "brand": "Acme",
            "color": "Black",
            "connectivity_technology": "Wireless",
            "date_first_available": "March 4, 2025",
            "item_model_number": "AC-WH400",
            "item_weight": "8.8 ounces",
            "manufacturer": "Acme",
            "product_dimensions": "7.3 x 6.5 x 3.1 inches"
          }
        }
      ]
    }
  ]
}

Result, rendered

The product object of the example above as an application would show it: identity, byline and variants, price, rank and rating, and every label → value pair of details.

B0EXAMPLE1·amazon.com

Acme Wireless Noise Cancelling Headphones, Black

Acme

BlackB0EXAMPLE1
WhiteB0EXAMPLE2
Navy BlueB0EXAMPLE3

Price

$59.99

USD

Best Sellers Rank

#1,432

in Electronics

Rating

4.5out of 5

2,318 ratings

#12 in Over-Ear Headphones
#31 in Noise-Cancelling Headphones

details8 pairs

brand: Acme
color: Black
connectivity_technology: Wireless
date_first_available: March 4, 2025
item_model_number: AC-WH400
item_weight: 8.8 ounces
manufacturer: Acme
product_dimensions: 7.3 x 6.5 x 3.1 inches

observed 24 Sept 2026, 12:35 UTC

Result fields

Each element of tasks[].result is a product object. Returned by task_get and live (result[0]), by history (every item) and inside monitoring subscriptions. Text is returned as the marketplace shows it, in its language. A field that is not available is null (empty for byline, variants and details) — values are never guessed.

asin

string

ASIN that was observed (uppercased).

marketplace

string

Marketplace code.

url

string

Product URL on the marketplace.

observed_at

string (date-time)

When the observation was made, ISO 8601 in UTC.

status

string

ok — the observation was made; no_bsr — the product has no Best Sellers Rank; not_found — the product does not exist on this marketplace.

title

string· nullable

Product title.

byline

array of strings

Names listed for the product — usually its brand. Empty when none are available.

variant

string· nullable

Label of the selected variant — a colour, size, style or configuration. When several options are selected (colour and size), their labels are joined with , , for example Black, Large. null when the product has no variants.

variants

array of objects

Sibling variants of the product, each with name and asin — the selected one included. Empty when none are listed.

variants[].name

string

Label of the variant.

variants[].asin

string

ASIN of that variant.

price

object· nullable

Current price, or null when none is listed.

price.amount

number

Price in the marketplace currency.

price.currency

string

ISO 4217 currency code, for example USD.

bsr

object· nullable

Best Sellers Rank, or null when status is no_bsr or not_found.

bsr.rank

integer

The first rank the marketplace shows: the rank in the main category when bsr.scope is main.

bsr.category

string

Category of bsr.rank as the marketplace shows it, for example Electronics or Home & Kitchen.

bsr.scope

string· nullable

What bsr.rank is: main — the rank in the main category; subcategory — the marketplace shows no main-category rank for this product, so bsr.rank is its rank in a subcategory (and the first item of bsr.subcategories); store — a rank in a special store list rather than the main category; null — not known (an observation made before 2026-10-15).

bsr.subcategories

array of objects

Ranks in subcategories, each with rank and category.

rating

number· nullable

Average customer rating from 1.0 to 5.0.

ratings_count

integer· nullable

Number of customer ratings.

image_url

string· nullable

URL of the main product image.

details

object

Every label → value pair of the product's details (specifications) except the Best Sellers Rank and the customer rating, which are bsr, rating and ratings_count. Keys are the labels lower-cased, with every run of spaces and punctuation turned into _; they stay in the marketplace's language (item_weight on com, artikelgewicht on de, メーカー on jp) and are sorted. Values are the text as shown, trimmed, without invisible characters. At most 60 entries; a value longer than 500 characters is cut. {} when none are available.

details.<key>

string

One value as published, for example 8.8 ounces for item_weight.

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.
40200	Payment Required. Insufficient balance.	402 / 200	Request / task	The balance does not cover the cost. When no task of a request can be paid for, the whole request fails with HTTP 402; otherwise only the tasks that cannot be paid for fail. Contact us to add balance, then retry.
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.
50000	Internal error.	500	Request	Unexpected server error. The request can be retried; contact support if it persists.