Docs

Batch endpoint (async)

Submit up to 1,000 ASINs or search queries in one call. Receive results via webhook or poll.

`POST /v1/amazon/batch` - Async batch scraping

Submit a list of ASINs or search queries in one HTTP call. The worker processes them in the background and either POSTs the results to a webhook URL you provide or lets you poll for status.

When to use this

You need to scrape 100+ products and don’t want to manage request orchestration yourself
You want fire-and-forget semantics with a webhook callback
You’re building a price-monitoring job that runs periodically across your catalogue

For a handful of ASINs, use the plain product or search endpoints - batch has ~60 s of overhead before processing begins.

Request

POST /api/v1/amazon/batch
Authorization: Bearer asa_live_YOUR_KEY
Content-Type: application/json

{
  "endpoint": "amazon.product",
  "items": [
    { "query": "B09HN3Q81F", "domain": "com" },
    { "query": "B08D6T6BKS", "domain": "com" },
    { "query": "B092RCLKHN", "domain": "com", "language": "es_US" }
  ],
  "webhook_url": "https://your.server/webhooks/amazon-scrapes"
}

Body parameters

Param	Type	Required	Description
`endpoint`	`"amazon.product"` OR `"amazon.search"`	✅ yes	Which endpoint to call for each item
`items`	array (1-1000)	✅ yes	Each item = same shape as the query string params you’d pass to the sync endpoint
`webhook_url`	string (https)	-	If set, we POST the completed results here when all items are done. Must be a public URL.

Response (201)

{
  "id": "8a1f3b76-2e4c-4a7f-b9e2-1c9d3e5f7a8b",
  "status": "pending",
  "total_count": 3,
  "created_at": "2026-04-20T14:32:01.000Z",
  "webhook_signature_secret": "whsec_abcd1234...",
  "poll_url": "/api/v1/amazon/batch/8a1f3b76-2e4c-4a7f-b9e2-1c9d3e5f7a8b"
}

Save webhook_signature_secret now. It’s only returned once - use it to verify webhook POSTs are genuine.

Processing

Our worker runs every 60 s and processes up to 100 items per run across all pending batches. A 1,000-item batch typically completes within 10-12 minutes.

Each item is dispatched through the same pipeline as the sync endpoints (same auth, same billing, same retries). Only successful (2xx) items are billed.

Polling status

GET /api/v1/amazon/batch/8a1f3b76-2e4c-4a7f-b9e2-1c9d3e5f7a8b
Authorization: Bearer asa_live_YOUR_KEY

{
  "id": "8a1f3b76-...",
  "status": "running",          // "pending" | "running" | "complete" | "failed"
  "endpoint": "amazon.product",
  "total_count": 3,
  "processed_count": 2,
  "success_count": 2,
  "failure_count": 0,
  "credits_charged": 2,
  "started_at": "2026-04-20T14:32:42.000Z",
  "completed_at": null,
  "webhook_url": "https://your.server/webhooks/amazon-scrapes",
  "webhook_delivered_at": null,
  "results": [
    { "input": { "query": "B09HN3Q81F", ... }, "status": "ok", "http_status": 200,
      "data": { /* full product JSON */ }, "duration_ms": 2851, "credits_charged": 1 },
    { "input": { "query": "B08D6T6BKS", ... }, "status": "ok", "http_status": 200,
      "data": { /* full product JSON */ }, "duration_ms": 3120, "credits_charged": 1 }
  ]
}

Webhook payload

Once all items complete, we POST to your webhook_url:

POST https://your.server/webhooks/amazon-scrapes
Content-Type: application/json
X-ASA-Batch-Id: 8a1f3b76-...
X-ASA-Event: batch.completed
X-ASA-Signature: sha256=<hmac-hex>

Body is identical to the GET /batch/{id} response.

Verifying the signature (Node.js)

import crypto from "node:crypto";

function verifyWebhook(req, secret) {
  const sig = req.headers["x-asa-signature"]; // "sha256=<hex>"
  const expected = `sha256=${crypto.createHmac("sha256", secret).update(req.rawBody).digest("hex")}`;
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Verifying in Python

import hmac, hashlib

def verify_webhook(signature_header: str, raw_body: bytes, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)

Retry policy

If your webhook returns non-2xx, we retry up to 5 times with backoff (1min → 2min → 5min → 15min → 1h), then stop. Check webhook_delivery_status and webhook_last_error on the batch row.

Billing

Each item is billed independently per the normal rules. If 800 of 1,000 items succeed, you pay $0.40 (800 × $0.0005). Failed items cost nothing.

Limits

1,000 items per batch
No limit on concurrent batches per account
Worker processes ~100 items / minute globally - sustained throughput for a single batch is ~6,000 items/hour

POST /v1/amazon/batch - Async batch scraping