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] …" }
  ],
  "auditedAt": "2026-08-11T14:02:31.000Z",
  "quota": { "used": 41, "limit": 500 }
}

Scores come from a live pull of the listing (not a cached copy) graded by the same audit engine as the web app — some checks are automated, others use AI assessment. auditedAt is when that grading actually happened, which isn't always "now": if the listing hasn't changed since your last audit of it, this returns that existing result instead of paying for a new one (unchanged: true), and auditedAt reflects the original run.

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

Reads back audits this account has already run, whether 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, so 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, since 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, since 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, since 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.