API reference

The ListingLens API lets you programmatically submit Amazon listings for analysis and retrieve structured results. Results are stored permanently and retrievable by report ID.

Authentication

Authenticate by passing your API key in the Authorization header as a Bearer token.

Authorization: Bearer ll_live_sk_a1b2c3d4e5f6...

Submit a listing for analysis

Submits an Amazon listing URL for full 4-agent analysis. Returns immediately with a reportId — use this to poll GET /api/results/:id or connect to the SSE stream.

Request body

cURL example

curl -X POST https://api.listinglens.com/v1/analyse \
  -H "Authorization: Bearer ll_live_sk_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.amazon.com/dp/B08N5WRWNW",
    "agents": ["visual", "reviews", "ai_search", "benchmark"]
  }'

Response

{
  "reportId": "rpt_abc123xyz",
  "status": "running",
  "asin": "B08N5WRWNW",
  "estimatedSeconds": 90
}

Retrieve a completed report

Returns the full structured report for a given reportId. Reports are stored permanently — there is no expiry.

Report object

Agent result object

Subscribe to live agent events

Opens a Server-Sent Events stream that emits real-time agent progress events. The stream closes automatically once synthesis_complete is emitted.

Event types

JavaScript example

// 1. Submit the listing
const res = await fetch('https://api.listinglens.com/v1/analyse', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://amazon.com/dp/B08N5WRWNW' }),
});
const { reportId } = await res.json();

// 2. Connect to the SSE stream
const source = new EventSource(`https://api.listinglens.com/v1/stream/${reportId}`);

source.addEventListener('synthesis_complete', async (e) => {
  const { reportId } = JSON.parse(e.data);
  source.close();
});

Status codes

Rate limits

Rate limits are applied per API key. When a limit is exceeded, the response includes a Retry-After header.