Amazon Monitoring API
Add products to monitoring
Add products once and receive fresh observations hourly, every 6 hours or daily.
https://api.screamingdata.dev/v1/amazon/monitoring/add- Authentication
- API key (HTTP Basic)
- Cost
- $0.0006 per observation
List price · volume rates on request
- Body
- Array of up to 100 tasks
Overview
Adds each product in the array to your monitoring: it is observed regularly at the chosen frequency. New observations appear in monitoring/list and in history.
Adding the same ASIN and marketplace again updates the frequency and tag of the existing subscription instead of creating a duplicate.
Every delivered observation is charged at your monitoring rate. If your balance cannot cover an observation, your subscriptions switch to paused_balance and resume automatically once balance is added. A subscription added while your balance is below the monitoring rate, or while your subscriptions are paused, starts as paused_balance and resumes in the same way.
An account can monitor up to 10,000 products; beyond that the task fails with 40000 — delete subscriptions you no longer need, or ask support for a higher limit.
Platforms that serve many end users can attribute subscriptions with external_user_id — an opaque id from your system. Do not put personal data in it: values that look like e-mail addresses are rejected.
Cost
Request
POST /v1/amazon/monitoring/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:
asinASIN of the product. Case-insensitive; must be 10 letters or digits after uppercasing.
- Pattern
^[A-Z0-9]{10}$ - Example
B0EXAMPLE1
marketplaceMarketplace code. The aliases us and usa (for com) and gb (for uk) are also accepted. See Marketplaces.
- Allowed
comukdefresitnlcaaujpmxin - Example
com
frequencyHow often to observe the product.
- Allowed
hourlyevery_6hdaily - Example
daily
tagYour own identifier. It is echoed back in the task data, returned with the subscription and can be used to filter monitoring/list.
- Max length255 characters
- Example
client-42
external_user_idOpaque id of your own end user. Must not contain personal data; values that look like e-mail addresses are rejected.
- Max length255 characters
- Example
u_8f3a2c
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/ monitoring/ add" \
--user "$API_LOGIN:$API_KEY" \
--header "Content-Type: application/json" \
--data '[
{
"asin": "B0EXAMPLE1",
"marketplace": "com",
"frequency": "daily",
"tag": "client-42",
"external_user_id": "u_8f3a2c"
},
{
"asin": "B0EXAMPLE2",
"marketplace": "uk",
"frequency": "hourly",
"tag": "launch-watch"
}
]'import os
import requests
response = requests.post(
"https://api.screamingdata.dev/ v1/ amazon/ monitoring/ add",
auth=(os.environ["API_LOGIN"], os.environ["API_KEY"]),
json=[
{
"asin": "B0EXAMPLE1",
"marketplace": "com",
"frequency": "daily",
"tag": "client-42",
"external_user_id": "u_8f3a2c",
},
{
"asin": "B0EXAMPLE2",
"marketplace": "uk",
"frequency": "hourly",
"tag": "launch-watch",
},
],
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/ monitoring/ add", {
method: "POST",
headers: {
Authorization: `Basic ${auth}`,
"Content-Type": "application/json",
},
body: JSON.stringify([
{
asin: "B0EXAMPLE1",
marketplace: "com",
frequency: "daily",
tag: "client-42",
external_user_id: "u_8f3a2c",
},
{
asin: "B0EXAMPLE2",
marketplace: "uk",
frequency: "hourly",
tag: "launch-watch",
},
]),
});
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.
{
"version": "1.0.0",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0268 sec.",
"cost": 0,
"tasks_count": 2,
"tasks_error": 0,
"tasks": [
{
"id": "09241302-3c9e-4f1a-8b2d-5e7a0c6f4d18",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0051 sec.",
"cost": 0,
"result_count": 1,
"path": [
"v1",
"amazon",
"monitoring",
"add"
],
"data": {
"api": "amazon",
"function": "monitoring",
"asin": "B0EXAMPLE1",
"marketplace": "com",
"frequency": "daily",
"tag": "client-42",
"external_user_id": "u_8f3a2c"
},
"result": [
{
"id": 3051,
"asin": "B0EXAMPLE1",
"marketplace": "com",
"frequency": "daily",
"tag": "client-42",
"external_user_id": "u_8f3a2c",
"status": "active",
"created_at": "2026-09-24T13:02:11Z"
}
]
},
{
"id": "09241302-9a4b-4c7e-a1f3-2d8b6e0c5f39",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0047 sec.",
"cost": 0,
"result_count": 1,
"path": [
"v1",
"amazon",
"monitoring",
"add"
],
"data": {
"api": "amazon",
"function": "monitoring",
"asin": "B0EXAMPLE2",
"marketplace": "uk",
"frequency": "hourly",
"tag": "launch-watch"
},
"result": [
{
"id": 3052,
"asin": "B0EXAMPLE2",
"marketplace": "uk",
"frequency": "hourly",
"tag": "launch-watch",
"external_user_id": null,
"status": "active",
"created_at": "2026-09-24T13:02:11Z"
}
]
}
]
}Result fields
Each element of tasks[].result is a subscription object. A monitored product. monitoring/add returns it without latest_observation.
idSubscription id. Use it with monitoring/delete.
asinMonitored ASIN.
marketplaceMarketplace code.
frequencyhourly, every_6h or daily.
tagYour tag.
external_user_idYour opaque end-user id.
statusactive, or paused_balance while the balance cannot cover observations (resumes automatically once balance is added).
created_atWhen the subscription was created, ISO 8601 in UTC.
latest_observationThe latest observation delivered to this subscription (a product object, same shape as in task_get), or null before the first delivery. Returned by monitoring/list only.
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. |
| 50000 | Internal error. | 500 | Request | Unexpected server error. The request can be retried; contact support if it persists. |
Related endpoints
- GETlistList monitored productsYour subscriptions with the latest observation of each product.
- POSTdeleteDelete monitored productsStop monitoring products by subscription id or by ASIN and marketplace.
- POSThistoryGet product historyStored observations of a product, newest first — BSR, price and rating over time.