The Reverse ASIN Lookup API

Authentication

Every request carries Authorization: Bearer <token>. The token is your SmartKDP session token, or a device token minted from your account with a connect code (the same way the browser extension connects) — device tokens are listed and revocable from your account's device list. There are no separate API keys; if your team needs standing credentials, a device token is the supported path.

Endpoints

• POST /research/reverse-asin

  Start a run (1–5 ASINs, marketplace, optional variation scope). Answers 202 with the run id and your remaining quota.

• GET /research/reverse-asin/{run_id}/events

  The live stream (SSE): meta, rows as they verify, progress, an honest summary, done. Reconnect with Last-Event-ID.

• GET /research/reverse-asin/{run_id}

  The persisted run resource. 404 until the run finalizes — poll this after the stream, not instead of it.

• POST /research/reverse-asin/{run_id}/verify

  Re-verify one keyword in place (uses one probe from your allowance).

• POST /research/reverse-asin/{run_id}/deep-sweep

  Launch a background deep sweep that checks the run's unprobed candidates. It takes a few minutes, and only the probes it actually runs count against your allowance. Answers 202 with a job id and the result run's id.

• GET /research/reverse-asin/deep-sweep/{job_id}

  The sweep job's status while its result run does not exist yet.

• GET /research/reverse-asin/runs?asin=&marketplace=

  Run history for an ASIN (subscription required).

• GET /research/reverse-asin/trend?asin=&marketplace=

  The two newest runs differenced: measured position deltas always; modeled deltas only when the runs are honestly comparable.

The vocabulary is the contract

Every row states exactly what was checked: a ranked(position, page) row is a measured observation on a live search page with a timestamp; not_in_top_n(n) states exactly how many organic slots were scanned; unprobed means never checked — it is not a rank claim in either direction. Modeled values (volume bands, difficulty, opportunity) arrive separately labeled, always as ranges with a confidence badge, and where evidence is absent the API answers insufficient data rather than inventing an integer. Client code that collapses these distinctions is misreading the data on purpose.

Metering and honesty on refusal

Runs and probes — a probe is one live check of one keyword's search results — meter against your subscription's monthly allowances. You are charged only for the probes a run actually uses, so a run that finishes early gives back what it did not need. Refusals are typed: 429 with a scope for rate windows, 402 with the unlocking products for capability and quota, 409 for a sweep already in flight. A partially served run says partial: true and keeps its leftovers labeled unprobed — the API never renders a thin result as a complete one.

Read the methodology for what is measured, what is modeled, and how to read the bands.