Amazon Product API

Post product tasks

Queue up to 100 product lookups in one request and collect the results later.

POST

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

Authentication: API key (HTTP Basic)
Cost: $0.0015 per tasknormal priority
$0.0030 per taskhigh priority
List price · volume rates on request
Body: Array of up to 100 tasks

Overview

Creates one task per element of the array. Each task reads the Amazon product page of one ASIN on one marketplace and produces a product object: title, byline, variants, price, Best Sellers Rank with category ranks, rating and the product details.

Tasks are charged when they are posted, at your normal or high-priority rate. If an observation of the same product younger than 60 minutes already exists, the task completes immediately from it.

Collect finished tasks with tasks_ready and task_get, or let the API call you: postback_url receives the full result, pingback_url receives a short notification. See Webhooks.

Results are stored for 30 days.

Cost

Charged per task when it is posted. Failed tasks are refunded automatically: products that do not exist (40402) and pages that could not be read (50301) cost nothing. List price: $0.0015 per task (normal priority) or $0.0030 per task (high priority) — volume rates on request; every response reports the exact cost. See pricing · Get a quote

Up to 100 tasks per request and 2,000 tasks per minute per account. See Rate limits.

Validation errors are reported per task: one invalid element does not reject the others.

Request

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

priority

integeroptional

1 — normal, 2 — high. High-priority tasks are processed first and cost more.

Default1
Allowed12
Example1

tag

stringoptional

Your own identifier. It is echoed back in the task data, in tasks_ready and in pingbacks.

Max length255 characters
Examplecatalog-sync

postback_url

string (uri)optional

When the task completes, the full task_get response is sent here with a POST request, signed with your webhook secret. Private, loopback and link-local addresses are refused.

Max length2048 characters
Examplehttps://example.com/webhooks/postback

pingback_url

string (uri)optional

When the task completes, a GET request is sent to this URL. The placeholders $id and $tag are replaced with the task id and tag.

Max length2048 characters
Examplehttps://example.com/webhooks/pingback?id=$id&tag=$tag

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/task_post" \
  --user "$API_LOGIN:$API_KEY" \
  --header "Content-Type: application/json" \
  --data '[
  {
    "asin": "B0EXAMPLE1",
    "marketplace": "com",
    "priority": 1,
    "tag": "catalog-sync",
    "postback_url": "https://example.com/webhooks/postback"
  },
  {
    "asin": "B0EXAMPLE2",
    "marketplace": "uk",
    "priority": 2,
    "tag": "launch-watch",
    "pingback_url": "https://example.com/webhooks/pingback?id=$id&tag=$tag"
  }
]'

import os

import requests

response = requests.post(
    "https://api.screamingdata.dev/v1/amazon/product/task_post",
    auth=(os.environ["API_LOGIN"], os.environ["API_KEY"]),
    json=[
        {
            "asin": "B0EXAMPLE1",
            "marketplace": "com",
            "priority": 1,
            "tag": "catalog-sync",
            "postback_url": "https://example.com/webhooks/postback",
        },
        {
            "asin": "B0EXAMPLE2",
            "marketplace": "uk",
            "priority": 2,
            "tag": "launch-watch",
            "pingback_url": "https://example.com/webhooks/pingback?id=$id&tag=$tag",
        },
    ],
    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/task_post", {
  method: "POST",
  headers: {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    {
      asin: "B0EXAMPLE1",
      marketplace: "com",
      priority: 1,
      tag: "catalog-sync",
      postback_url: "https://example.com/webhooks/postback",
    },
    {
      asin: "B0EXAMPLE2",
      marketplace: "uk",
      priority: 2,
      tag: "launch-watch",
      pingback_url: "https://example.com/webhooks/pingback?id=$id&tag=$tag",
    },
  ]),
});
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.0391 sec.",
  "cost": 0.0045,
  "tasks_count": 2,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "09241235-4e1c-4b6a-9d8f-2c7a51f0e3b1",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0042 sec.",
      "cost": 0.0015,
      "result_count": 0,
      "path": [
        "v1",
        "amazon",
        "product",
        "task_post"
      ],
      "data": {
        "api": "amazon",
        "function": "product",
        "asin": "B0EXAMPLE1",
        "marketplace": "com",
        "priority": 1,
        "tag": "catalog-sync",
        "postback_url": "https://example.com/webhooks/postback"
      },
      "result": null
    },
    {
      "id": "09241235-7a02-4f3e-8c11-5b9d0e6a4c27",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0038 sec.",
      "cost": 0.003,
      "result_count": 0,
      "path": [
        "v1",
        "amazon",
        "product",
        "task_post"
      ],
      "data": {
        "api": "amazon",
        "function": "product",
        "asin": "B0EXAMPLE2",
        "marketplace": "uk",
        "priority": 2,
        "tag": "launch-watch",
        "pingback_url": "https://example.com/webhooks/pingback?id=$id&tag=$tag"
      },
      "result": null
    }
  ]
}

Example: Insufficient balance (HTTP 402)

Insufficient balance

{
  "version": "1.0.0",
  "status_code": 40200,
  "status_message": "Payment Required. Insufficient balance.",
  "time": "0.0012 sec.",
  "cost": 0,
  "tasks_count": 0,
  "tasks_error": 0,
  "tasks": []
}

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.
20100	Task Created.	200	Task	task_post accepted the task. Collect the result later with tasks_ready and task_get, or receive it with a webhook.
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.

Overview#

Request#

Body fields

Request example#

Response#

Status codes#

Related endpoints#

Overview

Request

Request example

Response

Status codes

Related endpoints