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",
            "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"
          },
          "parser_version": "2026.09.2"
        },
        {
          "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",
            "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"
          },
          "parser_version": "2026.09.2"
        }
      ]
    }
  ]
}

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 · parser 2026.09.2

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. Any field that cannot be read reliably 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 page URL on the marketplace.

observed_at

string (date-time)

When the product page was read, ISO 8601 in UTC.

status

string

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

title

string· nullable

Product title as shown on the page.

byline

array of strings

Names shown under the title, in page order — usually the brand of the product, from its "Visit the … Store" or "Brand: …" line. Empty when the page shows none or they could not be read.

variant

string· nullable

Label of the selected variant as the page shows it — 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 page offers no variants.

variants

array of objects

Sibling variants listed on the page, each with name and asin — the selected one included. Empty when the page lists none.

variants[].name

string

Label of the variant as the page shows it.

variants[].asin

string

ASIN of that variant.

price

object· nullable

Current price, or null when the page shows none.

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

Rank in the main category.

bsr.category

string

Main category as the marketplace shows it, for example Electronics or Home & Kitchen.

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 page's product details — the details list and the product-information, technical-details, overview and product-facts tables — 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 nothing could be read.

details.<key>

string

One value as the page shows it, for example 8.8 ounces for item_weight.

parser_version

string

Version of the parser that produced this object.

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.