Audit Any Listing Programmatically

POSThttps://amazonseoranking.com/api/v1/audit

Authenticate with Authorization: Bearer asr_live_…. Body takes an asin (10-character ASIN or an amazon.* product URL) and an optional marketplace code (default US; same 19 marketplaces as the app). Each call spends one audit from your monthly quota.

Request

curl -X POST https://amazonseoranking.com/api/v1/audit \
  -H "Authorization: Bearer asr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asin": "B0CJCJTVZ2", "marketplace": "US"}'

Response

{
  "asin": "B0CJCJTVZ2",
  "marketplace": "US",
  "product": { "title": "…", "brand": "…", "url": "…" },
  "score": 72,
  "categories": [
    { "category": "Title & Item Highlights", "score": 60 },
    { "category": "Bullet Points", "score": 80 }
  ],
  "recommendations": [
    { "priority": "high", "text": "[Title] …" }
  ],
  "quota": { "used": 41, "limit": 500 }
}

GEThttps://amazonseoranking.com/api/v1/audits

Reads back audits this account has already run — from the web app, Bulk Optimization, and the API alike. Spends no quota: these audits were paid for when they ran. Optional asin and marketplace filters, limit up to 200 (default 50), and cursor for paging. Newest first.

curl "https://amazonseoranking.com/api/v1/audits?asin=B0CJCJTVZ2&limit=50" \
  -H "Authorization: Bearer asr_live_YOUR_KEY"

{
  "audits": [
    {
      "asin": "B0CJCJTVZ2",
      "marketplace": "US",
      "productTitle": "…",
      "score": 72,
      "auditedAt": "2026-07-28T09:12:04.000Z"
    }
  ],
  "nextCursor": "412"
}

Pass the nextCursor from a response back as ?cursor= for the next page. It's null once you've reached the end.

Rate limits

Up to 20 requests per minute and 300 per hour, counted per account rather than per key — issuing more keys doesn't raise the ceiling. Going over returns 429 RATE_LIMITED with a Retry-After header telling you how many seconds to wait.

Errors

Every error returns a JSON error string for humans and a stable code for your code to branch on. Branch on code — the wording of error can change.

{
  "error": "Monthly audit limit reached (500). Resets on the 1st.",
  "code": "QUOTA_EXCEEDED"
}

• MISSING_TOKEN / INVALID_KEY (401) — no bearer token, or the key is unknown or revoked.
• PLAN_REQUIRED (403) — the key is valid but its account no longer includes API access.
• INVALID_ASIN / INVALID_MARKETPLACE / INVALID_BODY (400) — the request never runs, so no quota is spent.
• RATE_LIMITED (429) — too fast. Retry after the seconds in Retry-After.
• QUOTA_EXCEEDED (429) — monthly audits used up. Its Retry-After counts down to the 1st, so don't confuse it with the one above.
• UPSTREAM_ERROR (502) — the listing couldn't be fetched or graded. The audit is refunded to your quota.

Notes

• Scores are identical to the web app — the API shares the exact audit engine.
• Audited listings also appear in your History and are covered by score monitoring.
• A failed audit is never charged — quota is refunded automatically.
• Call this server-side. There are no CORS headers, so browser requests are blocked by design — an API key in front-end code is a key anyone can read.
• Keys are shown once at creation and stored only as a hash — revoke and recreate if lost.