# Amazon Price History & Sales Rank Tracker (`cyprusapi/amazon-price-history`) Actor

Get years of Amazon price history, sales rank history and rating history for any ASIN - going back to 2011, not just from your first run. Amazon, New, Used, FBA, Buy Box and offer-count time series in 13 marketplaces. Export wide or one row per data point. Errors are never charged.

- **URL**: https://apify.com/cyprusapi/amazon-price-history.md
- **Developed by:** [Torchtechnology LTD](https://apify.com/cyprusapi) (community)
- **Categories:** E-commerce, Developer tools, Automation
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 product histories

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Amazon Price History & Sales Rank Tracker

Get **years of Amazon price history** for any ASIN — not just from the moment you
start tracking. Most price trackers begin collecting the day you first run them.
This one returns the history that already exists, often going back to **2011**.

For a typical product that means thousands of observations in a single run:
Amazon's own price, third-party New and Used, list price, sales rank and offer
counts, each as a dated time series.

### What you get

| Series | Included in base price |
|---|---|
| `amazon` — Amazon's own price | ✅ |
| `new` — lowest marketplace new price | ✅ |
| `used` — lowest marketplace used price | ✅ |
| `salesRank` — Best Sellers Rank | ✅ |
| `listPrice` — list price / MSRP | ✅ |
| `offerCountNew` / `offerCountUsed` | ✅ |
| `collectible`, `refurbished`, `lightningDeal`, `tradeIn`, `ebayNew`, `ebayUsed` | ✅ |
| `rating`, `reviewCount` | + charged separately |
| `buyBox`, `buyBoxUsed` | ++ charged separately |
| `newFba`, `newFbm`, `warehouse`, `primeExclusive`, used-by-condition | requires **Include offer-based series** |

Series in the last three rows need extra data from the source. They are only
charged **when the data actually arrives** — and if you leave the offer option
off, offer-based series are skipped rather than silently returned empty.

### Two output shapes

**One row per product** (`wide`) nests each series inside the product. Best for
JSON and for feeding an application:

```json
{
  "asin": "B0C3HCD34R",
  "marketplace": "com",
  "currency": "USD",
  "trackedSince": "2023-04-26T02:16:00Z",
  "history": {
    "new": [
      { "date": "2023-06-19T07:28:00Z", "value": 69.99 },
      { "date": "2024-11-08T04:46:00Z", "value": 34.99 }
    ]
  },
  "summary": {
    "new": {
      "pointCount": 307,
      "observedCount": 305,
      "first":   { "date": "2023-06-19T07:28:00Z", "value": 69.99 },
      "last":    { "date": "2026-08-11T02:28:00Z", "value": 44.99 },
      "lowest":  { "date": "2024-11-08T04:46:00Z", "value": 34.99 },
      "highest": { "date": "2023-06-19T07:28:00Z", "value": 69.99 }
    }
  }
}
```

**One row per data point** (`long`) emits a flat row per observation. Best for
CSV, Excel, BigQuery or any database:

```json
{ "asin": "B0C3HCD34R", "series": "new", "date": "2024-11-08T04:46:00Z", "value": 34.99, "currency": "USD" }
```

### Reading the data correctly

- **`value: null` is meaningful.** It means nothing was on offer in that
  interval — the product was out of stock. It does not mean "price unknown", and
  it is not a gap you should interpolate across. Dropping those points would
  wrongly imply the previous price still stood.
- **A new point only appears when the value changed.** Flat stretches are real,
  not missing data.
- **For `salesRank`, `lowest` means the best rank.** Rank 11 is better than rank
  85,331. The field names describe the number, not the ranking.
- **Prices are in the marketplace's own currency**, already converted to major
  units. The `currency` field is authoritative — never infer it from a symbol.
- **`rating` is on a 0–5 scale** with one decimal, already converted for you.

### Pricing

Charged **once per ASIN**, no matter how many data points come back — a product
with 8,000 observations costs the same as one with 12. Extra series are separate
events and only charged when delivered.

**Errors are never charged.** That includes ASINs that do not exist, products
with no history in the requested window, and requests that hit a temporary
capacity limit. Those come back marked `status: "notFound"`,
`status: "noHistory"` or `status: "currentlyUnavailable"` with a
`retryAfterSeconds` hint — the run still finishes successfully so your pipeline
does not break.

### Tips

- **Use `days` to top up.** Pull the full history once, then set `days: 7` on a
  schedule. Same price, a fraction of the response size.
- **Bundle your ASINs.** Up to 100 are combined into one request automatically.
- **Need current data instead of history?** Use the *Amazon Product Data* Actor.
- **Need to find ASINs first?** Use *Amazon Product Finder* or
  *Amazon Bestseller Lists*.

# Actor input Schema

## `asins` (type: `array`):

Amazon product IDs to get history for. Up to 100 are bundled into a single request. You are charged once per ASIN, no matter how many data points its history contains.

## `marketplace` (type: `string`):

Which Amazon marketplace to read. Prices and currency always follow the marketplace you pick.

## `maxItems` (type: `integer`):

Safety cap on how many products this run may return. Set to 0 to process the whole input list.

## `outputFormat` (type: `string`):

'One row per product' nests each time series inside the product - best for JSON. 'One row per data point' emits a flat row for every single observation - best for CSV, Excel and databases.

## `series` (type: `array`):

Which histories to return. The six defaults are included in the base price. Series marked (+) need extra data from the source and are charged as separate events, but only when that data actually arrives: rating and reviewCount (+), buyBox and buyBoxUsed (++). Series marked (offers) additionally require the 'Include offer-based series' option below.

## `includeOfferSeries` (type: `boolean`):

Unlocks FBA, FBM, Warehouse and Prime-exclusive price histories. These require pulling live marketplace offers, which is the most expensive data this source provides and is priced per product, not per run. Leave off unless you specifically need these series - without it they are skipped and you are not charged for them.

## `days` (type: `integer`):

Return only the most recent N days of history. Free of charge, and it makes runs much faster - ideal for topping up data you already have. Leave at 0 for the complete history.

## `includeSummary` (type: `boolean`):

Adds first, last, lowest and highest observed value per series, each with its date. Free of charge.

## `salesRankByCategory` (type: `boolean`):

Adds a separate rank history for every category the product is listed in, instead of just the main one. Free of charge.

## `dataFreshnessHours` (type: `integer`):

Refresh a product only when its stored data is older than this. History itself is unaffected - this only controls how current the last data point is.

## `maxWaitSeconds` (type: `integer`):

If the shared data capacity is momentarily used up, wait up to this long for it to refill. Anything still unserved afterwards is reported as currently unavailable - and never charged.

## `apiKey` (type: `string`):

Advanced: run this Actor against your own upstream account instead of the bundled capacity. Leave empty to use the included capacity.

## Actor input object example

```json
{
  "asins": [
    "B0CHX1W1XY",
    "B08N5WRWNW"
  ],
  "marketplace": "com",
  "maxItems": 10,
  "outputFormat": "wide",
  "series": [
    "amazon",
    "new",
    "used",
    "salesRank",
    "listPrice",
    "offerCountNew"
  ],
  "includeOfferSeries": false,
  "days": 0,
  "includeSummary": true,
  "salesRankByCategory": false,
  "dataFreshnessHours": 24,
  "maxWaitSeconds": 60
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "asins": [
        "B0CHX1W1XY",
        "B08N5WRWNW"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("cyprusapi/amazon-price-history").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "asins": [
        "B0CHX1W1XY",
        "B08N5WRWNW",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("cyprusapi/amazon-price-history").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "asins": [
    "B0CHX1W1XY",
    "B08N5WRWNW"
  ]
}' |
apify call cyprusapi/amazon-price-history --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,cyprusapi/amazon-price-history"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/py11x3Ss7PyDZYfmm/builds/a0eyPR9kpklTdJLaE/openapi.json