API documentation
Amazon (11 marketplaces: US, UK, DE, FR, IT, ES, JP, CA, MX, BR, AU) & Walmart product data — single-ASIN lookups (by ASIN or any barcode), multi-seller offers, curated product search, warehouse filtering, live offers pages, live Amazon Today’s Deals and live Amazon search-results (SERP) fetches. Served from the warehouse in milliseconds or scraped live. Interactive reference →
Three layers, one key and one credit grammar: warehouse product data (/v1/product, /v1/search, /v1/shopping, batches — price, BSR, rating, seller and buy-box history), live Amazon & Walmart (mode=live, /v1/offers, /v1/serp, /v1/bestsellers, /v1/deals, /v1/seller) and, since 2026-10-05, derived intelligence — brand dossiers, seller maps, operator footprints, category landscapes and ranked lists computed from our own observations.
On this page
Base URL & auth
https://api.logimu.com
Send your key in the X-API-KEY header, or as a standard bearer token
(Authorization: Bearer sk_live_...) 2026-10-07 —
both work on every endpoint, the MCP connector included; when both headers are sent, X-API-KEY wins.
Get a key from $19/month (14-day money-back) at sign up.
MCP connector from Claude (claude.ai, desktop, mobile): sign in instead of a key 2026-10-15. Add https://api.logimu.com/mcp as a custom connector (Settings → Connectors → Add custom connector). With a Logimu plan, choose Sign in now under Authentication and keep Use Claude’s published identity under OAuth client, then sign in with your Logimu account and allow: every tool call is metered on your plan exactly like a call with your key (OAuth 2.1 with PKCE; the connector never sees the key; disconnect in Claude to revoke). Keep the pre-selected No sign-in for the free tools without an account. Claude cannot change this choice later: remove the connector and add it again. Clients that can send headers (Claude Code: claude mcp add --transport http logimu https://api.logimu.com/mcp --header "Authorization: Bearer sk_live_…", Cursor, VS Code) keep working with the key.
curl "https://api.logimu.com/v1/product?asin=B0BDHQSZCV" \ -H "X-API-KEY: sk_live_..." curl "https://api.logimu.com/v1/product?asin=B0BDHQSZCV" \ -H "Authorization: Bearer sk_live_..."
Credits
| Call | Credits |
|---|---|
| Curated product search (/v1/shopping) | 2 per query |
| Curated search, detailed (/v1/shopping?detail=true) — everything the basic product answer carries, attached to every product (sellers with fulfillment & delivery, 30-day events, stock history, brand stats, dimensions, deal/badge/rating history, variation coverage, page content, up to 50 featured reviews), plus a response-wide seller_ratings array | 5 per query |
| Product (/v1/product) — from the warehouse, everything included 2026-09-27 snapshot + every intelligence and content block: full price-change timeline + 30-day events, bought-past-month (+ its history), every current offer with seller IDs, fulfilment and delivery, seller feedback, brand stats, dimensions, deal history, rating history, variation coverage, description, images, reviews. Same price as a batch row. | 0.5 |
| ↳ + history 2026-10-10 — BSR rank history (bsr_history=true, back to Oct 2023) and/or the buy-box timeline, per-seller prices and the daily buy-box price (offer_history=true); every seller listed, point series for the 10 most-observed sellers, 500 points each | included — a full warehouse record with both histories is 0.5 |
| ↳ wider series (history_sellers up to 50, history_points up to 20,000) | included |
| ↳ live scrape instead of the warehouse (mode=live, or auto past your max age) | 1, history included |
| ↳ history only 2026-10-10 (history_only=true) — the stored series alone: bsr_history, offer_history and buybox_price_history, no snapshot, content or seller table; Amazon, stored observations only — details | 0.05 |
| ↳ Walmart from the warehouse | 0.5 |
| ↳ Walmart live 2026-10-18 — the walmart.com product page read now (mode=live, or auto past your max age) — details a partial page, an item walmart.com does not have and a failed or busy fetch are never billed | 2 |
| ↳ by barcode instead of ASIN (gtin=) 2026-10-12 — any UPC / EAN / GTIN / ISBN-13, resolved from our observations, the same product on another Amazon marketplace, or Amazon’s own search — details a barcode nothing resolves is a 404 and is never billed | included |
| Warehouse filter search (/v1/search) | 1 per 25 results, every marketplace |
| Live Amazon search results (/v1/serp) — a real live fetch, seconds not ms billed per page actually fetched (request_metadata.pages_fetched), never per page requested — max_page=5 can stop at 2 when Amazon runs out of results; blocked fetches (502) and zero-result answers are never billed | 1 per page fetched |
| ↳ Walmart search results (/v1/serp?country=walmart) 2026-10-18 — walmart.com’s search page, live, up to 3 pages a call — details per results page returned; an empty result set, a failed fetch (502) and a busy refusal (503) are never billed | 2 per page |
| Amazon Best Sellers list (/v1/bestsellers) 2026-10-09 — a category’s current top 100 with its breadcrumb name and subcategories, fetched live (or from our cache, up to 30 min old) per page of 50 products returned, cached or fresh — the full top 100 is 2; the root list of top-level categories is free; a category Amazon does not have, a blocked fetch and an empty list are never billed | 1 per page of 50 · root list 0 |
| Amazon Today’s Deals (/v1/deals) 2026-10-18 — a marketplace’s deals page, fetched live (or from our cache, up to 15 min old), filtered by department, deal type, discount, price, Prime Exclusive, rating or brand per deals page fetched that returned at least one deal, cached or fresh — any page size is 1 credit, so page_size=120 is 120 deals for 1 credit; a page with no deals, an empty list, a blocked fetch and a busy marketplace are never billed | 1 per page fetched (up to 120 deals) |
| Offers page (/v1/offers) 2026-10-12 — every offer on Amazon’s offers page, fetched live: seller, price, shipping, condition, buy box, FBA / Prime, delivery, the sellers’ feedback — no product page per product whose offers page lists at least one offer (any condition); a product with no offer right now, an ASIN Amazon does not have, a blocked fetch and a busy marketplace are never billed | 0.5 |
| ↳ as seen from a US ZIP (zip=) 2026-10-14 — the page as a shopper at that ZIP sees it, with location and deliverable (Amazon Fresh / Whole Foods delivery areas), page 1 only (details) a ZIP Amazon rejects, no offer there, not found and a failed fetch are never billed | 1 |
| Product tracking (/v1/track, /v1/product?track=true) 2026-10-14 — pin an ASIN into our hot lane: its offers page is re-read hourly or every 2 / 4 / 12 / 24 h for as long as the plan is active, every read lands in the product’s sub-daily buy-box history, and e-mail / webhook alerts fire on the thresholds you set 0 credits; each plan carries a daily allowance of tracked snapshots (Solo 2,500 · Starter 6,000 · Growth 18,000 · Standard 40,000 · Scale 170,000 · Volume 710,000); reading the history stays 0.05 (history_only) or 0.5 (the record) | 0 |
| Seller profile (/v1/seller) 2026-10-04 — star rating, feedback per period, histogram, up to 5 recent feedback entries, tracking (since when and how often we have observed the seller) and, where the seller publishes them, business name and address — all included mode=auto bills what was served: 0.5 from our stored observation, 1 when it went live | 1 live · 0.5 stored |
| ↳ + history — the seller’s rating change points and storefront-size points since we first observed it (history=true) 2026-10-05 once per call, only when at least one point comes back; an empty history is free | +0.5 |
| Seller’s products (/v1/seller/products) 2026-10-04 live storefront: per page actually fetched, like /v1/serp; warehouse: the products we observed the seller offering, 25 per page, like /v1/search | 1 per storefront page fetched · 1 per page of 25 observed products |
| Brand dossier (/v1/brand) · brand seller map (/v1/brand/network) · connected sellers (/v1/seller/network) · category landscape (/v1/category) 2026-10-05 derived from our observations; history=true on brand / seller-brands / category adds up to 24 months for +0.5 once, only when it comes back non-empty | 1 per record · +0.5 with history |
| Who sells a brand (/v1/brand/sellers) · operator footprint (/v1/seller/brands) · ranked lists (/v1/brands/movers, /v1/brands/top, /v1/sellers/movers, /v1/sellers/top, /v1/categories/top) 2026-10-05 25 rows per page; an empty page is free; each key has a daily cap on the derived family (2,000 calls by default — ask us for more) | 1 per page of 25 |
| Category lookup (/v1/categories/search) 2026-10-05 | 0 |
| Category taxonomy (/v1/categories — roots, or one category’s children) 2026-10-07 — any key, every plan | 0 |
| Keyword suggestions (/v1/keywords) — Amazon’s own autocomplete suggestion lists for a seed, every term with its position within its list, first / last observed, and the marketplaces it was observed in, plus related observed vocabulary 2026-10-07 observed suggestion ranking since Aug 2026 — no volume figures (Amazon publishes none); for the products on page 1 of a search see /v1/keywords/rankings; a seed with no observations is a free 404 | 1 per seed |
| ↳ + history — every observation of each returned list since the harvest began: terms entering, leaving or moving (history=true) only when at least one closed observation exists; a list that never changed is free | +0.5 |
| Keyword vocabulary across marketplaces (/v1/keywords/compare) — the seed’s primary list on 2–11 marketplaces and the position matrix 2026-10-07 | 1 per call |
| Keyword rankings (/v1/keywords/rankings) — page 1 of Amazon US search for a keyword as last observed (about once a week): the organic order with product facts and buy boxes, the sponsored units in the page, the Overall Pick badge, Amazon’s result count and who holds the page, dated 2026-10-18 paid plans; observed positions, no volume figures; a keyword not in the observed set (or not observed yet) is a free 404 | 1 per keyword |
| ↳ + history — every stored observation of the keyword and the rank series of the products on the latest page (history=true) only when more than the latest observation exists | +0.5 |
| Keywords for a product (/v1/product/keywords) — reverse ASIN: every observed keyword whose latest page 1 shows the product, organically with its rank or in a sponsored unit; asins= compares up to 10 products 2026-10-18 paid plans; a product not seen on any observed page is a free 404; history=true adds the product’s rank on each keyword over time (+0.5 once when any keyword has more than one observation) | 1 per 25 keywords returned, per ASIN |
| Partial scrape, not found, empty storefront, blocked or suppressed seller, failed, or rate-limited you are never charged for a request that did not return what you asked for, and plan credits are a monthly allowance that renews with your billing cycle (top-up credits stay usable for 90 days) | 0 — never billed |
Every Amazon marketplace costs the same. Warehouse vs live is chosen per request with
mode and max_age_days (below).
GET /v1/shopping curated search
Keyword in, ranked product recommendations out — in under 100 ms. Broad queries come back grouped by product category; specific ones by Budget / Mid-range / Premium price tier. Within each group our ranking selects the strongest products using Amazon-reported sales, ratings, review counts, and seller and brand signals.
| Param | Notes |
|---|---|
| q | required — the search query. A bare ASIN (or numeric Walmart item ID) returns exactly that product (mode: "asin"). On Amazon its price, rating, review_count, seller_count, in_stock and bought_past_month are the values /v1/product returns for that ASIN at the same moment 2026-10-21. |
| country | us (default), uk, de, ca, au, fr, it, es, jp, mx, br — 11 Amazon marketplaces — plus walmart (Walmart US, numeric item ID) |
| category | optional — keyword filter on the product-category path. Matched against the full path including all parent categories, with singular/plural folding (and German inflection on de). q=coffee maker&category=machine keeps only categories whose path mentions Machine(s); multiple words must all appear. Matching uses word-stem folding (powered ↔ power), max 200 characters. An unmatchable value returns total: 0 — never billed. Prefer broad category words: a filter that excludes every strong match can surface weaker description-level matches rather than an empty set. |
| group | optional — force category, price, or none; default auto. none 2026-10-18 returns one flat ranked list drawn from the categories that name the product (laptop lists laptops, not laptop bags; eggs lists eggs, not egg cookers). When no category names the product, the list ranks every match. |
| format 2026-09-30 | optional, books and media — only this format: kindle, paperback, hardcover, mass_market, audiobook, audio_cd, board_book, spiral, library_binding, other; comma-separate several (format=paperback,hardcover). Applied before collapse, so each row is the requested format of its book. A marketplace without format data yet returns no results with a note saying so (not billed). For used copies of a format, take the ASINs to /v1/product with include_used=true, or a batch with include: ["used"]. |
| collapse 2026-09-30 | optional — true (default): one row per book. The best-matching format represents the book, and its other formats (each its own ASIN, with price) are in the row’s formats, alongside format_norm and family_asin. false: every format as its own row (the behaviour before 2026-09-30). Products without format data are never collapsed. |
| include_unavailable 2026-09-26 | optional — false (default) returns only products with a current offer: a price observed in the activity window. true also returns listings we know but that currently have no offer on the marketplace (Amazon “Currently unavailable”: price: null, in_stock: false). A bare ASIN in q always returns that product regardless of this flag; use /v1/product for its history. |
| q | required — keywords, a bare ASIN, or a bare barcode (UPC/EAN/GTIN, 8–14 digits). An ASIN or barcode returns the product(s) it identifies rather than a keyword search. A barcode can map to several ASINs: gtin_matches lists every ASIN we have mapped to it and gtin_match_count counts them, while results carries the ones we hold current data for — so a 3-match barcode can legitimately return fewer than 3 products. Barcodes are not accepted for country=walmart, where a numeric query is an item ID. |
| sort | optional — relevance (default), price, rating. When grouping is active (the default), results is a concatenation of the per-group lists — each group is sorted internally, but the flat array is not globally sorted. Pass group=none for a globally sorted flat list. |
| detail 2026-09-28 | optional — true attaches to every product everything the basic /v1/product answer carries: current_sellers (each seller with fulfillment, delivery_*, condition), the fulfillment block, 30-day price/stock change events, stock_history / stock_state, brand_stats, dimensions, deal_history, bought_past_month_history, rating_history, variation_coverage, page content (images, feature_bullets, breadcrumbs, variations, description) and reviews (up to 50), authors / author, every seller row carrying its seller_rating feedback record — plus a response-wide seller_ratings array. Only bsr_history and offer_history stay product-only (included in the record there, no extra credits). Up to 40 products per response get the block. 5 credits per query instead of 2; response takes a few seconds. bought_past_month needs no flag — it is included on every product in every response. |
curl "https://api.logimu.com/v1/shopping?q=toothbrush&country=us" \\ -H "X-API-KEY: sk_live_..."
{
"query": "toothbrush", "country": "us", "currency": "USD",
"total": 1549, "mode": "category",
"groups": [ { "category": "\u2026 > Powered Toothbrushes", "count": 110,
"products": [ { "asin": "B072YVWBXH", "product_id": "B072YVWBXH",
"product_url": "https://www.amazon.com/dp/B072YVWBXH",
"title": "Aquasonic \u2026", "brand": "Aquasonic",
"price": 35.95, "rating": 4.6, "review_count": 136657, "in_stock": true,
"bought_past_month": 7000,
"upc": "842776104423",
"image_url": "https://\u2026", "amazon_url": "https://www.amazon.com/dp/B072YVWBXH",
"observed_at": "2026-07-22T16:03:48Z" } ] } ],
"facets": { "brands": [ {"value":"Oral-B","count":102,"avg_rating":4.56,"est_monthly_sold":14109} ] },
"credits_charged": 2, "credits_remaining": 2498
}
When nothing matches every term 2026-10-09: the answer is relaxed instead of empty, and says so: match: "relaxed", dropped_terms (as typed) and a note naming them and why. Terms that match no product go first; then, in an ALL-CAPS query, 1–2 letter words without digits (distributor shorthand such as MO; 4K or 2M stay); then at most two more terms. A query that matches as typed is never relaxed, and a relaxed answer is not billed. /v1/search does the same against the whole catalogue.
Books 2026-09-30: a query that is an author’s name (“tolkien”, “stephen king”) returns only that author’s books, and the response carries author_match (the matched author names). Words that are mostly something else (“rice”, “king”) are not treated as authors. Book rows carry author, and where we hold format data, format_norm, family_asin and formats (see collapse). Both fill in as book pages are re-observed from 2026-10-01.
Sample response — detail=true 2026-09-28 — the same call with &detail=true, a real answer; one group with one product shown, its detail block complete except reviews (3 of 21 kept), images (3 of 12) and the stock/price series (6 points each) shortened for display; seller_ratings filtered to the sellers this product names. Every product in the response carries the same block (up to 40).
{
"query": "toothbrush",
"country": "us",
"currency": "USD",
"mode": "category",
"total": 1153,
"detail": true,
"groups": [
{
"category": "Health & Household > Oral Care > Toothbrushes & Accessories > Powered Toothbrushes & Accessories > Powered Toothbrushes > Ultrasonic",
"count": 179,
"products": [
{
"asin": "B0DNMLK6SC",
"product_id": "B0DNMLK6SC",
"product_url": "https://www.amazon.com/dp/B0DNMLK6SC",
"title": "Bitvae ADA Accepted Electric Toothbrush, 60-Day Battery Travel Toothbrush",
"brand": "Bitvae",
"price": 24.99,
"rating": 4.4,
"review_count": 13908,
"in_stock": true,
"seller_count": 1,
"is_fba": true,
"image_url": "https://m.media-amazon.com/images/I/719Qwh9HkEL._AC_SY355_.jpg",
"category": "Health & Household > Oral Care > Toothbrushes & Accessories > Powered Toothbrushes & Accessories > Powered Toothbrushes > Ultrasonic",
"bought_past_month": 1000,
"observed_at": "2026-09-16T09:55:39Z",
"description": "ADA Approved for a Brighter Smile in Two Weeks: Bitvae D2 electric toothbrush is endorsed by the American Dental Association (ADA) Council on Scientific Affairs for its safety and efficacy in removing plaque and helping to prevent and reduce gingivitis • Daily Use-Friendly 2-in-1 Toothbrush Holder and Cover: This electric toothbrush features a versatile holder that not only keeps your toothbrush clean and hygienic but also doubles as a protective cover, shielding it from dust and water between uses • Sleek and Lightweight Travel Toothbrush: Our rechargeable toothbrush's slim design and lightweight build make packing a breeze; Your Perfect On-the-Go Companion with a 60 days battery life, stay fresh and confident every day, everywhere • 8 Replacement Heads for 2 Years of Use: Transform your smile with our cutting-edge toothbrush heads; Featuring precision-crafted firm bristles at the core for deep cleansing action, soft gumcare bristles at the edges to protect your gums • 5 Modes for Various Oral Care Needs: White, Clean, Soft, Polish, Gum Care; The 5 brushing modes are designed to meet all your oral care needs and help maintain a healthy mouth • 2-Minute Smart Timer & IPX7 Waterproof: This electric toothbrush built-in 2-minute timer control system pulses every 30 seconds to remind you to move on to the next quadrant of your mouth • Package Includes: 1 Bitvae D2 Toothbrush Handle, 8 Toothbrush Heads, 1 USB Cable (Adapter not included—please charge the toothbrush using a 5V-1A adapter), 1 Travel Case & Holder, 1 Instruction Manual\n\nSpecs — Brand Name: Bitvae · Age Range Description: Adult · Included Components: 8 Toothbrush Heads, Travel Case, Toothbrush Holder, USB Cable · Model Name: H1D2 · Target Audience: Unisex-Adults · Manufacturer: Bitvae · Other Special Features of the Product: ADA Approved, Rechargeable, Travel Size, Lightweight , Portable, Customizable, Brushing Timer, 8 Brush Heads, 5 Modes, 60-Day Battery Life, IPX7 Waterproof · Power Source: Battery Powered · Item Firmness Description: Soft · Toothbrush Head Shape: Oval · Operation Mode: Automatic · Number of settings: 5 · Mount Motion: ultrasonic · Number of Items: 1 · Unit Count: 8 Count · Item Dimensions: 7.8 x 0.79 x 0.67 inches · Item Weight: 0.21 kg · Material Features: Recyclable · Bristle Material: Nylon · Handle Material: Plastic · Color: Shadow Black · Product Dimensions: 7.8 x 0.79 x 0.67 inches; 7.37 ounces",
"amazon_url": "https://www.amazon.com/dp/B0DNMLK6SC",
"detail": {
"observed_at": "2026-09-16T09:55:39Z",
"price_changes_30d": [
{
"at": "2026-09-01T14:28:40Z",
"from": 16.12,
"to": 24.99,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-09-05T03:03:40Z",
"from": 24.99,
"to": 19.99,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-09-11T06:11:33Z",
"from": 19.99,
"to": 24.99,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-09-14T20:15:44Z",
"from": 24.99,
"to": 19.99,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-09-15T16:15:54Z",
"from": 19.99,
"to": 24.99,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
}
],
"stock_changes_30d": [],
"price_history": [
{
"at": "2026-05-20T06:09:05Z",
"from": 16.13,
"to": 24.99,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-06-20T20:55:10Z",
"from": 24.99,
"to": 16.24,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-06-25T11:18:16Z",
"from": 16.24,
"to": 19.99,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-07-13T16:06:39Z",
"from": 19.99,
"to": 16.24,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-07-29T03:49:43Z",
"from": 16.24,
"to": 19.99,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
},
{
"at": "2026-08-27T20:39:55Z",
"from": 19.99,
"to": 16.12,
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY"
}
],
"stock_history": [],
"stock_state": "in_stock",
"stock_observed_since": "2026-05-16T08:10:22Z",
"bought_past_month": 1000,
"bought_past_month_raw": "1K+ bought in past month",
"bought_past_month_observed_at": "2026-09-16T09:55:35Z",
"dimensions": {
"weight_raw": "0.21 kg",
"weight_value": 0.21,
"weight_unit": "kg",
"weight_g": 210.0,
"weight_observed_at": "2026-09-16T09:55:35Z",
"dimensions_raw": "7.8 x 0.79 x 0.67 inches",
"length": 7.8,
"width": 0.79,
"height": 0.67,
"unit": "in",
"length_cm": 19.81,
"width_cm": 2.01,
"height_cm": 1.7,
"dimensions_observed_at": "2026-09-16T09:55:35Z",
"observed_at": "2026-09-16T09:55:35Z"
},
"rating_history": {
"points": [
{
"date": "2026-05-16",
"rating_count": 13697,
"rating": 4.4
},
{
"date": "2026-05-20",
"rating_count": 13702,
"rating": 4.4
},
{
"date": "2026-05-28",
"rating_count": 13705,
"rating": 4.4
},
{
"date": "2026-06-02",
"rating_count": 13722,
"rating": 4.4
},
{
"date": "2026-06-07",
"rating_count": 13745,
"rating": 4.4
},
{
"date": "2026-06-11",
"rating_count": 13764,
"rating": 4.4
},
{
"date": "2026-06-16",
"rating_count": 13763,
"rating": 4.4
},
{
"date": "2026-06-20",
"rating_count": 13770,
"rating": 4.4
},
{
"date": "2026-06-25",
"rating_count": 13776,
"rating": 4.4
},
{
"date": "2026-06-30",
"rating_count": 13786,
"rating": 4.4
},
{
"date": "2026-07-04",
"rating_count": 13796,
"rating": 4.4
},
{
"date": "2026-07-09",
"rating_count": 13803,
"rating": 4.4
},
{
"date": "2026-07-13",
"rating_count": 13814,
"rating": 4.4
},
{
"date": "2026-07-20",
"rating_count": 13820,
"rating": 4.4
},
{
"date": "2026-07-25",
"rating_count": 13834,
"rating": 4.4
},
{
"date": "2026-07-29",
"rating_count": 13835,
"rating": 4.4
},
{
"date": "2026-08-05",
"rating_count": 13830,
"rating": 4.4
},
{
"date": "2026-08-09",
"rating_count": 13833,
"rating": 4.4
},
{
"date": "2026-08-14",
"rating_count": 13846,
"rating": 4.4
},
{
"date": "2026-08-27",
"rating_count": 13865,
"rating": 4.4
},
{
"date": "2026-09-01",
"rating_count": 13870,
"rating": 4.4
},
{
"date": "2026-09-05",
"rating_count": 13875,
"rating": 4.4
},
{
"date": "2026-09-11",
"rating_count": 13891,
"rating": 4.4
},
{
"date": "2026-09-13",
"rating_count": 13905,
"rating": 4.4
},
{
"date": "2026-09-14",
"rating_count": 13905,
"rating": 4.4
},
{
"date": "2026-09-15",
"rating_count": 13907,
"rating": 4.4
},
{
"date": "2026-09-16",
"rating_count": 13908,
"rating": 4.4
}
],
"points_total": 27,
"observed_from": "2026-05-16",
"observed_to": "2026-09-16",
"rating_count_first": 13697,
"rating_count_last": 13908,
"rating_last": 4.4,
"ratings_gained_30d": 43,
"ratings_gained_90d": 138,
"notes": "One point per day the product page was observed (rating_count = Amazon's global ratings count, rating = the star average shown); ratings_gained_Nd = the count's growth over the trailing window of observed days. Observed since we started tracking this listing."
},
"bought_past_month_history": {
"segments": [
{
"from": "2026-05-16",
"to": "2026-05-20",
"days_observed": 2,
"bought_past_month": 2000,
"raw": "2K+ bought in past month"
},
{
"from": "2026-05-28",
"to": "2026-06-02",
"days_observed": 2,
"bought_past_month": 1000,
"raw": "1K+ bought in past month"
},
{
"from": "2026-06-07",
"to": "2026-07-13",
"days_observed": 9,
"bought_past_month": 2000,
"raw": "2K+ bought in past month"
},
{
"from": "2026-07-20",
"to": "2026-07-25",
"days_observed": 2,
"bought_past_month": 1000,
"raw": "1K+ bought in past month"
},
{
"from": "2026-07-29",
"to": "2026-09-15",
"days_observed": 11,
"bought_past_month": 2000,
"raw": "2K+ bought in past month"
},
{
"from": "2026-09-16",
"to": "2026-09-16",
"days_observed": 1,
"bought_past_month": 1000,
"raw": "1K+ bought in past month"
}
],
"segments_total": 6,
"days_observed": 27,
"observed_from": "2026-05-16",
"observed_to": "2026-09-16",
"max": 2000,
"notes": "One segment per run of consecutive product-page observations with the same badge (bought_past_month = the floor of Amazon's bucket, raw = the badge text). null = the page was observed WITHOUT a badge (Amazon badges only higher-velocity listings); a day absent from every segment was not observed on the product page."
},
"deal_history": {
"segments": [
{
"from": "2026-05-16",
"to": "2026-05-16",
"days_observed": 1,
"list_price": 19.99,
"savings_amount": 3.86,
"savings_percent": 19,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-05-20",
"to": "2026-05-20",
"days_observed": 1,
"list_price": 24.99,
"savings_amount": null,
"savings_percent": null,
"coupon_text": "Save 30% at checkout Shop items",
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": 30.0
},
{
"from": "2026-05-28",
"to": "2026-06-07",
"days_observed": 3,
"list_price": 24.99,
"savings_amount": null,
"savings_percent": 20,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-06-11",
"to": "2026-06-20",
"days_observed": 3,
"list_price": 24.99,
"savings_amount": null,
"savings_percent": 35,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-06-25",
"to": "2026-07-09",
"days_observed": 4,
"list_price": 24.99,
"savings_amount": null,
"savings_percent": 20,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-07-13",
"to": "2026-07-25",
"days_observed": 3,
"list_price": 24.99,
"savings_amount": null,
"savings_percent": 35,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-07-29",
"to": "2026-07-29",
"days_observed": 1,
"list_price": 24.99,
"savings_amount": null,
"savings_percent": 20,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-08-05",
"to": "2026-08-14",
"days_observed": 3,
"list_price": 24.99,
"savings_amount": 5.0,
"savings_percent": 20,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-08-27",
"to": "2026-08-27",
"days_observed": 1,
"list_price": 19.99,
"savings_amount": 3.87,
"savings_percent": 19,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-09-01",
"to": "2026-09-01",
"days_observed": 1,
"list_price": 49.95,
"savings_amount": 24.96,
"savings_percent": 50,
"coupon_text": "Save 20% at checkout Terms",
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": 20.0
},
{
"from": "2026-09-05",
"to": "2026-09-05",
"days_observed": 1,
"list_price": 24.99,
"savings_amount": 5.0,
"savings_percent": 20,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-09-11",
"to": "2026-09-11",
"days_observed": 1,
"list_price": null,
"savings_amount": null,
"savings_percent": null,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-09-13",
"to": "2026-09-13",
"days_observed": 1,
"list_price": 27.99,
"savings_amount": 3.0,
"savings_percent": 11,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-09-14",
"to": "2026-09-14",
"days_observed": 1,
"list_price": 24.99,
"savings_amount": 5.0,
"savings_percent": 20,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-09-15",
"to": "2026-09-15",
"days_observed": 1,
"list_price": null,
"savings_amount": null,
"savings_percent": null,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
},
{
"from": "2026-09-16",
"to": "2026-09-16",
"days_observed": 1,
"list_price": 49.95,
"savings_amount": 24.96,
"savings_percent": 50,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null
}
],
"segments_total": 16,
"days_observed": 27,
"observed_from": "2026-05-16",
"observed_to": "2026-09-16",
"days_with_list_price": 25,
"days_with_coupon": 2,
"list_price_suppressed_days": 0,
"list_price_hidden_days": 0,
"list_price_unstable_days": 0,
"current": {
"list_price": 49.95,
"savings_amount": 24.96,
"savings_percent": 50,
"coupon_text": null,
"coupon_expires": null,
"coupon_amount": null,
"coupon_percent": null,
"as_of": "2026-09-16"
},
"notes": "List price (the strikethrough 'List:' / 'Was:' figure), Amazon's shown savings, and the coupon or promotion text as printed on the product page, one segment per run of consecutive observations with identical values; coupon_amount / coupon_percent are parsed from that text (null when it carries no figure). null fields = not shown on the page that day; 'current' = the latest observed segment. A list price 20x or more above that day's price is a parser artefact and is served as null (list_price_suppressed_days); a list price at or below that day's price is no discount, so it and that day's savings are served as null (list_price_hidden_days). A list price is served only when it is consistent: at least 60% of the product-page observations within 7 days either side of it carry a list price within 10% of it; otherwise the page's list-price field was flipping between unrelated values (another variation's or another widget's price) and that day's list price and savings are served as null (list_price_unstable_days). The check reads the days after an observation too, so the verdict for the latest week can change as new observations arrive."
},
"variation_coverage": {
"parent_asin": "B0BHNYQ2VC",
"is_variation_child": true,
"variation_count": 1,
"dimension_names": [
"color_name"
],
"children_total": 1,
"children_tracked": 1,
"children_tracked_pct": 100.0,
"children_with_price_30d": 1,
"children_available": 1,
"children_listed": 1,
"children_truncated": false,
"children": [
{
"child_asin": "B0DNMLK6SC",
"dimension_values": {
"color_name": "Shadow Black"
},
"is_available": true,
"is_this_asin": true,
"tracked": true,
"last_observed_at": "2026-09-16T09:55:39Z",
"price_30d": 24.99,
"price_30d_observed_at": "2026-09-16T09:55:39Z"
}
],
"matrix_observed_at": "2026-09-16T09:55:35Z",
"notes": "Coverage of the variation matrix as last observed on the product page (current state, not history): children_tracked = child ASINs with at least one observation of their own on this marketplace, the rest are known only as matrix entries; price_30d = the child's latest observed price in the last 30 days (null = not observed in that window); is_available is the matrix's own flag at matrix_observed_at. An empty matrix on a listing without variants is normal."
},
"current_sellers": {
"as_of": "2026-09-16T09:55:39Z",
"offer_count": 1,
"buybox_seller": "Bitvae",
"conditions_included": "new_only",
"used_offer_count": 0,
"buybox_days_observed_30d": 26,
"buybox_observations_total_30d": 41,
"lowest_new": {
"price": 24.99,
"condition": "New",
"condition_class": "new",
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY",
"is_fba": true,
"is_prime": false,
"fulfillment": "FBA",
"seller_rating": {
"positive_pct": 98.0,
"feedback_count": 5923,
"rating": null,
"observed_at": "2026-09-19T09:18:23Z"
}
},
"lowest_used": null,
"sellers": [
{
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY",
"price": 24.99,
"is_buybox": true,
"is_fba": true,
"is_prime": false,
"seller_positive_pct": 98.0,
"seller_feedback_count": 5923,
"buybox_days_30d": 7,
"buybox_share_30d": 27,
"buybox_observations_30d": 11,
"buybox_observation_share_30d": 26.8,
"ships_from": "Amazon.com",
"shipping_cost": 0.0,
"condition": "New",
"condition_class": "new",
"fulfillment": "FBA",
"delivery": {
"text": "FREE delivery September 22 - 23 on orders shipped by Amazon over $35 Or fastest delivery Monday, September 21",
"free": true,
"days_min": 6,
"days_max": 7,
"fastest_days": 5,
"date_min": "2026-09-22",
"source": "nightly",
"observed_at": "2026-09-16T07:55:39Z"
},
"delivery_eta_days": 6,
"delivery_eta_fastest_days": 5,
"seller_rating": {
"positive_pct": 98.0,
"feedback_count": 5923,
"rating": null,
"observed_at": "2026-09-19T09:18:23Z"
}
}
]
},
"brand_stats": {
"brand": "Bitvae",
"products_tracked": 10,
"avg_rating": 4.41,
"total_ratings": 102498,
"in_stock_pct": 100.0,
"distinct_buybox_sellers": 1,
"top_buybox_sellers": [
{
"seller": "Bitvae",
"products": 8
}
]
},
"fulfillment": {
"buybox": "FBA",
"buybox_seller": "Bitvae",
"buybox_seller_id": "A1JHU3BZ1D3UVY",
"ships_from": "Amazon.com",
"is_prime": false,
"offers": {
"amz": 0,
"fba": 1,
"fbm": 0,
"total": 1
},
"amazon_sells": false,
"amazon_holds_buybox": false,
"buybox_delivery": {
"text": "FREE delivery September 22 - 23 on orders shipped by Amazon over $35 Or fastest delivery Monday, September 21",
"free": true,
"days_min": 6,
"days_max": 7,
"fastest_days": 5,
"date_min": "2026-09-22",
"source": "nightly",
"observed_at": "2026-09-16T07:55:39Z"
},
"buybox_delivery_eta_days": 6,
"dispatch_latency": null,
"dispatch_days_min": null,
"dispatch_days_max": null,
"delivery_eta_source": "offer",
"observed_at": "2026-09-16T09:55:39Z",
"source": "cache",
"notes": "buybox is the buy-box winner's fulfilment: AMZ = sold by Amazon itself, FBA = a third party fulfilled by Amazon, FBM = merchant-fulfilled. Counts cover the offers listed in current_sellers. Delivery days are read from Amazon's own delivery sentence at the time of the observation, in whole days from that date; ranges give min/max, fastest_days is the paid/Prime fast option when shown. Not billed extra."
},
"description": "ADA Approved for a Brighter Smile in Two Weeks: Bitvae D2 electric toothbrush is endorsed by the American Dental Association (ADA) Council on Scientific Affairs for its safety and efficacy in removing plaque and helping to prevent and reduce gingivitis • Daily Use-Friendly 2-in-1 Toothbrush Holder and Cover: This electric toothbrush features a versatile holder that not only keeps your toothbrush clean and hygienic but also doubles as a protective cover, shielding it from dust and water between uses • Sleek and Lightweight Travel Toothbrush: Our rechargeable toothbrush's slim design and lightweight build make packing a breeze; Your Perfect On-the-Go Companion with a 60 days battery life, stay fresh and confident every day, everywhere • 8 Replacement Heads for 2 Years of Use: Transform your smile with our cutting-edge toothbrush heads; Featuring precision-crafted firm bristles at the core for deep cleansing action, soft gumcare bristles at the edges to protect your gums • 5 Modes for Various Oral Care Needs: White, Clean, Soft, Polish, Gum Care; The 5 brushing modes are designed to meet all your oral care needs and help maintain a healthy mouth • 2-Minute Smart Timer & IPX7 Waterproof: This electric toothbrush built-in 2-minute timer control system pulses every 30 seconds to remind you to move on to the next quadrant of your mouth • Package Includes: 1 Bitvae D2 Toothbrush Handle, 8 Toothbrush Heads, 1 USB Cable (Adapter not included—please charge the toothbrush using a 5V-1A adapter), 1 Travel Case & Holder, 1 Instruction Manual",
"description_source": "feature_bullets",
"images": [
"https://m.media-amazon.com/images/I/51daP2PQo1L.jpg",
"https://m.media-amazon.com/images/I/51h2+bu39ML.jpg",
"https://m.media-amazon.com/images/I/512vSssS9FL.jpg"
],
"feature_bullets": [
"ADA Approved for a Brighter Smile in Two Weeks: Bitvae D2 electric toothbrush is endorsed by the American Dental Association (ADA) Council on Scientific Affairs for its safety and efficacy in removing plaque and helping to prevent and reduce gingivitis",
"Daily Use-Friendly 2-in-1 Toothbrush Holder and Cover: This electric toothbrush features a versatile holder that not only keeps your toothbrush clean and hygienic but also doubles as a protective cover, shielding it from dust and water between uses",
"Sleek and Lightweight Travel Toothbrush: Our rechargeable toothbrush's slim design and lightweight build make packing a breeze; Your Perfect On-the-Go Companion with a 60 days battery life, stay fresh and confident every day, everywhere",
"8 Replacement Heads for 2 Years of Use: Transform your smile with our cutting-edge toothbrush heads; Featuring precision-crafted firm bristles at the core for deep cleansing action, soft gumcare bristles at the edges to protect your gums",
"5 Modes for Various Oral Care Needs: White, Clean, Soft, Polish, Gum Care; The 5 brushing modes are designed to meet all your oral care needs and help maintain a healthy mouth",
"2-Minute Smart Timer & IPX7 Waterproof: This electric toothbrush built-in 2-minute timer control system pulses every 30 seconds to remind you to move on to the next quadrant of your mouth",
"Package Includes: 1 Bitvae D2 Toothbrush Handle, 8 Toothbrush Heads, 1 USB Cable (Adapter not included—please charge the toothbrush using a 5V-1A adapter), 1 Travel Case & Holder, 1 Instruction Manual"
],
"breadcrumbs": [
"Health & Household",
"Oral Care",
"Toothbrushes & Accessories",
"Powered Toothbrushes & Accessories",
"Powered Toothbrushes",
"Ultrasonic"
],
"variations": [
{
"child_asin": "B0DNMLK6SC",
"dimension_index": "0",
"dimension_values": {
"color_name": "Shadow Black"
},
"is_selected": 1,
"is_available": 1
}
],
"variation_count": 1,
"parent_asin": "B0BHNYQ2VC",
"content_observed_at": "2026-09-16 11:55:35",
"reviews": [
{
"author": null,
"rating": 5.0,
"title": "Clean and simple",
"date_raw": "Reviewed in the United States on February 5, 2025",
"verified": true,
"is_local": true,
"variant": null,
"body": "I bought this toothbrush in May, 2022 and the battery just stopped working for good on February 3, 2025. I liked it so I’m back here buying another one. The first one lasted a little over two and a half years, which isn’t too bad compared to the longevity versus cost of one of the more expensive “name brand” electric toothbrushes. I do wish these could last longer just for the sake of creating less plastic waste. What I like about this toothbrush is the handle is easy to hold, simple shape, lightweight and easy to clean… It comes with a lot of replacement brush heads. The size of the brush head and bristle softness works well for me. They attach easily and stay on well without rattling. The whole thing is quite durable. I like that it charges with a USB cord (although a plug was not included). I like that it did not come with a charging base – that would only be more plastic waste and I don’t like to leave my toothbrush out on the counter anyway. The cord attaches on the bottom of the handle so the toothbrush lays on its side while charging. The use time between battery charges is pretty long. I never really paid attention to just how long – maybe a month or two? It’s got some different vibration settings but I’m not really sure why. It seems to me they all clean about the same. Here’s something a little weird: Several days before the battery croaked for good, the toothbrush came on all by itself in the middle of the night. That was a little creepy. It wouldn’t turn off until I plugged it in. Then it happened again two nights later. The following morning it wouldn’t run anymore. So maybe that’s what happens when the battery is about to be all done…?",
"helpful_count": 4
},
{
"author": null,
"rating": 5.0,
"title": "Would buy again",
"date_raw": "Reviewed in the United States on September 7, 2026",
"verified": true,
"is_local": true,
"variant": "Color: Shadow Black",
"body": "Pleasantly surprised! I like to change heads more often than most, so this works great for me",
"helpful_count": null
},
{
"author": null,
"rating": 4.0,
"title": "Good value if it works",
"date_raw": "Reviewed in the United States on August 13, 2026",
"verified": true,
"is_local": true,
"variant": "Color: Shadow Black",
"body": "product failed after a total of 6 months of use and no support from manufacturer. It was good when it worked. Edit: Manufacturer slow to respond - but shipped a replacement - update after testing replacement",
"helpful_count": null
}
],
"review_count_scraped": 21,
"out_of_stock": false,
"in_stock": true,
"history_available": true
},
"upc": null
}
]
}
],
"results": "… (the response also carries results[], price_tiers[] and facets exactly as without detail)",
"seller_ratings": [
{
"seller": "Bitvae",
"seller_id": "A1JHU3BZ1D3UVY",
"seller_positive_pct": 98.0,
"seller_feedback_count": 5923,
"seller_rating": null,
"observed_at": "2026-09-19T09:18:23Z"
}
],
"credits_charged": 5.0,
"data_source": "amazon US marketplace — observed listings"
}
Demand signal. Every product carries
bought_past_month — the floor of Amazon’s “N+ bought in past
month” badge (e.g. 7000 for “7K+”), measured buyer behavior as
Amazon reports it, null where Amazon shows no badge. Included in every
response — no detail flag required.
Identifiers. Every product carries
product_id and product_url. product_id is the ASIN on
Amazon and the numeric item ID on Walmart; product_url points at the right
storefront (amazon.<tld>/dp/… or walmart.com/ip/…).
Pass product_id straight to /v1/product for that
item’s full history. The older asin and amazon_url keys are still
returned unchanged for compatibility, but note both are misnamed on Walmart (they carry the
item ID and a walmart.com URL) — prefer the product_* pair. Each Amazon product also carries upc — the barcode (UPC/EAN/GTIN) we hold for it, null when we hold none; feed it back to /v1/product?gtin= to resolve the same item. Walmart rows have no upc (Walmart uses numeric item IDs, not barcodes).
Results are scoped to the product category the query resolves to, so a search for graphics card returns graphics cards rather than whatever unrelated best-seller happens to share a word with the query.
Every product carries observed_at (UTC), the age of the snapshot; stale products (older than ~14 days) are pruned, so it is always recent. Coverage is Amazon best-seller (BSR) products; media (books, music, video)
excluded for now. Same engine as the
product search demo.
GET /v1/product product + intelligence
The single-ASIN product endpoint. One call returns the current snapshot (price, BSR,
rating, reviews, buy-box seller, seller count, FBA, image, sales estimate — warehouse or live) and
the intelligence blocks: a freshness stamp, the full price-change timeline (price_history, every buy-box price move we ever observed, seller-stamped) plus a 30-day convenience view, the Amazon-reported “bought in past month” badge (measured, not modeled — parsed integer + raw text; Amazon marketplaces only), the current
all-seller snapshot, and brand stats — plus the listing content (2026-08-09):
description with its source, the full image gallery, feature bullets, the complete category
breadcrumb path, the variations matrix, featured reviews and a definite out-of-stock signal
(all Amazon marketplaces; no extra charge). Warehouse responses return in under 100 ms.
| Param | Notes |
|---|---|
| asin | 10-char ASIN, or a numeric Walmart item ID with country=walmart. Provide either asin or gtin (not both). |
| gtin | optional anchor — any barcode (UPC, EAN, GTIN or ISBN-13; 8, 12, 13 or 14 digits) instead of an ASIN 2026-10-12. Punctuation and leading zeros are tolerated, so 012345678905, 12345678905 and 0012345678905 all resolve to the same product. Resolved within the requested marketplace, cheapest evidence first, and the answer says how in gtin_resolution — see Barcodes. The lookup is included in the record’s price; a barcode nothing resolves is a 404 and is never billed. |
| country | us (default), uk, de, ca, au, fr, it, es, jp, mx, br — 11 Amazon marketplaces — plus walmart (Walmart US, numeric item ID) |
| mode | auto (default) · cache · live — snapshot freshness (live scrape: all Amazon marketplaces, and Walmart since 2026-10-18 at 2 credits — Walmart live) |
| bsr_history | optional — true adds per-category BSR rank history: one daily point per category (best rank observed that day).
|
| bsr_leaf / bsr_leaf_category | always present. Many products (media, books, niche items) never receive an overall best-seller rank — Amazon's own page shows only a category rank there. When bsr is null, bsr_leaf carries the product's best category rank and bsr_leaf_category names the category (e.g. 18 in “Blank Media”). Both are null when the overall rank exists. |
| offer_history | optional — true attaches the buy-box owner timeline (who held the buy box, as observed ownership segments) and per-seller price series (daily points per seller, buy-box price wins the day) from our multi-seller offer stream. US buy-box depth reaches Dec 2024; full multi-seller depth Aug 2025+. Included in the record — no extra credits 2026-10-10. Amazon only. Sellers are identified by seller_id (the merchant id); the name is that id's usual display name. On a day with more than one observed holder the timeline shows the last observation and multi_holder_days counts such days; the per-seller points keep buybox: true for every observed holder. Since 2026-09-27 every point also carries the offer’s shipping (a cost, 0 = free), fba and prime as observed that day (null on legacy-era days before 2026-04-17), and each series row fba_days, fba_last, shipping_last; seller feedback stays in current_sellers / seller_ratings.Every observed seller is listed ( sellers_total = the length of sellers), each with first_seen, last_seen, days_observed, buybox_days and points_total; the sellers_with_series most-observed sellers carry points (default 10 sellers × 500 points — see history_sellers / history_points), the rest carry points: [] with points_returned: 0.sellers_per_day 2026-10-08: one entry per observed day (the most recent history_points days; sellers_per_day_total = all of them) — sellers = distinct sellers observed that day (every seller, not only the ones carrying series), buybox_holders = distinct buy-box holders observed that day, and list: full (a full offer list), buybox_only (a legacy feed that recorded only the buy-box offer — such a day says nothing about how many sellers competed) or carried_forward (the 2026-04-01 migration carry-forward). Count competing sellers on full days only; full_list_from = the first one.buybox_price_history 2026-10-09 comes with it: the lowest buy-box price of every observed day, Amazon US back to Nov 2023 — see the field. |
| history_sellers 2026-09-16 | optional, with offer_history — how many of the most-observed sellers carry a point series. Default 10, max 50. Every observed seller is listed regardless. |
| history_points 2026-09-16 | optional, with offer_history — points per series: the most recent N observed days (default 500, max 20,000; one point per observed day, so the observation depth is the real bound — points_total tells you how many days a seller has). Billing: included 2026-10-10 — wider series cost nothing extra (until then every started 1,000 points beyond the default 10 × 500 cost 0.5). The block still discloses points_returned, points_included, points_extra and extra_credits (now 0). |
| history_only 2026-10-10 | optional — true returns only the stored history series for 0.05 credit: bsr_history, offer_history (shaped by history_sellers / history_points) and buybox_price_history, plus asin, marketplace, currency, data_source and history_only: true. No snapshot, content, current_sellers, brand stats or seller ratings — when you need today’s listing, call without it. The cheap lane for price and rank tracking at volume.
|
| track 2026-10-14 | optional — true answers and tracks: after this answer the ASIN is pinned into our hot lane, which re-reads its offers page every interval for as long as your plan is active (or a ttl_days you set) and adds every read to buybox_price_points_hot — the same as POST /v1/track. No extra credits: the record is billed as usual and the tracking draws on the plan’s daily tracked-snapshot allowance. The answer is served even when the tracking is refused; the track block says what happened (status active / refused, granted_interval, allowance). Amazon only. |
| interval | with track=true: 1h, 2h, 4h (default), 12h or 24h. |
| full_offers | optional — true returns the complete seller list instead of the buy box plus the first page (~10 offers). Only affects a live scrape (mode=live, or mode=auto when the warehouse copy is stale); warehouse responses already carry the full list from our continuous crawl. Adds roughly 15–20s to the call and is not billed extra — still one call.
|
| include_used | optional — true adds the used, refurbished, open-box and collectible offers to current_sellers.sellers (default false keeps the new-condition list, so existing integrations see no change). Every seller row always carries condition (the marketplace's own label, e.g. Used - Like New, Gebraucht - Wie neu) and condition_class (new, used_like_new, used_very_good, used_good, used_acceptable, used, refurbished, open_box, collectible, unknown); current_sellers always carries conditions_included, used_offer_count, lowest_new and lowest_used (the cheapest offer of each population — the list itself is buy-box first, then price, so do not read the first row as the cheapest) whether or not you opt in. With offer_history=true and include_used=true the per-seller price series are keyed per seller and condition class. Cached, live and historical data alike; not billed extra. |
| max_age_days | warehouse freshness window for the snapshot (default 30) |
Barcodes (GTIN / UPC / EAN) 2026-10-12
Pass gtin= instead of asin= and we find the product, cheapest evidence first:
| Step | gtin_resolution.source | How |
|---|---|---|
| 1 | observed | the barcode printed on a listing we observe on this marketplace |
| 2 | isbn | a book’s ISBN-13 (978…) becomes its ISBN-10, which is the print edition’s ASIN (gtin_note says so) |
| 3 | other_marketplace | the same ASIN carries the barcode on another Amazon marketplace, and we observe that ASIN here too |
| 4 | amazon_search | mode=auto (the default) or mode=live: one Amazon search for the barcode on this marketplace. Only organic results count — sponsored placements and ad blocks are never candidates, and never more results than Amazon’s own “N results” count. Among the first three, the one whose listing we have seen carrying this barcode wins; otherwise the first. The first time takes ~10–20 s; the answer is kept 60 days (a search that found nothing, 7 days), so the next lookup is instant. mode=cache never searches. |
gtin_resolution = {"source", "confidence", "resolved_at", "barcode_verified"}.
barcode_verified answers “is this barcode printed on that listing?” — true: we observed it there (steps 1 and 3), it is the book’s own ISBN (step 2), or the search result’s listing carries it in our observations or on its product page when we scrape it live; false: the listing shows other barcodes and not this one; null: Amazon’s search placed it and the listing shows no barcode we could compare. confidence: observed, isbn10, other_marketplace and verified are checked facts; single_result (Amazon’s page held one organic result) and search_top (the first of several) are unverified search answers; barcode_differs means the listing carries other barcodes — check it before you rely on it. A live answer (mode=live, or auto when it scrapes) also returns upc as printed on the product page. A barcode can legitimately map to more than one ASIN (variations, re-listings, bundles): the best match is returned, priced first then most recently observed, and gtin_matches / gtin_match_count list every match we hold. The same barcode can be a different listing on another marketplace. Walmart barcodes resolve against the UPC of walmart.com listings we observed (step 1 only). /v1/offers takes gtin= the same way, /v1/shopping resolves a bare barcode with steps 1–3 plus earlier search answers, and product batches take a gtins list (below).
curl "https://api.logimu.com/v1/product?gtin=000113684531&country=us" -H "X-API-KEY: sk_live_..."
# the answer is the full product record (here a Verizon Fios G3100 router, B082BLM2KH), plus
"gtin": "000113684531",
"gtin_matches": ["B082BLM2KH"],
"gtin_match_count": 1,
"gtin_resolution": {"source": "amazon_search", "confidence": "single_result", "resolved_at": "2026-10-12T15:07:58Z"}
curl "https://api.logimu.com/v1/product?asin=B07X4V2M3B&country=us&bsr_history=true&offer_history=true" \\ -H "X-API-KEY: sk_live_..."
Sample response — a real warehouse answer for B07X4V2M3B (WD Elements desktop drive: 15 variations, full gallery, 12 featured reviews). Long arrays are truncated with an explicit marker; the API returns all of them. Billing fields omitted.
{
"source": "cache",
"asin": "B07X4V2M3B",
"marketplace": "amazon-us",
"data_source": "amazon US marketplace — observed listings",
"title": "Western Digital 12TB Elements Desktop External Hard Drive, USB 3.0 external hard drive for plug-and-play storage - Western DigitalBWLG0120HBK-NESN",
"brand": "Western Digital",
"price": 529.99,
"review_count": 127985,
"image_url": "https://m.media-amazon.com/images/I/51U3tZNZ36L._AC_SY355_.jpg",
"price_source": "aod",
"price_observed_at": "2026-08-09 00:29:56",
"currency": "USD",
"bsr": null,
"rating": 4.6,
"reviews_count": 127985,
"buybox_seller": "Nutrend Automotive Inc",
"buybox_seller_id": "A2LH8DUZ1Q6T63",
"buybox_observed_at": "2026-08-08T22:29:56Z",
"seller_count": 21,
"fba": false,
"image": "https://m.media-amazon.com/images/I/51U3tZNZ36L._AC_SY355_.jpg",
"description": "Western Digital elements desktop storage with USB 3.0 offers reliable, high-capacity, add-on storage, fast data transfer rates and universal connectivity with USB 3.0 and USB 2.0 devices. The sleek design features up to 12TB capacity plus Western Digital quality and reliability. Operating temperature: 5 degree Celsius to 35 degree Celsius Non-operating temperature: -20 degree Celsius to 65 degree Celsius.",
"sales_estimate": 10,
"upc": "718037872070",
"parent_asin": "B0FGKVRWXQ",
"as_of": "2026-08-09 00:29:49",
"bsr_leaf": 4,
"bsr_leaf_category": "External Hard Drives",
"observed_at": "2026-08-08T22:29:56Z",
"price_changes_30d": [],
"stock_changes_30d": [],
"price_history": [],
"stock_history": [],
"stock_state": "in_stock",
"stock_observed_since": "2026-08-05T10:44:16Z",
"bought_past_month": 100,
"bought_past_month_raw": "100+ bought in past month",
"bought_past_month_observed_at": "2026-08-08T22:29:49Z",
"bsr_history": {
"series": [
{
"category_id": 6239,
"category_name": "External Hard Drives",
"category_path": "Computers & Accessories > Data Storage > External Hard Drives",
"is_root": false,
"first_date": "2023-10-24",
"last_date": "2026-08-09",
"n_points": 234,
"points": [
{
"date": "2023-10-24",
"rank": 8
},
{
"date": "2023-10-25",
"rank": 13
},
"… 232 more (truncated for this sample — the API returns all of them)"
]
},
{
"category_id": 510,
"category_name": "External Components",
"is_root": false,
"first_date": "2023-10-24",
"last_date": "2024-03-12",
"n_points": 8,
"points": [
{
"date": "2023-10-24",
"rank": 23
},
{
"date": "2023-11-08",
"rank": 75
},
"… 6 more (truncated for this sample — the API returns all of them)"
]
},
"… 2 more (truncated for this sample — the API returns all of them)"
],
"observed_from": "2023-10-24",
"observed_to": "2026-08-09"
},
"offer_history": {
"multi_holder_days": 23,
"buybox_timeline": [
{
"seller": "platinum micro, inc.",
"seller_id": null,
"from": "2024-12-31",
"to": "2024-12-31",
"days_observed": 1
},
{
"seller": "stc distributors (serial # recorded)",
"seller_id": null,
"from": "2025-01-02",
"to": "2025-01-02",
"days_observed": 1
},
{
"seller": "platinum micro, inc.",
"seller_id": null,
"from": "2025-01-04",
"to": "2025-01-06",
"days_observed": 2
},
"… 21 more (truncated for this sample — the API returns all of them)"
],
"sellers": [
{
"seller": "dealspro1",
"seller_id": null,
"first_seen": "2024-12-29",
"last_seen": "2025-10-04",
"days_observed": 17,
"buybox_days": 13,
"seller_positive_pct": 96.0,
"seller_feedback_count": 1842,
"rating_observed_at": "2026-09-17T04:12:09Z",
"points_total": 17,
"points_returned": 17,
"points": [
{
"date": "2024-12-29",
"price": 246.0,
"buybox": false
},
{
"date": "2025-01-07",
"price": 239.95,
"buybox": true
},
"… 15 more (truncated for this sample — the API returns all of them)"
]
},
{
"seller": "giz-promo",
"seller_id": "A1H3REWH8UBGUB",
"first_seen": "2025-01-17",
"last_seen": "2026-08-08",
"days_observed": 12,
"buybox_days": 6,
"points": [
{
"date": "2025-01-17",
"price": 239.5,
"buybox": true
},
{
"date": "2025-01-29",
"price": 237.95,
"buybox": true
},
"… 10 more (truncated for this sample — the API returns all of them)"
]
},
"… 38 more — every observed seller is listed; beyond the 10 most-observed, points is [] and points_returned 0 (points_total still says how many days that seller has)"
],
"sellers_total": 40,
"sellers_with_series": 10,
"history_sellers": 10,
"history_points": 500,
"points_returned": 1843,
"points_included": 1843,
"points_extra": 0,
"extra_credits": 0.0,
"sellers_per_day": [
{ "date": "2025-03-27", "sellers": 1, "buybox_holders": 1, "list": "buybox_only" },
"… 498 more (truncated for this sample — the most recent history_points observed days, oldest first)",
{ "date": "2026-08-08", "sellers": 21, "buybox_holders": 2, "list": "full" }
],
"sellers_per_day_total": 612,
"full_list_from": "2025-08-11",
"observed_from": "2023-12-16",
"observed_to": "2026-08-08"
},
"current_sellers": {
"as_of": "2026-08-08T22:29:56Z",
"offer_count": 21,
"buybox_seller": "Nutrend Automotive Inc",
"conditions_included": "new_only",
"used_offer_count": 2,
"buybox_days_observed_30d": 26,
"buybox_observations_total_30d": 64,
"lowest_new": { "price": 529.99, "condition": "New", "condition_class": "new", "seller": "Nutrend Automotive Inc", "seller_id": "A2LH8DUZ1Q6T63", "is_fba": false, "is_prime": false },
"lowest_used": { "price": 449.00, "condition": "Used - Like New", "condition_class": "used_like_new", "seller": "Example Resale Ltd", "seller_id": "A1EXAMPLE0SELLR", "is_fba": true, "is_prime": true },
"sellers": [
{
"seller": "Nutrend Automotive Inc",
"seller_id": "A2LH8DUZ1Q6T63",
"price": 529.99,
"is_buybox": true,
"is_fba": false,
"is_prime": false,
"seller_positive_pct": 91.0,
"seller_feedback_count": 21318,
"buybox_days_30d": 5,
"buybox_share_30d": 19,
"buybox_observations_30d": 9,
"buybox_observation_share_30d": 14.1,
"condition": "New",
"condition_class": "new"
},
{
"seller": "Adorama",
"seller_id": "A17MC6HOH9AVE6",
"price": 529.99,
"is_buybox": false,
"is_fba": false,
"is_prime": false,
"seller_positive_pct": 90.0,
"seller_feedback_count": 579297,
"buybox_days_30d": 0,
"buybox_share_30d": 0,
"buybox_observations_30d": 0,
"buybox_observation_share_30d": 0.0,
"condition": "New",
"condition_class": "new"
},
"… 19 more (truncated for this sample — the API returns all of them)"
]
},
"brand_stats": {
"brand": "Western Digital",
"products_tracked": 102,
"avg_rating": 4.41,
"total_ratings": 1015987,
"in_stock_pct": 100.0,
"distinct_buybox_sellers": 48,
"top_buybox_sellers": [
{
"seller": "Amazon.com",
"products": 19
},
{
"seller": "ALL4COMPUTERS ----- SIGNATURE REQUIRED -----",
"products": 3
},
{
"seller": "Actiview CCTV",
"products": 3
},
{
"seller": "CorteseInc",
"products": 3
},
{
"seller": "GO SMART",
"products": 3
}
]
},
"product_url": "https://www.amazon.com/dp/B07X4V2M3B",
"description_source": "product_description",
"images": [
"https://m.media-amazon.com/images/I/21A5YMvc7ZL.jpg",
"https://m.media-amazon.com/images/I/41CLje4zOhL.jpg",
"https://m.media-amazon.com/images/I/51X-qRLsP-L.jpg",
"… 9 more (truncated for this sample — the API returns all of them)"
],
"feature_bullets": [
"High-capacity add-on storage.Specific uses: Personal",
"Fast data transfers",
"… 2 more (truncated for this sample — the API returns all of them)"
],
"breadcrumbs": [
"Electronics",
"Computers & Accessories",
"Data Storage",
"External Hard Drives"
],
"variations": [
{
"child_asin": "B09VCXWPQG",
"dimension_index": "11",
"dimension_values": {
"size_name": "20TB"
},
"is_selected": 0,
"is_available": 1
},
{
"child_asin": "B0BTFPTSNQ",
"dimension_index": "12",
"dimension_values": {
"size_name": "22TB"
},
"is_selected": 0,
"is_available": 1
},
{
"child_asin": "B0D7N5XRSV",
"dimension_index": "13",
"dimension_values": {
"size_name": "24TB"
},
"is_selected": 0,
"is_available": 1
},
"… 12 more (truncated for this sample — the API returns all of them)"
],
"variation_count": 15,
"content_observed_at": "2026-08-09 15:04:50",
"reviews": [
{
"author": null,
"rating": 5.0,
"title": "Good drive! You'll buy it.",
"date_raw": "Reviewed in the United States on May 30, 2020",
"verified": true,
"variant": "Capacity: 5TB",
"body": "First order of business: I ordered this drive (WD Elements 5tb) and received it in about 18 hours. I checked the shipping label, and it is their proprietary del…",
"helpful_count": 107
},
{
"author": null,
"rating": 5.0,
"title": "A Tale of 2 drives (WD 20TB Elements Desktop & WD 2TB Elements Portable)",
"date_raw": "Reviewed in the United States on December 30, 2025",
"verified": true,
"variant": "Capacity: 20TB",
"body": "June 22, 2026 (UPDATES): I paid $279.99 for the 20TB drive on May 7, 2025 (on sale from $304.00). This drive is $814.99 as of today. It's been in daily use all …",
"helpful_count": 99
},
"… 10 more (truncated for this sample — the API returns all of them)"
],
"review_count_scraped": 12,
"out_of_stock": false,
"history_available": true
}
Description & image. description is returned on
both warehouse and live responses, and image_url on live scrapes as well as the warehouse.
Listing content fields 2026-08-09
Always present on Amazon-marketplace answers, warehouse or live,
at no extra charge. Walmart answers carry their own content set since 2026-09-20 — image_url,
images[], description, category_path + breadcrumbs[],
highlights[] (the PDP spec table as name/value pairs), warnings[], upc
— listed in the Walmart row of the response table above. content_observed_at stamps when the content was captured; when it is
null and the arrays are empty, content has not been captured for this ASIN yet
(coverage fills in as the crawl cycles) — that is “not yet observed”, never “this
product has no gallery”.
| Field | Notes |
|---|---|
| description / description_source | description_source names the surface the text came from: product_description (written prose), feature_bullets (the “About this item” list, joined), or aplus (brand marketing copy). Bullets read very differently from prose — check the source before rendering or summarising the text as a “description”. |
| images | the full gallery, de-duplicated to original-resolution URLs, up to 20. image_url stays the primary image. |
| feature_bullets | the “About this item” bullets as their own list — no need to guess whether description happens to be bullets this time. |
| breadcrumbs | the complete category path (e.g. ["Electronics", "Computers & Accessories", "Data Storage", "External Hard Drives"]), not just the root and leaf. |
| variations / variation_count / parent_asin | the variation matrix: each entry carries child_asin, dimension_values (e.g. {"size_name": "20TB"}), is_selected, is_available. An empty variations is normal — most ASINs genuinely have no variants. Per-variant price is NOT included: Amazon sends it only when a variant is selected, so do not expect it here. |
| reviews / review_count_scraped | the top/featured reviews Amazon shows a logged-out visitor, accumulated across our observations — up to 50 per product 2026-09-28 (was 12), most recently featured first — not the full review history, and not a random sample. A single page render shows 8–13; the warehouse keeps every featured review it has seen for the ASIN, so older featured reviews stay available after Amazon rotates them out. On a live answer the page’s own reviews come first and the accumulated set fills up to the cap. Each review: author (always null 2026-10-03 — reviewer names are not stored or served; the key stays so existing parsers keep working), rating, title, date_raw, verified, is_local (true = the marketplace's own “Top reviews from <country>” section, false = “Top reviews from other countries” — on smaller marketplaces most featured reviews can be foreign), variant, body, helpful_count. date_raw is verbatim (“Reviewed in the United States on December 30, 2025”) — it carries the review country and a localised month name; parse it downstream if you need a datetime, and keep the country. The “Customers say” AI summary and aspect chips are not available (Amazon lazy-loads them after the HTML we capture). |
| seller_count 2026-10-05 | the number of sellers we observed on the listing at its latest observation — the same observation as current_sellers, so with a seller list in the answer it always equals that list’s length (an observed empty list is 0); on a /v1/shopping row without detail it is the count from our nightly fulfilment table for that product. It is not Amazon’s own “N new offers” headline: that page number used to feed this key on search rows and was missing on most products and wrong on many (a stuck value on ~5 %), so it is no longer served anywhere. The list is what our pass read on the offers page (a live /v1/product with full_offers=true walks every page). null = no observation yet; on a /v1/shopping row also when that table’s latest observation of the listing is more than 30 days old 2026-10-18, so an old count is never served as today’s. |
| fulfillment 2026-09-17 | the listing's fulfilment status, Amazon marketplaces only, not billed extra. buybox = AMZ (sold by Amazon itself), FBA (a third party fulfilled by Amazon), FBM (merchant-fulfilled) or null (no buy box observed); buybox_seller, buybox_seller_id, ships_from, is_prime; offers = {amz, fba, fbm, total} counts over the offers in current_sellers; amazon_sells (Amazon has an offer on the listing) and amazon_holds_buybox; buybox_delivery (see below); dispatch_latency (Amazon's “Usually ships within 2 to 3 days”, only shown when the item does not ship immediately); observed_at, source. Amazon is identified by its storefront label, never by a merchant id. |
| current_sellers.sellers[].fulfillment / delivery / ships_from / shipping_cost | per seller: fulfillment (AMZ / FBA / FBM), ships_from, shipping_cost (the offer's shipping charge, 0 for free), and delivery = {text, free, days_min, days_max, fastest_days} — text is Amazon's own delivery sentence as rendered in the marketplace language at scrape time; days_min/days_max are whole days from the observation date to the promised delivery date (a range like “19 - 21 September” gives both, a single date gives the same value twice); fastest_days is the Prime / paid fast option when the sentence offers one; free is whether the standard option is free. Parsed for en, de, fr, it, es, pt and ja; when the sentence cannot be read the days are null and the text is kept. Delivery promises are relative to the scrape moment, so they describe the seller's speed at that observation, not today's promise. |
| current_sellers.sellers[].delivery.source / date_min / observed_at 2026-09-18 | where the delivery days come from: nightly = parsed by the nightly pipeline from that seller's last observed delivery sentence (the default, non-Prime promise as days_min/days_max, the Prime/fast option as fastest_days, the promise as a date in date_min, stamped observed_at); parsed = parsed at request time from the sentence in this response (live scrapes, sellers the nightly has not seen yet). Same parser either way. |
| current_sellers.sellers[].delivery_eta_days / delivery_eta_fastest_days 2026-09-18 | per offer, flat: whole days from the observation to that seller's default (non-Prime) promised delivery date, and the Prime/fast option when Amazon showed one (null = no date in the sentence, e.g. "cannot be shipped to your address"). The same numbers as delivery.days_min / delivery.fastest_days; fulfillment.buybox_delivery_eta_days is the buy-box winner's. Nightly-parsed, no request-time cost beyond one indexed lookup. |
| buybox_price_history 2026-10-09 | the daily buy-box price, as deep as we hold it — returned with offer_history=true (and with history_only=true), included in the record. points: one per observed day, {date, price, source}, oldest first; price = the lowest buy-box price we observed that day, new condition (every marketplace’s own word for new counts). source: offers = our offer observations (every Amazon marketplace, from 2026-04-17), daily_snapshot = the legacy daily product snapshot (Amazon US, Nov 2023 – Apr 2026) — which reaches further back than offer_history’s Dec 2024. Also days_observed, observed_from, observed_to, days_by_source and points_withheld (days priced more than 20× above or below the series’ median, withheld as parsing artifacts). Every observed day is returned (no series cap). A gap between two dates is a stretch we did not observe the listing, not a price that held. On a day with several buy-box holders this series takes the lowest price; offer_history shows who held the box and at what price. null on Walmart and when we hold no buy-box price for the ASIN. |
| buybox_price_points_hot 2026-10-14 | every all-offers-page observation of the last 30 days, newest last — on every Amazon answer (full record and history_only=true), included in the record. points: {ts, price, seller, seller_id, fulfillment, offer_count} = the buy box as it stood at that moment. Sub-daily where price_history (one observation per day) and buybox_price_history (the lowest price per day) are daily: ASINs in our hot lane (see tracking) are observed every few hours, the rest carry the continuous crawl’s and on-demand observations. Also points_total, points_returned (the most recent 2,000), days, observed_from/observed_to, points_withheld (observations priced more than 20× below the rest, withheld as parsing artifacts). With offer_history=true the same points also appear as buybox_price_history.points_hot. null on Walmart and when we hold no priced all-offers observation in the window. |
| tracking 2026-10-14 | the hot lane’s state for this ASIN when we refresh it at an interval: {hot: true, interval_min, rate, source, last_fetched_at, next_due_at}; null when the ASIN is not in the lane. The lane watches popular and customer-polled ASINs every few hours (US first); observed_at and current_sellers.as_of then move with every fetch, and mode=auto serves the stored record while it is fresh. |
| offer_history.sellers[].points[].delivery_eta_days / sellers[].delivery_eta_days_last 2026-09-18 | historical delivery ETA per offer-day: on every series point, whole days from that day's observation to the seller's default (non-Prime) promised delivery, parsed nightly from the delivery sentence Amazon showed that day; delivery_eta_days_last is the seller's most recent value. null before the history's fill window (currently from 2026-08-19) or where the sentence carried no date. Not billed beyond the history charge. |
| fulfillment.dispatch_days_min / dispatch_days_max / delivery_eta_source 2026-09-18 | dispatch_latency ("Usually ships within 2 to 3 days") parsed to whole days — Amazon shows that line only on slow-dispatch listings (about 2% of US pages), so null means the listing ships promptly, not missing data. delivery_eta_source says whether the buy-box delivery promise came from the product page (page) or from the buy-box offer's own delivery sentence (offer); the page ETA is shown on roughly a quarter to a half of pages and never on DE/MX/BR, so the offer sentence is the usual source. |
| authors[] / author / authors_observed_at 2026-09-29 | who made the product, from the page byline — authors is a list of {name, role, role_norm, author_id} (role = the page’s own word, role_norm one of author / narrator / illustrator / editor / translator / foreword / publisher / other; author_id = Amazon’s author-page id when the page linked one), author = the author-role names joined. Books, audiobooks, music and similar listings; [] / null elsewhere and on Walmart. Products parsed before 2026-09-29 carry a single byline without a role — served as one author entry, never with an invented role. Filling in over the coming days as pages are re-observed. |
| format / format_norm / formats[] / family_asin / formats_observed_at 2026-09-30 | the book or media format, and every other format of the same book — format as the page shows it (“Paperback”, “Taschenbuch”, “Kindle版”), format_norm one of kindle / paperback / hardcover / mass_market / audiobook / audio_cd / board_book / spiral / library_binding / other. formats lists every format of the book, each its own ASIN: {type, format_norm, label, asin, price, subscription_price, is_current, price_text}. price is the purchase price and is null when the page only showed a membership price (Kindle Unlimited, Audible), which is in subscription_price. is_current marks this ASIN. family_asin identifies the book across its formats. Formats are separate products, so they are not in variations. Any ASIN in formats can be passed to this endpoint. null / [] for non-media listings, for pages not re-observed since formats were captured (filling in from 2026-10-01), and on Walmart. Same keys on /v1/shopping?detail=true, batch rows and MCP. |
| current_sellers.sellers[].seller_rating / lowest_new.seller_rating / offer_history.sellers[].seller_rating 2026-09-28 | the seller’s feedback record on the seller row itself — {positive_pct, feedback_count, rating, observed_at}, the latest we hold for that seller (same source as the response-wide seller_ratings array below, matched by seller id, then by name), null when we hold none. Additive: the per-offer seller_positive_pct / seller_feedback_count printed on the offer at observation time stay. Same rows on /v1/shopping?detail=true, batches and MCP. |
| seller_ratings 2026-09-18 | seller feedback for every seller this answer names — the current offers, the cheapest new/used sellers, the buy-box holder and, with offer_history, every historical seller: one entry per seller with seller, seller_id, seller_positive_pct (Amazon's positive-feedback %), seller_feedback_count, seller_rating (stars, when shown) and observed_at (the observation the values come from). Sourced from a nightly seller-feedback table built from every offer we observe, so a seller's values are its latest seen on that marketplace, not just on this listing. Amazon's own offers carry no feedback. offer_history.sellers[] rows also carry seller_positive_pct, seller_feedback_count and rating_observed_at directly. Amazon marketplaces only (empty on Walmart). Not billed. |
| Walmart: image_url, images[], description, category_path, breadcrumbs[], highlights[], warnings[], upc, model_number, color, rating, review_count, rating_observed_at, was_price, discount_pct, additional_offer_count, in_stock, as_of; sellers[].shipping_cost 2026-09-20 | country=walmart — the listing content we hold for every Walmart item, added additively (no existing key changed): main image (and a one-element images[]), description, breadcrumb path (string + list), highlights[] = the PDP spec table as {name, value} pairs, warnings[] = compliance text (Prop 65) in the same shape, barcode (upc, ~61% of items — gtin= now resolves Walmart barcodes to item IDs), rating/review_count from the most recent snapshot that carried one (null when the page showed none, ~41% of items), strikethrough was_price with discount_pct (both null unless the was-price is above the price), and in_stock/as_of beside stock_state/observed_at so one client shape covers Amazon and Walmart. Each seller row carries shipping_cost — a shipping cost (0 = free, null = not shown), never a landed price. product_url stays walmart.com/ip/<id>. |
| observed_at / price_observed_at / price_source 2026-09-22 | what the stamps mean by source: on cache and cache_after_live_fail answers they are the warehouse's — observed_at is the last time we observed the listing's offers, price_observed_at the last time the served price was seen, price_source the surface it came from (pdp, aod, warehouse). On a live answer (full or partial scrape) all three are the scrape you just paid for: observed_at = the scrape time (UTC), price_observed_at = the same instant, price_source = live. as_of and content_observed_at already carried the scrape time; before 2026-09-22 a live answer wrongly kept the warehouse's days-old observed_at. |
| buybox_seller / buybox_seller_id / buybox_observed_at 2026-10-08 price 2026-10-09 | the top-level buy-box holder, name and id from one observation: when the answer carries an offer list, both come from its buy-box offer row and buybox_observed_at is that list’s time (current_sellers.as_of); Amazon’s own offer row carries no id, so its id is taken from the product page only when that page named the same seller, else null. Without an offer list both come from the latest product-page row (time: as_of) and buybox_observed_at is absent. Before 2026-10-08 the name followed the offer list while the id could come from a newer product-page row naming a different holder. Since 2026-10-09 the top-level price follows the same observation on cached answers: when that buy-box offer row is new-condition and priced, price is its price, price_source is aod and price_observed_at is that list’s time (UTC); otherwise the price stays the latest product snapshot’s. Before, a cached answer could pair the holder with another observation’s price (one holder’s name with the previous day’s holder’s price). A live answer is one scrape and was already consistent. |
| dimensions 2026-09-27 | item weight and package dimensions, Amazon marketplaces, not billed: weight_raw / dimensions_raw exactly as the product page prints them (“2.12 ounces”, “7.88"L x 3.97"W x 1"H”, “28.6L x 43W x 7.7H centimetres”), plus the parsed weight_value + weight_unit (g, kg, oz, lb, mg) and weight_g, and length / width / height + unit (in, cm, mm, m) with length_cm / width_cm / height_cm. Untagged triples are taken in print order (Amazon prints L × W × H); a two-value string leaves height null; an unreadable string keeps the raw text with null numbers. observed_at = the page observation the values come from. null when no observation of the listing carried either field. 2026-10-02 Letter tags are used only when every axis letter is an English L / W / H / D; any local letter (German B, French l / P, Brazilian C / L / A, “Th”) falls back to print order, so “48,5L x 27,5B x 58,5H” reads 48.5 × 27.5 × 58.5. missing_axes names the measures a shorter string leaves out (“3.24"W x 10.68"H” → ["length"]). Weight units are read in the page language (Pfund, livres, libras, onzas, onças, ポンド, “hundredths pound”…). weight_flag: "implausible" marks a weight Amazon printed that cannot be right: under 5 g at less than half the density of air for the listed dimensions, a milligram dose on anything over 10 cm³, or under 0.1 g with no dimensions. Then weight_value / weight_unit / weight_g are null and weight_raw keeps Amazon’s text. |
| deal_history 2026-09-27 | list price, savings and coupon history: segments[], one per run of consecutive product-page observations with identical values — from, to, days_observed, list_price (the strikethrough “List:” / “Was:” figure), savings_amount, savings_percent, coupon_text (the coupon or promotion line as printed — coupons and multi-buy promotions alike), coupon_expires, the parsed coupon_amount / coupon_percent, and promotion_types 2026-10-02 (coupon, multi_buy, other). The coupon figures come only from an explicit coupon or voucher clause (“Coupon: 15% off coupon applied”, “Voucher: …”, “Cupón: …”); a multi-buy offer such as “Save 5% on any 2 qualifying items”, a sign-in code or a registry discount is not a coupon and leaves them null. null fields mean not shown on the page that day; a day inside no segment was not observed on the product page. Also current (the latest segment’s values with as_of), days_with_list_price, days_with_coupon (days with a coupon clause), days_with_promotion (days with any promotion text), observed_from / observed_to. A list price at or below that day’s price is not a discount and is served as null together with that day’s savings (counted in list_price_hidden_days, 2026-09-30). A list price that is not consistent is not served 2026-10-08: at least 60% of the product-page observations within 7 days either side must carry a list price within 10% of it; otherwise the page’s list-price field was flipping between unrelated values (another variation’s or another widget’s price) and that day’s list price and savings are null (counted in list_price_unstable_days). The check reads the days after an observation too, so the latest week’s verdict can change as observations arrive. Observed since we started tracking the listing (Apr 2026 onward). Not billed. |
| subscribe_save 2026-10-02 | Subscribe & Save, from the latest product-page observation that showed it: eligible, discount_percent (the Subscribe & Save price against the one-time price; 0 is a real value: offered without a discount) and observed_at. Captured from 2026-09-30, so null means the page has not been observed since, never “not offered”. Amazon only (null on Walmart). Not billed. |
| bought_past_month_history 2026-09-27 | the “N+ bought in past month” badge over time: segments[] of consecutive product-page observations with the same badge — from, to, days_observed, bought_past_month (the floor of Amazon’s bucket: 1K+ → 1000), raw. bought_past_month: null = the page was observed without a badge (Amazon badges only higher-velocity listings) — a real observation, not a gap. Plus max, days_observed, observed_from / observed_to. Measured aggregate buyer behaviour, never an estimate. Not billed. |
| rating_history 2026-09-27 | rating-count history: points[], one per day the product page was observed — date, rating_count (Amazon’s global ratings count), rating (the star average shown) — with rating_count_first / rating_count_last, rating_last, ratings_gained_30d / ratings_gained_90d (growth over the trailing window of observed days; null with fewer than two observations in it), points_total, observed_from / observed_to. Review velocity without modelling. Not billed. |
| variation_coverage 2026-09-27 | how much of the variation matrix we cover — current state, not history. parent_asin, is_variation_child, variation_count, dimension_names[] (e.g. color_name, size_name), children_total, children_tracked (child ASINs with at least one observation of their own on this marketplace — the rest are known only as matrix entries), children_tracked_pct, children_with_price_30d, children_available (the matrix’s own availability flags), and children[] (≤200, children_truncated says if more exist): child_asin, dimension_values, is_available, is_this_asin, tracked, last_observed_at, price_30d + price_30d_observed_at (the child’s latest observed price in the last 30 days; null = not observed in that window). matrix_observed_at = when the matrix was last seen on the page. An empty matrix on a listing without variants is normal. Any child ASIN can be passed to this endpoint for its own dossier. Not billed. |
| sales_estimate 2026-09-27 | coverage: the modelled estimate exists for Amazon US listings (BSR-curve model calibrated on badge data); on the other marketplaces the only monthly-sales figure is Amazon’s own badge in bought_past_month, where Amazon shows one (US ~19 % of listings, DE ~14 %, BR ~10 %, MX ~7 % of observed rows). The modelled monthly unit estimate is served only for listings without Amazon’s “N+ bought in past month” badge; when the badge is present sales_estimate is null and the measured figure is in bought_past_month (with bought_past_month_raw, bought_past_month_observed_at and the bought_past_month_history segments). A model must not contradict a measurement on the same record. |
| reviews[] order 2026-09-27 | the marketplace’s own featured reviews (is_local: true, Amazon’s “Top reviews from <country>”) come first, the “other countries” set after them; inside each group the most recently featured first. Same set, same fields. |
| buybox_state buybox_state_observed_at stock_state_source 2026-10-14 | what the lane’s newest all-offers read saw: in_stock (a featured offer), no_buybox (offers, but no featured offer), out_of_stock (no offers), with its stamp. When that read is newer than the daily history’s last point it decides stock_state / in_stock and stock_state_source names it (e.g. all-offers read 2026-10-15T03:46:34Z (out_of_stock)); otherwise the keys are absent and the history’s state stands. The three stock keys always agree. Same states as tracking. |
| out_of_stock | tri-state: true = out of stock — Amazon's dedicated out-of-stock buybox on the page, or the newest all-offers read found no offer (on mode=live, measured on that scrape — a real answer, distinct from a failed lookup); since 2026-10-15 it always agrees with stock_state and in_stock, false = in stock when last seen, null = unknown. |
| variation_status page_asin 2026-10-15 | mode=live only: Amazon sometimes answers a variation child’s URL with another ASIN’s page — variation_status says so (page_is_sibling = a sibling of the same parent, page_is_other = an unrelated ASIN, null = the page was this ASIN’s) and page_asin names whose page it was. The answer’s stock keys describe the ASIN you asked for (its own offers page), not the page served; the content fields are the served page’s. Cache answers carry both keys as null. |
| buybox_condition buybox_condition_source buybox_condition_detail 2026-10-15 | new | used | null (no featured offer): whether the buy box is a second-hand offer — Amazon’s own used storefronts (Amazon Resale, Amazon Warehouse, Retourenkauf, Segunda mano, …) win the buy box like any seller and were previously indistinguishable from Amazon retail (fulfillment: AMZ). source = product_page or offers_page, detail = the pinned offer’s condition text, used_only_buybox, or the storefront name. Live answers: measured on that fetch. Cache answers: the pinned offer’s stored condition at the row’s observation (offers-page reads), else the storefront name; null when the stored row says nothing either way. |
About the stock fields. stock_state, stock_changes_30d and stock_history are still returned, but do not build on them. Our crawl follows best-seller rank, and a product that goes out of stock generally drops out of that walk — so we stop seeing it rather than observing it go out of stock. Measured: out-of-stock appears on 0.24% of availability-bearing observations, well below the true rate for a catalogue this size. Treat these fields as "in stock when last seen", not as a reliable availability timeline.
One exception: on mode=live, when the scrape finds the product marked unavailable, stock_state comes back a definite "out_of_stock" (with in_stock: false) — a measured answer from that scrape, not the walk-derived timeline.
Credits 2026-10-10: a warehouse call with everything attached is 0.5 credit — the same as a batch row — and that includes the history: bsr_history, offer_history with buybox_price_history, and wider series. A live scrape is 1, history included; an intelligence-only answer or Walmart is 0.5; history_only=true (the series alone) is 0.05. Until 2026-10-10 history added 0.5 once per call. A partial live
scrape (identity but no price) sets snapshot_status: "partial" and is
never billed for the snapshot half. snapshot_status is
returned on live scrapes only — it reports the completeness of that
scrape, so warehouse responses omit it. Change events are transitions from
our 30-day observation stream — one observation per calendar day (the richest scrape pass of that day), so multiple same-day passes never fabricate changes; a price that moved and moved back between two observations is not seen — while price_history and stock_history extend the same transition streams back to the first time we observed the product (stock_observed_since; stock_state is the latest derived state),
each stamped with the buy-box seller at that time. buybox_days_30d = the observed days in the last
30 on which a seller held the buy box; because it scales with how often we visited the listing, read it against
current_sellers.buybox_days_observed_30d (the days in that window with any buy-box winner observed)
or use the ready-made buybox_share_30d (0–100, the seller's share of those days; null
when the window holds no buy-box observation). The buy box rotates within a day, so several sellers can share a
day and day shares can sum past 100; buybox_observation_share_30d 2026-10-08 counts each buy-box
observation once instead (0–100, one decimal: the seller's part of
current_sellers.buybox_observations_total_30d; buybox_observations_30d is the count) —
the shares of all holders sum to 100. All 11 Amazon marketplaces (us, uk, de, ca, au, fr, it, es, jp, mx, br), plus Walmart
(numeric item ID, or gtin= with the item's UPC; since 2026-09-20 Walmart answers also carry the
listing content we hold — image_url, description, breadcrumbs[],
highlights[], upc, rating/review_count, per-seller
shipping_cost — see the Walmart row above; a live walmart.com read since 2026-10-18, below). Not billed if the product is untracked.
Live Walmart 2026-10-18
country=walmart&mode=live reads the walmart.com product page right now (typically
10–25 s; set client timeouts to 120 s) and lays it over the history we hold for the item. Price, stock,
rating, the featured seller and the sellers the page lists, title, brand, image, description, breadcrumbs, highlights,
warnings, UPC, model number and colour come from walmart.com now; price_history, stock_history
and the 30-day change events stay the stored ones (empty when we never held the item, see
history_available). The answer carries source: "live", price_source: "walmart_live"
and live_fetched_at. location names the store walmart.com priced the page for
(postal_code, city, state, store_id): each read can land on a different
store, and fresh grocery is priced per store, so the same item can differ between two reads. 2 credits.
mode=autoworks as on Amazon: the stored record when we observed the item withinmax_age_days(default 30) at 0.5, otherwise a live read at 2.mode=cachenever fetches.- Never billed: a partial page (a title but no price while shown in stock,
snapshot_status: "partial"), an item walmart.com does not have (404, remembered for 24 h), a failed fetch and a busy refusal (503 withretry_after_seconds). - A live read that fails on an item we hold answers our stored record instead, with
source: "cache_after_live_fail"and anote, billed as a warehouse row (0.5). When every live slot is busy,mode=autodoes the same andmode=liveanswers 503. - One product page per call:
additional_offer_countsays how many more sellers walmart.com has; their separate sellers page is not fetched. - Capacity: at most 5 live Walmart reads run at once across all customers (batches take at most 3 of them, one account at most 3), so a burst can see a 503; retry after the seconds it names.
- Batches:
country=walmartwithmode=liveorauto, 2 credits per live row, up to 5,000 rows a batch (modes).
Offer conditions 2026-09-14
We store the condition of every offer we observe, in the marketplace's own words, and the
API now returns it. By default current_sellers.sellers is the new-condition list (unchanged
behaviour); pass include_used=true to get used, refurbished, open-box and collectible offers in the
same list, each with its condition label and canonical condition_class. Even without
opting in, used_offer_count, lowest_new and lowest_used tell you how many
second-hand offers exist and the cheapest offer of each kind. price_history remains the buy-box
(new) series; a used-price history is available per seller via offer_history=true&include_used=true
(series keyed per seller and condition class). condition_class: "unknown" means the marketplace
showed a heading our classifier does not recognise; those rows stay in the new-condition list.
GET /v1/search
Search our warehouse of 24M+ tracked products across Amazon US/UK/DE/CA/AU/JP/FR/IT/ES/MX/BR + Walmart (not a live SERP scrape). Answers in under 100 ms.
| Param | Notes |
|---|---|
| q | keyword (title/description). An anchor. |
| brand | exact brand. An anchor. |
| category | a department or sub-category name (e.g. Home & Kitchen), matched in full and case-insensitively against the product’s category chain (comma-separate several). An anchor on its own — ?category=Home & Kitchen browses that category with no keyword — or a refinement of q/brand. A category-only browse returns the category’s top products by in-category best-seller rank, then applies your filters and sort; a name we don’t carry returns a 422 with the nearest matches, and — when nothing is even close, typically an English
name sent to a non-English marketplace — that marketplace’s real root categories plus a pointer to
GET /v1/categories 2026-10-07 (never a silent empty). Slower than a keyword search on the largest departments (up to ~1 s), not <100 ms. |
| seller | refinement — combine with an anchor (q, brand or category) |
| price_min/max, rating_min/max, reviews_min, bsr_min/max, fba, seller_count_min/max | filters |
| fulfillment 2026-09-17 | optional — amz (sold by Amazon itself), fba (third party, fulfilled by Amazon) or fbm (merchant-fulfilled), by the listing's latest observed buy box. Finer than fba, which cannot separate Amazon Retail from FBA sellers. Every result row also carries fulfillment (AMZ / FBA / FBM / null) next to fba. Amazon marketplaces only. |
| sort | bsr(default) · rating · reviews · price · sales_estimate · seller_count |
| bought_past_month 2026-10-06 | response field — every row now carries Amazon’s own “N+ bought in past month” badge (integer floor, null when Amazon shows none) and follows the same rule as /v1/product: when the badge is present sales_estimate is null; the modelled estimate appears only on unbadged US listings. Rows used to carry a modelled figure next to no badge. |
| max_per_category, limit | result caps (limit ≤ 100, default 50) |
| marketplace | amazon-us (default) · amazon-uk · amazon-de · amazon-ca · amazon-au · amazon-fr · amazon-it · amazon-es · amazon-jp · amazon-mx · amazon-br · walmart — all eleven Amazon marketplaces plus Walmart US 2026-09-28. country=us|uk|de|…|walmart is accepted as an alias, so the same value works here as on every other endpoint 2026-10-05 |
| seller_ratings 2026-09-18 | response field — a separate, additive array with seller feedback for every buy-box seller named in products[]: seller, seller_id, seller_positive_pct (Amazon's positive-feedback %), seller_feedback_count, seller_rating (stars, when shown), observed_at. One indexed lookup on the nightly seller-feedback table; row shapes are unchanged so existing integrations keep working. Amazon marketplaces only (null on Walmart and on empty results). Not billed. |
{
"marketplace": "amazon-us", "limit": 2, "returned": 2, "total_matched": 118,
"products": [ { "asin": "B0CT43D46H", "product_id": "B0CT43D46H",
"product_url": "https://www.amazon.com/dp/B0CT43D46H",
"marketplace": "amazon-us", "title": "Keurig K-Express \u2026", "brand": "Keurig",
"price": 70.39, "currency": "USD", "bsr": 412, "rating": 4.5, "reviews_count": 28104,
"seller_count": 6, "buybox_seller": "Amazon.com", "fba": true, "in_stock": true,
"as_of": "2026-07-29T11:20:04Z" } ],
"credits_charged": 1, "credits_remaining": 2497
}
Provide at least one anchor — q, brand or category
(seller only refines). A category-only example:
GET /v1/search?category=Home & Kitchen&price_max=30&sort=reviews&marketplace=amazon-us.
Coverage is deep on tracked brands, not the full Amazon catalog.
Identifiers. As with
/v1/shopping, every row carries product_id
(ASIN on Amazon, numeric item ID on Walmart) and a marketplace-correct
product_url; asin is retained for compatibility and is misnamed on
Walmart.
GET /v1/serp live Amazon & Walmart search
A live Amazon search-results (SERP) fetch — a real browser navigates Amazon’s search page right now and returns the parsed result grid plus everything around it. This is a third, different thing from the two warehouse search endpoints, and the three do not substitute for each other:
| Endpoint | What it searches | Latency |
|---|---|---|
| /v1/shopping | our curated index — ranked, grouped product recommendations | <100 ms |
| /v1/search | our warehouse — filterable tracked-product dataset | <100 ms |
| /v1/serp | Amazon itself, live — what Amazon’s search page shows this minute for a query | seconds (typically ~8–13 s) |
There is no warehouse copy of a SERP, so there is no mode
parameter here — every call is a live fetch, and sending mode is a 422 rather than a
silently ignored field. Parameter names match Rainforest’s type=search, so an existing
integration ports with a rename, not a rewrite.
| Param | Notes |
|---|---|
| q | required — the search query, exactly as a shopper would type it. Query in the marketplace’s own language. Alias: search_term. |
| country | us (default), uk, de, ca, au, fr, it, es, jp, mx, br — amazon-xx forms accepted — or walmart (walmart.com, live, 2 credits per page: Walmart search) 2026-10-18. |
| page | start page, default 1 |
| max_page | auto-paginate page..max_page and concatenate, capped at 10 pages per request. position is continuous across pages (page 2 starts at 17, it does not restart at 1). Billed per page actually fetched. |
| sort_by | featured (Amazon’s default) · price_low_to_high · price_high_to_low · average_review · most_recent · bestseller_rankings |
| category_id | Amazon browse-node id (becomes &node=) |
| refinements | Amazon rh= value. Round-trips: feed back any refinements[*].value from a previous response to apply that filter. |
| exclude_sponsored | drop inline sponsored results (default false). Often a no-op — see the honesty notes below. |
| number_of_results | truncate the returned list |
curl "https://api.logimu.com/v1/serp?q=wireless+earbuds&country=us" \ -H "X-API-KEY: sk_live_..."
Sample response — a real live fetch for wireless earbuds on
us (captured 2026-08-09, 11.9 s, one page, 16 results). Long arrays are truncated with an
explicit marker; the API returns all of them. Billing fields omitted.
{
"marketplace": "us",
"request_parameters": {
"search_term": "wireless earbuds",
"url": null,
"marketplace": "us",
"page": 1,
"max_page": null,
"sort_by": null,
"category_id": null,
"refinements": null,
"exclude_sponsored": false,
"number_of_results": null
},
"request_metadata": {
"created_at": "2026-08-09T18:56:31.592111+00:00",
"processed_at": "2026-08-09T18:56:43.438693+00:00",
"total_time_taken": 11.85,
"amazon_url": "https://www.amazon.com/s?k=wireless+earbuds",
"pages_fetched": 1,
"pages": [
{
"page": 1,
"ok": true,
"results": 16,
"attempts": 1,
"fetch_ms": 10478
}
]
},
"search_results": [
{
"position": 1,
"asin": "B0H718C1NK",
"title": "Wireless Earbuds, Bluetooth 5.3 Headphones HiFi Stereo 50H Playback LED Digital Display Ear Buds with ENC Noise Canceling Headset, IPX7 Waterproof Earphones for Gym/Running/Work（White）",
"link": "https://www.amazon.com/Fhumsh-Bluetooth-Headphones-Waterproof-Work%EF%BC%88White…",
"image": "https://m.media-amazon.com/images/I/61P4QAI28CL._AC_UY218_.jpg",
"rating": 4.7,
"ratings_total": 331,
"price": {
"symbol": "$",
"value": 19.97,
"currency": "USD",
"raw": "$19.97"
},
"list_price": {
"symbol": "$",
"value": 249.99,
"currency": "USD",
"raw": "$249.99"
},
"prices": [
{
"symbol": "$",
"value": 19.97,
"currency": "USD",
"raw": "$19.97"
},
{
"symbol": "$",
"value": 249.99,
"currency": "USD",
"raw": "$249.99"
}
],
"recent_sales": "5K+ bought in past month",
"badges": [],
"is_prime": false,
"sponsored": false,
"delivery": "Join Prime to get FREE delivery Tue, Aug 11 Or Non-members get FREE delivery Fri, Aug 14 on $35 of items shipped by Amazon",
"availability": {
"raw": null
}
},
{
"position": 2,
"asin": "B0H5W39V6T",
"title": "HAOYUYAN Wireless Earbuds, Sports Bluetooth Headphones, 80Hrs Playtime Ear Buds with LED Power Display, Noise Canceling Headset, IPX7 Waterproof Earphones for Workout/Running (Black)",
"link": "https://www.amazon.com/HAOYUYAN-Bluetooth-Headphones-Canceling-Waterproof/dp/B0H…",
"image": "https://m.media-amazon.com/images/I/71cmAChhQKL._AC_UY218_.jpg",
"rating": 4.9,
"ratings_total": 292,
"price": {
"symbol": "$",
"value": 23.98,
"currency": "USD",
"raw": "$23.98"
},
"list_price": {
"symbol": "$",
"value": 299.99,
"currency": "USD",
"raw": "$299.99"
},
"prices": [
{
"symbol": "$",
"value": 23.98,
"currency": "USD",
"raw": "$23.98"
},
{
"symbol": "$",
"value": 299.99,
"currency": "USD",
"raw": "$299.99"
}
],
"recent_sales": null,
"badges": [],
"is_prime": false,
"sponsored": false,
"delivery": "Join Prime to get FREE delivery Tue, Aug 11 Or Non-members get FREE delivery Fri, Aug 14 on $35 of items shipped by Amazon",
"availability": {
"raw": null
}
},
"… 14 more (truncated for this sample — the API returns all of them)"
],
"result_count": 16,
"search_information": {
"results_text_raw": "1-16 of over 20,000 results for \"wireless earbuds\" Sort by: …",
"results_begin": 1,
"results_end": 16,
"total_results": 20000,
"search_term": "wireless earbuds",
"spelling_correction": null
},
"pagination": {
"current_page": 1,
"total_pages": 20,
"next_page_link": "https://www.amazon.com/s?k=wireless+earbuds&page=2&xpid=rx1DTeS_MGGis&…",
"has_next": true
},
"related_searches": [
{
"query": "wireless headphones",
"link": "https://www.amazon.com/s?k=wireless+headphones&ref=rsl_sug_0_0&pd_rd_w=RbQ9n&content-id=amzn1.sym.3be64970-3b95-4a6d-a45d-78077a3ff871:amzn1.sym.3be64970-3b95-4a6d-a45d-78077a3ff871&pf_rd_p=3be64970-3b95-4a6d-a45d-78077a3ff871&pf_rd_r=FCT87YJN2Q2JJ8P2S0DJ&pd_rd_wg=DZW0L&pd_rd_r=64a4bec2-cf63-49ba-8bed-9eb917ca8d14&qid=1786301794"
},
{
"query": "wired earbuds",
"link": "https://www.amazon.com/s?k=wired+earbuds&ref=rsl_sug_0_3&pd_rd_w=RbQ9n&content-id=amzn1.sym.3be64970-3b95-4a6d-a45d-78077a3ff871:amzn1.sym.3be64970-3b95-4a6d-a45d-78077a3ff871&pf_rd_p=3be64970-3b95-4a6d-a45d-78077a3ff871&pf_rd_r=FCT87YJN2Q2JJ8P2S0DJ&pd_rd_wg=DZW0L&pd_rd_r=64a4bec2-cf63-49ba-8bed-9eb917ca8d14&qid=1786301794"
},
{
"query": "airpods",
"link": "https://www.amazon.com/s?k=airpods&ref=rsl_sug_0_1&pd_rd_w=RbQ9n&content-id=amzn1.sym.3be64970-3b95-4a6d-a45d-78077a3ff871:amzn1.sym.3be64970-3b95-4a6d-a45d-78077a3ff871&pf_rd_p=3be64970-3b95-4a6d-a45d-78077a3ff871&pf_rd_r=FCT87YJN2Q2JJ8P2S0DJ&pd_rd_wg=DZW0L&pd_rd_r=64a4bec2-cf63-49ba-8bed-9eb917ca8d14&qid=1786301794"
},
"… 4 more (truncated for this sample — the API returns all of them)"
],
"refinements": {
"Popular Shopping Ideas": [
{
"name": "Noise Cancelling",
"value": null,
"link": "https://www.amazon.com/s?k=noise+cancelling+wireless+earbuds…"
},
{
"name": "Long Battery",
"value": null,
"link": "https://www.amazon.com/s?k=wireless+earbuds+long+battery+lif…"
},
{
"name": "For Iphone",
"value": null,
"link": "https://www.amazon.com/s?k=wireless+earbuds+for+iphone&ref=s…"
},
"… 6 more (truncated for this sample — the API returns all of them)"
],
"Eligible for Free Shipping": [
{
"name": "Free Shipping by Amazon Get FREE Shipping on eligible orders shipped by Amazon",
"value": "p_76:1249137011",
"link": "https://www.amazon.com/s?k=wireless+earbuds&rh=p_76%3A124913…"
}
],
"… 38 more refinement groups (truncated)": []
},
"ad_blocks": [
{
"position": 1,
"block_type": "product_carousel",
"title": "Beats wireless earbuds",
"brand_logo": "https://m.media-amazon.com/images/S/al-na-9d5791cf-3faf/9b225186-5e85-…",
"link": "https://aax-us-east-retail-direct.amazon.com/x/c/JDEonyLuvwqTF_FMQStb_…",
"products": [
"B08L6ZYW21",
"… 7 more (truncated for this sample — the API returns all of them)"
]
},
"… 1 more (truncated for this sample — the API returns all of them)"
],
"video_blocks": [
{
"position": 1,
"title": "Active Noise Cancelling Ear Buds Wireless Earbuds 80H Playtime Bluetooth Headphones with LED Display Case, Hi-Res Audio Clear Calls Earphones with Over Ear Hooks for Running Gym Workout Travel Black",
"video_link": "https://m.media-amazon.com/images/S/al-na-9d5791cf-3faf/23f44a7d-0e24-…",
"thumbnail": "https://aax-us-east-retail-direct.amazon.com/e/is/D8A8F2B64B75DAA625F6…",
"link": "https://aax-us-east-retail-direct.amazon.com/x/c/JBIrL6YvEshoz2D7-AncY…",
"sponsored": true
},
"… 1 more (truncated for this sample — the API returns all of them)"
],
"brand_stores": []
}
Honesty notes — measured, not assumed
All of these were measured on live captures (2026-08-09). Build against them rather than against assumptions carried over from other SERP APIs.
- Result count per page is Amazon’s choice, not ours — and it varies. Measured on the same day: 16 results for wireless earbuds on us/uk/de, 48 for a Japanese query on jp, 48 for yoga mat on us. Read
search_information.results_begin/results_endrather than assuming 48 per page. total_resultsis Amazon’s own estimate (“over 20,000”), not a countable number. Do not present it as precise.pagination.total_pagesis the highest page Amazon is currently offering in its pagination window, not the true last page.sponsoredwill usually befalse. On every capture measured, Amazon put its paid placements in separate sponsored-brand carousels outside the organic result grid, so the organic cards correctly report false. Inline sponsored results do occur on other queries and are detected — butexclude_sponsoredis therefore often a no-op.is_primeis layout-dependent and often absent (measured: 8 prime icons page-wide on de, 1 on us, 0 on jp).falsemeans “no Prime icon rendered on this card”, not “not Prime”. Do not filter on it.recent_salesis Amazon’s verbatim badge string in the page’s own language (5K+ bought in past month,5000+ Mal im letzten Monat gekauft,過去1か月で1000点以上購入されました). Parse it downstream if you need a number; do not assume English.spelling_correctionreports Amazon’s autocorrect; it does not suppress it. There is no documented Amazon parameter that disables autocorrect, so we report what happened instead of shipping a flag that silently does nothing.- Latency is seconds, not milliseconds — typically ~8–13 s on the warm path, occasionally up to ~90 s when the retry ladder runs. Set client timeouts to 180 s+, and do not put this behind a UI that expects a warehouse query. Expect the occasional block (a clean, unbilled
502). ad_blocks— sponsored-brand placements.block_typeisproduct_carousel(a few promoted ASINs inproducts[]) orbrand_banner(headline + logo, no ASINs).linkis an Amazon ad-redirector (amazon-adsystem.com), NOT a clean product/store URL — do not present it as one. Usually 0–2 per page.video_blocks— sponsored video units.video_linkis an mp4,thumbnailan image,linkan ad-redirector. Almost alwayssponsored: true. Usually 0–2 per page.brand_stores— Amazon Brand Store links, organic only. Only organic store headers (readable brand name + a/stores/page/<id>URL) are returned; a store link that only appears inside a sponsored unit has no readable identity and is deliberately excluded rather than returned as an all-null row. On sponsored-heavy pages this list is legitimately empty — that is correct, not a miss.- Blocked fetches are never reported as empty successes. The fetch is judged by content (did a real results page come back), not by HTTP status — Amazon serves perfect pages with status 202 and blocks with status 200, so status is meaningless here. A genuine block is a
502with a reason, unbilled. list_priceis only served when it is aboveprice(2026-09-30). A list price at or below the price is not a discount: it is returned asnulland its figure is removed fromprices.- Credits: 1 per page actually fetched (
request_metadata.pages_fetched) — never per page requested; blocked fetches and zero-result answers are never billed.
Walmart search 2026-10-18
country=walmart searches walmart.com right now (typically 4–12 s a page; set
client timeouts to 180 s) and answers in the Amazon shape wherever a key means the same thing.
| Param | On Walmart |
|---|---|
| q | required, up to 200 characters |
| page / max_page | at most 3 pages per call (max_page − page + 1 ≤ 3, more is a 422); position continues across pages |
| sort_by | featured (Walmart’s best match) · price_low_to_high · price_high_to_low · average_review · most_recent (new arrivals) · bestseller_rankings (best sellers) |
| exclude_sponsored, number_of_results | as on Amazon |
| category_id, refinements | Amazon-only: a 422 on Walmart, never billed |
- Same keys as Amazon:
position,asin(the Walmart item ID, which /v1/product takes withcountry=walmart),title,link,image,rating,ratings_total,price/list_price/prices(the same{symbol, value, currency, raw}objects;list_priceonly when above the price),badges,recent_sales,sponsored,delivery,availability.raw. - Walmart adds
item_id,page,unit_price(as walmart.com prints it),seller {name, id},additional_offer_count,availability.in_stock,flags(Best seller, Rollback and the like),category_path,unit_typeandorganic_rank(the rank among non-sponsored results);search_informationcarriestotal_resultsand anycorrected_query. - Not on Walmart:
is_prime,refinements,ad_blocks,video_blocks,brand_stores. Only the results grid comes back: Walmart’s recommendation carousels are skipped, and sponsored products sit inline in the grid withsponsored: true. - Prices and delivery promises are the ones walmart.com shows for the store it mapped the request to,
named in
location(postal_code,city,state,store_id). A store or ZIP cannot be chosen, and fresh grocery prices differ between stores. - Credits: 2 per results page returned. An empty result set, a failed fetch (502) and a busy
refusal (503 with
Retry-After) are never billed. At most 5 live Walmart reads run at once across all customers. - As a batch:
kind: "search"withcountry: "walmart"(search batches).
GET /v1/bestsellers live Amazon Best Sellers 2026-10-09
Amazon’s Best Sellers list for one category, fetched live — up to 100 products in
Amazon’s rank order, the category’s full breadcrumb name, and its subcategories with their URLs, so you can
walk the tree. Give it a marketplace’s root best-sellers URL (or just country) and it returns the
top-level categories instead. Root → category → subcategory, always by the URLs a previous answer returned.
| Param | Notes |
|---|---|
| url | any Amazon Best Sellers URL: a category (/gp/bestsellers/kitchen/289814, /Best-Sellers-…/zgbs/…, with or without the /ref=… tail, the query string or a /-/en/ prefix) or a marketplace’s root (/gp/bestsellers/). The marketplace comes from the host: amazon.com, .co.uk, .de, .ca, .com.au, .fr, .it, .es, .co.jp, .com.mx, .com.br. URL-encode it (curl -G --data-urlencode). |
| country | optional. Alone (no url): that marketplace’s root list of top-level categories. With url: must match the URL’s marketplace, otherwise 422. us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted). Amazon only. |
| pages | 1 = ranks 1–50 · 2 = ranks 1–100 (default). Page 2 is fetched only when page 1 is full; Amazon shows no more than 100. |
curl -G "https://api.logimu.com/v1/bestsellers" \ --data-urlencode "url=https://www.amazon.com/gp/bestsellers/kitchen/289814" \ -H "X-API-KEY: sk_live_..." # the root list of top-level categories (free) curl "https://api.logimu.com/v1/bestsellers?country=de" -H "X-API-KEY: sk_live_..."
Sample response — a real live fetch of Cookware on us (captured
2026-10-09, 21.9 s, two pages, 100 products, 16 subcategories). Long arrays are truncated with an explicit
marker; the API returns all of them. Billing fields omitted.
{
"ok": true,
"marketplace": "us",
"page_type": "category",
"request_parameters": {
"url": "https://www.amazon.com/gp/bestsellers/kitchen/289814",
"marketplace": "us",
"pages": 2
},
"request_metadata": {
"created_at": "2026-10-09T06:14:05.152987+00:00",
"processed_at": "2026-10-09T06:14:27.073931+00:00",
"total_time_taken": 21.92,
"amazon_url": "https://www.amazon.com/gp/bestsellers/kitchen/289814",
"pages": [
{
"page": 1,
"ok": true,
"attempts": 1,
"fetch_ms": 11056
},
{
"page": 2,
"ok": true,
"attempts": 1,
"fetch_ms": 9271
}
]
},
"current_category": {
"name": "Cookware",
"full_name": "Home & Kitchen › Kitchen & Dining › Cookware",
"path": [
{
"name": "Home & Kitchen",
"url": "https://www.amazon.com/Best-Sellers-Home-Kitchen/zgbs/home-garden",
"node_id": null,
"slug": "home-garden"
},
{
"name": "Kitchen & Dining",
"url": "https://www.amazon.com/Best-Sellers-Home-Kitchen-Kitchen-Dining/zgbs/home-garden/284507",
"node_id": "284507",
"slug": "home-garden"
},
{
"name": "Cookware",
"url": "https://www.amazon.com/Best-Sellers-Kitchen-Cookware/zgbs/home-garden/289814",
"node_id": "289814",
"slug": "home-garden"
}
],
"node_id": "289814",
"url": "https://www.amazon.com/Best-Sellers-Kitchen-Cookware/zgbs/home-garden/289814",
"title": "Kitchen Cookware"
},
"subcategories": [
{
"name": "Au Gratin Pans",
"url": "https://www.amazon.com/Best-Sellers-Home-Kitchen-Au-Gratin-Pans/zgbs/home-garden/3737261",
"node_id": "3737261",
"slug": "home-garden"
},
{
"name": "Bakers & Casseroles",
"url": "https://www.amazon.com/Best-Sellers-Home-Kitchen-Bakers-Casseroles/zgbs/home-garden/289671",
"node_id": "289671",
"slug": "home-garden"
},
"… 14 more (truncated for this sample)"
],
"bestsellers": [
{
"rank": 1,
"asin": "B0F7M3LVN8",
"title": "CAROTE 21pcs Pots and Pans Set Non Stick, Detachable Handle Cookware, Black | Induction Compatible, Dishwasher & Oven Safe, Kitchen Organization, for Camping/RV/Traveling, Cooking Set, House Warming Gift",
"link": "https://www.amazon.com/dp/B0F7M3LVN8",
"image": "https://images-na.ssl-images-amazon.com/images/I/81QDn2BzpXL._AC_UL300_SR300,200_.jpg",
"rating": 4.5,
"ratings_total": 3732,
"price": {
"symbol": "$",
"value": 59.99,
"currency": "USD",
"raw": "$59.99"
},
"position": 1
},
{
"rank": 2,
"asin": "B0732NXYNS",
"title": "CAROTE Nonstick Frying Pan, 8 Inch Classic Granite Skillet | Kitchen Healthy Non Toxic Stone Cookware,All-Stovetop Compatible, Cool Handle, Easy to Clean, PFOA Free",
"link": "https://www.amazon.com/dp/B0732NXYNS",
"image": "https://images-na.ssl-images-amazon.com/images/I/71FheZz5ZVL._AC_UL300_SR300,200_.jpg",
"rating": 4.6,
"ratings_total": 36169,
"price": {
"symbol": "$",
"value": 14.99,
"currency": "USD",
"raw": "$14.99"
},
"position": 2
},
"… 98 more (truncated for this sample — the API returns all of them)"
],
"pagination": {
"pages_requested": 2,
"pages_fetched": 2,
"total_results": 100,
"partial": false,
"page_errors": {}
},
"observed_at": "2026-10-09T06:14:27.073931+00:00",
"cached": false,
"cache_age_seconds": 0
}
The root list (country=us, or the root URL; captured 2026-10-09, 15.8 s, 40
categories) — page_type: "root" and categories[] instead of products:
{
"ok": true,
"marketplace": "us",
"page_type": "root",
"request_parameters": {
"url": "https://www.amazon.com/gp/bestsellers/",
"marketplace": "us",
"pages": 2
},
"request_metadata": {
"created_at": "2026-10-09T06:13:49.164598+00:00",
"processed_at": "2026-10-09T06:14:04.925670+00:00",
"total_time_taken": 15.76,
"amazon_url": "https://www.amazon.com/gp/bestsellers",
"pages": [
{
"page": 1,
"ok": true,
"attempts": 1,
"fetch_ms": 14980
}
]
},
"current_category": {
"name": "Any Department",
"full_name": null,
"path": [],
"node_id": null,
"url": "https://www.amazon.com/gp/bestsellers"
},
"categories": [
{
"name": "Amazon Devices & Accessories",
"url": "https://www.amazon.com/Best-Sellers-Amazon-Devices-Accessories/zgbs/amazon-devices",
"node_id": null,
"slug": "amazon-devices"
},
{
"name": "Amazon Renewed",
"url": "https://www.amazon.com/Best-Sellers-Amazon-Renewed/zgbs/amazon-renewed",
"node_id": null,
"slug": "amazon-renewed"
},
{
"name": "Appliances",
"url": "https://www.amazon.com/Best-Sellers-Appliances/zgbs/appliances",
"node_id": null,
"slug": "appliances"
},
"… 37 more (truncated for this sample)"
],
"observed_at": "2026-10-09T06:14:04.925670+00:00",
"cached": false,
"cache_age_seconds": 0
}
| Field | Meaning |
|---|---|
| page_type | category (products + subcategories) or root (the top-level categories) |
| current_category | name, full_name = the breadcrumb path (ancestors › current) in the page’s language, path[] (each ancestor’s name, url, node_id, slug), node_id, url, title (the page heading, when the page has one) |
| subcategories[] · categories[] | the current category’s direct children (empty on a leaf) · the root’s top-level categories — name, url (pass it back as url), node_id, slug |
| bestsellers[] | rank, position, asin, title, link, image, rating, ratings_total, price (symbol, value, currency, raw) — pass any asin to /v1/product for its history |
| pagination | pages_requested, pages_fetched, total_results, partial (page 2 failed after page 1 succeeded), page_errors |
| observed_at · cached · cache_age_seconds | when the list was fetched from Amazon; whether this answer came from our cache and how old it is (category answers are kept 30 min, the root list 24 h; Amazon refreshes these lists hourly) |
| Status | Meaning | Billed |
|---|---|---|
| 200 | the list (or the root categories); pagination.partial: true when page 2 failed after page 1 | per page of 50 returned · root 0 |
| 404 | category_not_found — Amazon answered “not found” on every attempt (a failed fetch is never turned into a not-found) | no |
| 422 | bad input, rejected before any fetch: no url and no country, not an Amazon host, not a best-sellers path, country ≠ the URL’s marketplace, pages not 1 or 2, an unknown parameter | no |
| 502 | Amazon blocked or did not serve the page after retries — a collection failure, retry | no |
| 503 | every live-fetch slot for the marketplace is busy (shared with /v1/serp: us/uk 2 concurrent, others 1) — retry after Retry-After | no |
Honesty notes
- Names are in the page’s language. German pages are local (Küche, Haushalt & Wohnen › Abfall & Recycling); on fr, it, es, jp, mx and br we request Amazon’s English page, so names come back in English; us, uk, ca and au are English.
- Ranks are Amazon’s at fetch time, and Amazon refreshes the lists hourly. Read
observed_atandcached: an answer can be up to 30 min old for a category, 24 h for the root list. priceisnullwhen the card shows none (the product is unavailable); a price range is reported as its low end, withrawkeeping Amazon’s text.titleorratingcan benullfor the few entries the grid did not render — their rank and ASIN are still listed.node_idisnullwhere Amazon’s URL carries only a slug (most top-level departments). Navigate byurl, which always works.- Media departments (Books, Kindle Store, Movies & TV, …) are listed exactly as Amazon lists them.
- An empty category (Amazon lists no products) is a
200withbestsellers: []and its subcategories, and is not billed. - This is Amazon’s list now, not a history. For a product’s rank over time use
bsr_history=trueon /v1/product. - Latency is seconds: ~15–35 s for a fresh top 100 (the two pages are fetched one after the other), ~15 s for a root list, milliseconds from our cache. Set client timeouts to 180 s+.
- Credits: 1 per page of 50 products returned (the full top 100 = 2), whether the list came fresh or from our cache — it is the same list. The root list is free; a not-found category, a blocked fetch and an empty list are never billed; a partial answer bills the page it returned. On the MCP connector the same rules apply to the
bestsellerstool (API key required).
GET /v1/deals live Amazon Today’s Deals 2026-10-18
Amazon’s Today’s Deals page for one marketplace, fetched live — every deal with its deal price and
Amazon’s reference price, percent off, deal type and state, how much of a lightning deal is claimed and when it ends, and
coupons, filtered the way Amazon’s own page filters it: department, deal collection (lightning deals, coupons, trending,
started / ending today, or any collection the page lists), percent off, price, Prime Exclusive, rating and brand. Every answer also
lists the page’s departments, collections and facets, so the next call can filter by them, and filter_check says
whether Amazon applied each filter you asked for.
| Param | Notes |
|---|---|
| country | us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted). Required unless url is given; with url it must match the URL’s marketplace, otherwise 422. Amazon only (walmart is a 422). |
| url | optional — an Amazon deals URL: /deals, /events/deals or /gp/goldbox, optionally behind a /-/xx/ language prefix. The host decides the marketplace, and the query string is kept (a discounts-widget filter copied from the browser works). URL-encode it (curl -G --data-urlencode). |
| category_id | a deals department id from categories[] of any answer (comma list accepted; Amazon applies one department at a time). |
| deal_types | one of lightning_deal, trending, coupons, started_today, ending_today — the collections every marketplace carries (Rainforest’s names). Not together with collection. |
| collection | any other collection id from collections[] of an answer (e.g. deals-collection-deals-under-20 on de). Collections differ per marketplace and over time. Not together with deal_types. |
| min_discount · max_discount | percent off, 0–100. discount = Rainforest’s form: 10_percent_off, 25_percent_off, 50_percent_off or 70_percent_off (= min_discount; not together with it). |
| min_price · max_price | the deal price in the marketplace currency. Amazon applies whole units and silently ignores a fractional bound, so a fraction is rounded outward (min_price=25.5 asks Amazon for 25 and up). |
| prime_exclusive | true = Prime Exclusive deals only. |
| minimum_rating | 1–4 (or 4_and_up): products rated at least that many stars. |
| brand | a brand id from facets.brands of an answer, e.g. 811979|dreame. |
| page · page_size · pages | page 1–400 (default 1) · page_size 30, 60 (default), 90 or 120 — Amazon serves deals pages in steps of 30 and ignores any other size, so any other value is a 422; every page is 1 credit whatever its size, so 120 gives the most deals per credit · pages 1–5 (default 1): consecutive pages from page merged into one answer, stopping early on a short page; 1 credit per page that returned deals. |
# lightning deals on amazon.de curl "https://api.logimu.com/v1/deals?country=de&deal_types=lightning_deal" -H "X-API-KEY: sk_live_..." # Electronics on amazon.com.au at 50% off or more, 120 deals (1 credit) curl "https://api.logimu.com/v1/deals?country=au&category_id=4851799051&min_discount=50&page_size=120" \ -H "X-API-KEY: sk_live_..."
Sample response — a real live read of the au deals page (captured 2026-10-18, 12.9 s,
the first 30 deals). Long arrays are truncated with an explicit marker; the API returns all of them. Billing fields omitted.
{
"ok": true,
"marketplace": "au",
"request_parameters": {
"marketplace": "au",
"page": 1,
"page_size": 30,
"pages": 1
},
"request_metadata": {
"created_at": "2026-10-18T14:19:11.115202+00:00",
"processed_at": "2026-10-18T14:19:24.029012+00:00",
"total_time_taken": 12.91,
"amazon_url": "https://www.amazon.com.au/deals?promotionsSearchStartIndex=0&promotionsSearchPageSize=30",
"pages": [
{
"page": 1,
"ok": true,
"attempts": 1,
"fetch_ms": 12630
}
]
},
"deals": [
{
"position": 1,
"asin": "B0GQW7YVG4",
"title": "Apple 2026 11-inch iPad Air (Wi-Fi + Cellular, 128GB) - Purple (M4)",
"link": "https://www.amazon.com.au/Apple-11-inch-Wi-Fi-Cellular-128GB/dp/B0GQW7YVG4",
"image": "https://m.media-amazon.com/images/I/71qYe0WIQlL.jpg",
"deal_id": "a8f3176b",
"deal_link": "https://www.amazon.com.au/deal/a8f3176b",
"deal_type": "BEST_DEAL",
"is_lightning_deal": false,
"deal_state": "AVAILABLE",
"percent_claimed": null,
"ends_at": null,
"deal_price": {
"value": 1237.0,
"currency": "AUD",
"symbol": "$",
"label": "Deal Price:"
},
"list_price": {
"value": 1499.0,
"currency": "AUD",
"symbol": "$",
"label": "RRP:"
},
"percent_off": 17,
"savings": {
"value": 262.0,
"currency": "AUD",
"symbol": "$"
},
"deal_badge": "17% off · Limited time deal",
"is_prime_price": false,
"coupon": null,
"brand": "Apple",
"brand_id": "110955",
"department_ids": [
"4851683051",
"4851684051"
],
"product_group": "premium_ce_brands_display_on_website",
"product_type": "TABLET_COMPUTER",
"variations": 25
},
{
"position": 2,
"asin": "B0FJG66CD1",
"title": "dreame L40 Ultra CE New Model Robot Vacuum DuoScrub &Liftable 13,000Pa Suction, Mop & Self Cleaning, Auto-Empty,TriCut Brush,Flexible App Control,3DAdapt",
"link": "https://www.amazon.com.au/DuoScrub-Liftable-Cleaning-Auto-Empty-Flexible/dp/B0FJG66CD1",
"image": "https://m.media-amazon.com/images/I/41Rd9T-ROUL.jpg",
"deal_id": "f13d187a",
"deal_link": "https://www.amazon.com.au/deal/f13d187a",
"deal_type": "BEST_DEAL",
"is_lightning_deal": false,
"deal_state": "AVAILABLE",
"percent_claimed": null,
"ends_at": null,
"deal_price": {
"value": 474.99,
"currency": "AUD",
"symbol": "$",
"label": "Deal Price:"
},
"list_price": {
"value": 2199.0,
"currency": "AUD",
"symbol": "$",
"label": "RRP:"
},
"percent_off": 78,
"savings": {
"value": 1724.01,
"currency": "AUD",
"symbol": "$"
},
"deal_badge": "78% off · Limited time deal",
"is_prime_price": false,
"coupon": null,
"brand": "dreame",
"brand_id": "811979",
"department_ids": [
"4851975051",
"4851976051"
],
"product_group": "kitchen_display_on_website",
"product_type": "ROBOTIC_VACUUM_CLEANER",
"variations": 2
},
"… 28 more (truncated for this sample — the API returns all of them)"
],
"categories": [
{
"category_id": "4974332051",
"name": "Amazon Devices & Accessories",
"selected": false
},
{
"category_id": "3969342051",
"name": "Audible Books & Originals",
"selected": false
},
{
"category_id": "4851454051",
"name": "Automotive",
"selected": false
},
"… more departments (truncated for this sample)"
],
"collections": [
{
"id": "discounts-collection-for-you",
"name": "For you",
"type": "filter",
"url": null
},
{
"id": "trending-bubble",
"name": "Trending",
"type": "filter",
"url": null
},
{
"id": "deals-collection-coupons",
"name": "Coupons",
"type": "filter",
"url": null
},
"… more collections (truncated)"
],
"facets": {
"brands": [
{
"id": "110955|Apple",
"name": "Apple",
"selected": false
},
{
"id": "811979|dreame",
"name": "dreame",
"selected": false
},
"… more brands (truncated)"
],
"reviewRating": [
{
"id": "4",
"name": "4 stars & up",
"selected": false
}
],
"price": {
"min": 0,
"max": 5900
},
"percentOff": {
"min": 0,
"max": 100
},
"accessType": [
{
"id": "1",
"name": "Prime Exclusive",
"selected": false
}
]
},
"selected_filters": [],
"filter_check": {},
"pagination": {
"page": 1,
"page_size": 30,
"pages_requested": 1,
"pages_fetched": 1,
"start_index": 0,
"returned": 30,
"has_more": true,
"partial": false,
"page_errors": {}
},
"amazon": {
"marketplace_id": "A39IBJ37TRP1C6",
"locale": "en_AU",
"currency": "AUD"
},
"observed_at": "2026-10-18T14:19:24.029012+00:00",
"cached": false,
"cache_age_seconds": 0
}
One entry of deals[] from a de answer for lightning deals (deal_types=lightning_deal; captured 2026-10-18, 8.5 s, 30 deals) — percent_claimed, the countdown in ends_at and a coupon; labels in the page’s language:
{
"position": 24,
"asin": "B07JNHK2KL",
"title": "Arotelicht 4er 3W LED Treppenlicht 230V Warmweiß 3000K IP65 Quadratisch Treppenleuchte Wandeinbauleuchte Wandleuchte Stufenlicht Wand Einbauleuchte Mauer Beleuchtung außen Lampe Alu, Grau Flurleuchte",
"link": "https://www.amazon.de/Arotelicht-Wandeinbauleuchte-Wandeinbaustrahler-Treppenlicht-Wandleuchte/dp/B07JNHK2KL",
"image": "https://m.media-amazon.com/images/I/51+LXNaXpkL.jpg",
"deal_id": "900f09b4",
"deal_link": "https://www.amazon.de/deal/900f09b4",
"deal_type": "LIGHTNING_DEAL",
"is_lightning_deal": true,
"deal_state": "AVAILABLE",
"percent_claimed": 0.0,
"ends_at": "2026-10-18T18:00:00.000Z",
"deal_price": {
"value": 32.29,
"currency": "EUR",
"symbol": "€",
"label": "Angebotspreis:"
},
"list_price": {
"value": 37.99,
"currency": "EUR",
"symbol": "€",
"label": "Statt"
},
"percent_off": 15,
"savings": {
"value": 5.7,
"currency": "EUR",
"symbol": "€"
},
"deal_badge": "15 % Rabatt · Endet in",
"is_prime_price": false,
"coupon": {
"text": "mit Rabattgutschein",
"amount": null,
"currency": null,
"promotion_id": "A6DA5CYLC2ZL6",
"link": "https://www.amazon.de/promo/A6DA5CYLC2ZL6"
},
"brand": "Arotelicht",
"brand_id": "567438",
"department_ids": [
"213083031",
"213084031"
],
"product_group": "lighting_display_on_website",
"product_type": "LIGHT_FIXTURE",
"variations": 7
}
| Field | Meaning |
|---|---|
| deals[] | position, asin, title, link, image, deal_id + deal_link (Amazon’s deal page), deal_type and deal_state (Amazon’s own codes, e.g. BEST_DEAL / LIGHTNING_DEAL, AVAILABLE), is_lightning_deal, percent_claimed, ends_at (UTC, the countdown’s end), deal_price and list_price (value, currency, symbol, label = Amazon’s own words: Deal Price, RRP, Was, Typical price, UVP, Statt …), percent_off, savings, deal_badge, is_prime_price, coupon (text, amount, currency, promotion_id, link) or null, brand, brand_id, department_ids, product_group, product_type, variations — pass any asin to /v1/product for its history or to /v1/offers for every seller |
| categories[] | the page’s departments: category_id (pass it back as category_id), name, selected |
| collections[] | the page’s deal collections: id (pass it back as collection), name, type, url |
| facets | brands[] (id for brand, name, selected), reviewRating[], price and percentOff ranges (min, max; not every marketplace shows a percent-off range), accessType[] (Prime Exclusive, where offered) |
| selected_filters · filter_check | the refinements Amazon reports as applied (facet, id, name) · per filter you asked for: applied, not_applied or unverified — departments, Prime Exclusive, rating and brand from Amazon’s own selected refinements, the discount and price ranges from the returned deals, lightning deals from the deal types |
| pagination | page, page_size, pages_requested, pages_fetched, start_index, returned, has_more (the last page came back full), partial (a later page failed after the first), page_errors |
| amazon | marketplace_id, locale and currency of the page read |
| request_parameters · request_metadata | the request as run (a deal_types alias is echoed as its collection, discount as min_discount) · created_at, processed_at, total_time_taken, amazon_url (the page read), pages[] (page, ok, attempts, fetch_ms) |
| observed_at · cached · cache_age_seconds | when the deals were read from Amazon; whether this answer came from our cache and how old it is (kept 15 min: lightning deals move fast) |
| Status | Meaning | Billed |
|---|---|---|
| 200 | the deals — deals may be [] (no deal matches the filters right now, e.g. no lightning deals running at night); pagination.partial: true when a later page failed after the first | 1 per page that returned deals · empty 0 |
| 422 | bad input, rejected before any fetch: neither country nor url, walmart, not an Amazon host or not a deals path, country ≠ the URL’s marketplace, collection with deal_types, discount with min_discount, a minimum above its maximum, page_size not 30 / 60 / 90 / 120, page or pages out of range, an unknown parameter — or, after the fetch, a filter Amazon did not apply (filter_check not_applied, e.g. a category_id that is not one of the marketplace’s deals departments): the detail names the filter, and the unfiltered page Amazon served instead is not returned | no |
| 502 | Amazon blocked or did not serve the deals page after retries (or served another slice than asked) — a collection failure, never “no deals”; retry | no |
| 503 | every live-fetch slot for the marketplace is busy (shared with /v1/serp and /v1/bestsellers: us/uk 2 concurrent, others 1) — retry after Retry-After | no |
There is no 404: a deals page always exists.
Honesty notes
- An empty list is a real answer.
deals: []means Amazon’s page shows no deal for those filters right now (lightning deals come and go by the hour); a fetch that fails is a502, never an empty list. - A filter Amazon did not apply is refused, not served. When
filter_checkmarks a filternot_applied(acategory_idorbrandthe page does not offer, a price or discount range the deals fall outside), Amazon served its unfiltered page instead, so you get a422naming the filter (a tool error on MCP, afailedbatch row) and are never billed.unverifiedanswers are served: Amazon ignores some filters without saying so (an unknown collection id returns the default list, and the page does not echo the collection except lightning deals, which the deal types confirm), so readfilter_checkbefore you rely on one. - No total count. Amazon publishes none on the page;
pagination.has_moresays whether the last page came back full. Walk on withpage. - No start time (the page does not carry one);
ends_atonly where Amazon shows a countdown (lightning deals and “Ends in” deals).percent_claimedisnullwhere Amazon shows no claimed bar. list_priceis Amazon’s reference price with Amazon’s label (RRP, Was, Typical price, UVP, Statt …) andnullwhen the page shows none or one at or below the deal price;percent_offis Amazon’s badge, computed only when there is none. A product without deal details (a Prime price, a coupon item) has the deal fieldsnull.coupon.textis Amazon’s sentence andamountthe money in it as shown — a final price or a saving depending on the sentence; we do not interpret it.- One department at a time.
category_idtakes a list, but Amazon’s department filter is single-select and applies one. - Collections differ per marketplace and over time (event pages, e.g. a Prime Day page on
jp); the fivedeal_typesare the stable ones. - Page language follows our on-demand policy:
de,mxandbrpages are local (labels such as Angebotspreis / UVP),fr,it,esandjpare requested in English. Prices are always numbers. pagesmerges consecutive pages and drops a product that Amazon repeats on the next page, soreturnedcan be one short of the page size times pages.- Latency is seconds: ~10–30 s a page, up to ~2 min for
pages=5(pages are read one after the other); milliseconds from our cache. Set client timeouts to 300 s. - Credits: 1 per deals page fetched that returned at least one deal, whatever its size — 30, 60, 90 or 120 deals are all 1 credit, so
page_size=120gives the most deals per credit;pages=3that all return deals is 3. Fresh or from our 15-minute cache, it bills the same — it is the same page. A page with no deals, an empty list, a blocked fetch, a busy marketplace and bad input are never billed; a partial answer bills the pages it returned. On the MCP connector the same rules apply to thedealstool (API key required), and batches of kinddealsrun one department per line (below).
GET /v1/offers live offers page 2026-10-12
Every offer on a product’s Amazon offers page, fetched live — the “All offers” view, every page of it: seller, seller id, price, shipping cost, condition, buy box, FBA / Prime, ships-from, the delivery promise and the seller’s feedback, plus the buy box and the page’s own header (title, image, rating, review count). No product page is fetched, which makes it the quick way to ask who sells this right now, and at what price, for half a credit. For brand, BSR, listing content or history use /v1/product.
| Param | Notes |
|---|---|
| asin | 10-char ASIN (a print book’s ISBN-10). Provide either asin or gtin. |
| gtin | a barcode instead (UPC / EAN / GTIN / ISBN-13), resolved exactly as on /v1/product, Amazon’s own search included; gtin_resolution says how. A barcode nothing resolves is a 404, never billed. |
| country | us (default), uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted; marketplace is an alias). Amazon only. |
| include_used | optional — true lists the used, refurbished, open-box and collectible offers in current_sellers.sellers too. Either way current_sellers carries used_offer_count, lowest_new and lowest_used, and every row its condition and condition_class (Offer conditions). |
| zip 2026-10-14 | optional — a US 5-digit ZIP: the offers page as Amazon shows it to a shopper at that ZIP, for the question “can this be delivered to my recipient, at what price, from which seller?” (Amazon Fresh and Whole Foods items deliver only to some ZIPs). The answer adds location (zip, accepted, city, state, label — Amazon’s own confirmed “Deliver to”), deliverable (true / false / null when it could not be read: offered to this ZIP right now — an out-of-area ZIP shows Amazon’s ordinary unavailable box, the same words as a stock-out), availability, buybox_state and offers_scope: "page_1" (page 1 of the offers only). A one-off session at that ZIP, never a shared one; nothing is stored, and the usage log keeps the first three digits only. country=us only (422 otherwise). 1 credit when the answer carries an offer; a not-deliverable / no-offers answer, a ZIP Amazon rejects (422 zip_rejected), a 404 and a failed fetch are never billed. ZIP+4 is cut to 5 digits. |
curl "https://api.logimu.com/v1/offers?asin=B07YYJRXQR&country=de" -H "X-API-KEY: sk_live_..." # by barcode curl "https://api.logimu.com/v1/offers?gtin=000113684531&country=us" -H "X-API-KEY: sk_live_..."
Sample response — a real live fetch of B07YYJRXQR on de with
include_used=true (captured 2026-10-12, 15.3 s, 4 offer pages, 35 offers: 31 new and 4 used). Long arrays are
truncated with an explicit marker; the API returns all of them. Billing fields omitted.
{
"source": "live",
"asin": "B07YYJRXQR",
"marketplace": "amazon-de",
"data_source": "amazon DE marketplace — live offers page",
"observed_at": "2026-10-12T15:04:56Z",
"title": "SANDISK 128 GB Ultra Dual Drive GO, USB-C & USB-A, up to 400 MB/s Read | USB flash drive, double-sided plug-in ports for USB-C smartphones, tablets & Mac, automatic data backup",
"image_url": "https://m.media-amazon.com/images/I/31lWWaMJiKS.jpg",
"rating": 4.6,
"reviews_count": 41165,
"currency": "EUR",
"price": 20.94,
"buybox_seller": "ACTECOM",
"buybox_seller_id": "A2R44V09DB41S8",
"seller_count": 35,
"no_sellers": false,
"pages_fetched": 4,
"current_sellers": {
"as_of": "2026-10-12T15:04:56Z",
"offer_count": 35,
"conditions_included": "all",
"used_offer_count": 4,
"buybox_days_observed_30d": 22,
"buybox_observations_total_30d": 167,
"lowest_new": {
"price": 20.94,
"condition": "New",
"condition_class": "new",
"seller": "ACTECOM",
"seller_id": "A2R44V09DB41S8",
"is_fba": true,
"is_prime": true,
"fulfillment": "FBA",
"seller_rating": {
"positive_pct": 99.0,
"feedback_count": 116,
"rating": null,
"observed_at": "2026-10-10T11:56:00Z"
}
},
"lowest_used": {
"price": 14.9,
"condition": "Used - Like New",
"condition_class": "used_like_new",
"seller": "BestArtikel GmbH",
"seller_id": "A3QX82XXUD599A",
"is_fba": false,
"is_prime": false,
"fulfillment": "FBM",
"seller_rating": {
"positive_pct": 79.0,
"feedback_count": 9330,
"rating": null,
"observed_at": "2026-10-10T12:28:14Z"
}
},
"buybox_seller": "ACTECOM",
"sellers": [
{
"seller": "ACTECOM",
"seller_id": "A2R44V09DB41S8",
"price": 20.94,
"is_buybox": true,
"is_fba": true,
"is_prime": true,
"seller_positive_pct": 100.0,
"seller_feedback_count": 117,
"buybox_days_30d": 0,
"buybox_share_30d": 0,
"buybox_observations_30d": 0,
"buybox_observation_share_30d": 0.0,
"condition": "New",
"condition_class": "new",
"ships_from": "Amazon",
"shipping_cost": 0.0,
"fulfillment": "FBA",
"delivery": {
"text": "FREE delivery Friday, 16 October on eligible first order. Order within 55 mins",
"free": true,
"days_min": 4,
"days_max": 4,
"fastest_days": null,
"date_min": null,
"source": "parsed",
"observed_at": null
},
"delivery_eta_days": 4,
"delivery_eta_fastest_days": null,
"seller_rating": {
"positive_pct": 99.0,
"feedback_count": 116,
"rating": null,
"observed_at": "2026-10-10T11:56:00Z"
}
},
{
"seller": "BestArtikel GmbH",
"seller_id": "A3QX82XXUD599A",
"price": 14.9,
"is_buybox": false,
"is_fba": false,
"is_prime": false,
"seller_positive_pct": 78.0,
"seller_feedback_count": 9332,
"buybox_days_30d": 0,
"buybox_share_30d": 0,
"buybox_observations_30d": 0,
"buybox_observation_share_30d": 0.0,
"condition": "Used - Like New",
"condition_class": "used_like_new",
"ships_from": null,
"shipping_cost": 0.0,
"fulfillment": "FBM",
"delivery": {
"text": "FREE delivery Saturday, 17 October on eligible first order. Details",
"free": true,
"days_min": 5,
"days_max": 5,
"fastest_days": null,
"date_min": null,
"source": "parsed",
"observed_at": null
},
"delivery_eta_days": 5,
"delivery_eta_fastest_days": null,
"seller_rating": {
"positive_pct": 79.0,
"feedback_count": 9330,
"rating": null,
"observed_at": "2026-10-10T12:28:14Z"
}
},
"… 33 more (truncated for this sample)"
]
},
"fulfillment": {
"buybox": "FBA",
"buybox_seller": "ACTECOM",
"buybox_seller_id": "A2R44V09DB41S8",
"ships_from": "Amazon",
"is_prime": true,
"offers": {
"amz": 2,
"fba": 6,
"fbm": 27,
"total": 35
},
"amazon_sells": true,
"amazon_holds_buybox": false,
"buybox_delivery": {
"text": "FREE delivery Friday, 16 October on eligible first order. Order within 55 mins",
"free": true,
"days_min": 4,
"days_max": 4,
"fastest_days": null,
"date_min": null,
"source": "parsed",
"observed_at": null
},
"buybox_delivery_eta_days": 4,
"dispatch_latency": null,
"dispatch_days_min": null,
"dispatch_days_max": null,
"delivery_eta_source": null,
"observed_at": "2026-10-12T15:04:56Z",
"source": "live",
"notes": "buybox is the buy-box winner's fulfilment: AMZ = sold by Amazon itself, FBA = a third party fulfilled by Amazon, FBM = merchant-fulfilled. Counts cover the offers listed in current_sellers. Delivery days are read from Amazon's own delivery sentence at the time of the observation, in whole days from that date; ranges give min/max, fastest_days is the paid/Prime fast option when shown. Not billed extra."
},
"seller_ratings": [
{
"seller": "1Deins Computer GmbH",
"seller_id": "A3NOUUHLVV3QXQ",
"seller_positive_pct": 95.0,
"seller_feedback_count": 93648,
"seller_rating": null,
"observed_at": "2026-10-10T14:04:16Z"
},
"… 29 more (truncated for this sample)"
]
}
| Field | Meaning |
|---|---|
| price · buybox_seller · buybox_seller_id | the buy box: its price and seller; null when no offer holds it |
| seller_count · pages_fetched | offers on the page, every condition · offer pages walked (up to 10) |
| no_sellers | true = Amazon lists no offer for the product right now. An answer, not a failure: we serve it only after a second, independent fetch agrees, and never bill it. |
| buybox_condition buybox_condition_source buybox_condition_detail 2026-10-15 | new | used | null (no featured offer): the pinned offer’s condition as measured on this fetch (source is offers_page here; with zip= the same), detail = its condition text or the used storefront’s name (Amazon Resale, Amazon Warehouse, …). Same keys on /v1/product. |
| title · image_url · rating · reviews_count | the offers page’s own header — always the requested ASIN’s, also for a variation Amazon no longer shows a product page for |
| current_sellers | the same block /v1/product returns: as_of, offer_count, conditions_included, used_offer_count, lowest_new, lowest_used, buybox_seller and sellers[] — buy box first, then price ascending — each with seller, seller_id, price, shipping_cost, condition, condition_class, is_buybox, is_fba, is_prime, ships_from, delivery_text and the derived fulfillment / delivery_*, the seller’s feedback (seller_positive_pct, seller_feedback_count, seller_rating) and, from our observations, the 30-day buy-box figures (buybox_days_30d, buybox_share_30d, buybox_observations_30d, buybox_observation_share_30d) |
| fulfillment | the fulfilment block: who fulfils the buy box (AMZ / FBA / FBM), offer counts per kind, delivery days |
| seller_ratings | the feedback record of every seller the answer names |
| observed_at | when the page was fetched (UTC) |
| gtin · gtin_matches · gtin_match_count · gtin_resolution | with gtin= only, as on /v1/product |
| Status | Meaning | Billed |
|---|---|---|
| 200 | the offers page; no_sellers: true when Amazon lists no offer right now | 0.5 with at least one offer · 0 without |
| 404 | asin_not_found — Amazon answered “not found” for the ASIN (Amazon’s answer, not a collection failure); or a barcode nothing resolves | no |
| 422 | bad input, rejected before any fetch: no anchor or both, not an ASIN, Walmart, an unknown marketplace or parameter | no |
| 502 | Amazon blocked or did not serve the offers page after retries — a collection failure, retry | no |
| 503 | every live offers slot for the marketplace is busy, or (with gtin=) the barcode search could not run — retry after Retry-After | no |
Notes
- Latency is seconds: typically 4–12 s — about 4 s for one page, and we walk every page of a long list. Set client timeouts to 120 s+. Concurrent calls for the same product share one fetch.
- The offers page, not the product page. It lists every offer Amazon shows there, second-hand included; the buy box is the pinned offer at the top. The 30-day buy-box figures come from our own observations of the product (0 /
nullfor a seller we have not observed holding it). - The fetch is stored. Each answer also lands in our warehouse, so the product’s /v1/product seller list and history pick it up after the nightly refresh.
- Batches: a list of ASINs runs as
kind: "offers"(Every endpoint as a batch); the CSV has one row per (ASIN, offer). On the MCP connector theofferstool runs the same call, by ASIN or barcode, with the same billing (an API key is required; the no-signup lane does not run live fetches). 2026-10-12
Tracking: POST / GET / DELETE /v1/track hot lane 2026-10-14
Track a product: pin an ASIN into our hot lane so its offers page is re-read every hour, or every 2, 4, 12 or 24 hours,
for as long as your plan is active (or a ttl_days you set). Every read becomes a point in the product’s buybox_price_points_hot
(price, buy-box seller, fulfillment, offer count), so GET /v1/product — its
0.05-credit history_only lane, or a product batch with source: "tracked" — carries
sub-daily buy box, price and offer-count history for it. Popular products are refreshed this often anyway (the lane’s
own selection, several hundred thousand ASINs a day); a tracking guarantees it for the product you name. Add notify_if
with alert_email and / or webhook_url and we tell you when a price, the buy-box seller, the offer count or the
availability crosses a threshold you set (alerts).
0 credits. What a plan sells is a daily allowance of tracked snapshots: an hourly tracking is 24 snapshots a day,
a 4-hour one 6, a 24-hour one 1. When the allowance is spent the call answers 402 tracking_allowance_full with the upgrade link;
when only a longer interval still fits, that interval is granted and the answer says so (granted_interval). Posting the same
ASIN again renews it and sets the new interval (same id). A lapsed subscription keeps its trackings for 7 days, then they pause
(and resume by themselves when the subscription returns). The lane picks a new tracking up within ~10 minutes (pending: true
until then); one fetch serves every account tracking the same ASIN. Amazon marketplaces only.
| Plan | Tracked snapshots / day | ≈ products every 4 h | ≈ products once a day |
|---|---|---|---|
| Solo | 2,500 | 416 | 2,500 |
| Starter | 6,000 | 1,000 | 6,000 |
| Growth | 18,000 | 3,000 | 18,000 |
| Standard | 40,000 | 6,666 | 40,000 |
| Scale | 170,000 | 28,333 | 170,000 |
| Volume | 710,000 | 118,333 | 710,000 |
POST /v1/track
| Body (JSON) | Notes |
|---|---|
| asin | the product’s 10-character ASIN |
| country | us (default), uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted). No Walmart. |
| interval | 1h, 2h, 4h (default), 12h, 24h — how often the lane re-reads the offers page; shorter draws more of the daily allowance (1h = 24 a day) |
| ttl_days | optional, 1–365 — stop after this many days. Omit it and the tracking runs for as long as your plan is active (a lapsed plan keeps it 7 days, then it pauses and resumes with the plan) |
| alert_email | optional 2026-10-14 — true (the account’s own address) or an address: one e-mail per notify_if event, at most 50 a day per tracking, from noreply@logimu.com. false detaches. Works with or without webhook_url |
curl -X POST "https://api.logimu.com/v1/track" -H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"asin": "B07YYJRXQR", "country": "us", "interval": "1h"}'
# answer and track in one call
curl "https://api.logimu.com/v1/product?asin=B07YYJRXQR&country=us&track=true&interval=4h" -H "X-API-KEY: sk_live_..."
# the list, and stopping one
curl "https://api.logimu.com/v1/track?country=us" -H "X-API-KEY: sk_live_..."
curl -X DELETE "https://api.logimu.com/v1/track/123" -H "X-API-KEY: sk_live_..."
# the daily series pull over everything you track: a product batch with source tracked (0.05 a row)
curl -X POST "https://api.logimu.com/v1/batches" -H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"name": "tracked daily", "country": "us", "mode": "cache", "source": "tracked", "include": ["history_only"]}'
Example response of POST /v1/track (illustrative shape; stamps are UTC). in_lane, last_snapshot_at, next_due_at
and lane_snapshots are the lane’s own state for the ASIN, read from its table (mirrored every 10 minutes); they are shared by
every account tracking it.
{
"credits_charged": 0.0,
"credits_remaining": 24871.5,
"created": true,
"id": 123,
"asin": "B07YYJRXQR",
"country": "us",
"marketplace": "amazon-us",
"status": "active",
"interval": "1h",
"interval_min": 60,
"requested_interval": "1h",
"granted_interval": "1h",
"snapshots_per_day": 24.0,
"created_at": "2026-10-14T13:02:11Z",
"expires_at": null,
"runs": "while the plan is active",
"stopped_at": null,
"via": "rest",
"alert_email": null,
"webhook": null,
"in_lane": false,
"lane_interval_min": null,
"last_snapshot_at": null,
"next_due_at": null,
"lane_snapshots": null,
"pending": true,
"note": "Enters the hot lane at the loader's next pull (within ~10 minutes); the first snapshot follows within the interval.",
"allowance": {
"plan": "solo",
"plan_state": "active",
"snapshots_per_day": 2500,
"used_snapshots_per_day": 24.0,
"remaining_snapshots_per_day": 2476.0,
"subscription_until": "2026-11-02T09:15:40Z"
}
}
| Status | Meaning |
|---|---|
| active | tracked; pending: true until the lane has picked it up, then in_lane: true with last_snapshot_at / next_due_at |
| paused | the subscription lapsed more than 7 days ago; resumes by itself when it returns (within 30 days the row is kept as is) |
| expired | the ttl_days you set ran out; post again to renew (a tracking without ttl_days never expires) |
| stopped | DELETE /v1/track/{id}; listed for 30 days, allowance released at once |
| Error | Meaning |
|---|---|
| 402 tracking_allowance_full | the plan’s daily snapshots are in use and even a 24-hour interval does not fit; the body carries allowance_snapshots_per_day, used_snapshots_per_day, requested_snapshots_per_day and upgrade_url. Never billed. |
| 402 tracking_plan_required | the key has no subscription plan (tracking is a plan feature; credits alone do not carry an allowance) |
| 402 tracking_plan_lapsed | the subscription lapsed more than 7 days ago |
| 422 | a Walmart country, an interval other than the five, a malformed ASIN, ttl_days outside 1–365 or a malformed alert_email. Never billed. |
| 404 | DELETE of an id that is not this key’s |
| 503 tracking_capacity | the marketplace’s lane is sold out at every interval (its daily snapshot capacity is shared by every tracking on it); retry_after_seconds, cap_snapshots_per_day, in_use_snapshots_per_day. Capacity is added when this happens. Never billed. |
| 503 tracking_busy | another tracking import was being admitted and this one waited 30 s for its turn (rare); nothing was created, retry in a few seconds (retry_after_seconds). Never billed. |
Alerts: webhooks and e-mail 2026-10-14
Add notify_if to POST /v1/track with webhook_url (a signed POST to your URL) and / or alert_email (an
e-mail per event) and we tell you when a threshold fires on a new observation of the product (the lane’s next read, so
within the tracking’s interval). Thresholds, any subset:
| notify_if key | Fires when |
|---|---|
| price_below | the buy-box price drops below the value (and was not below it on the previous observation) |
| price_above | the buy-box price rises above the value (edge-triggered the same way) |
| price_change_pct | the buy-box price moved by at least this percent since the previous observation, either way |
| buybox_seller_change | true: a different seller holds the buy box than on the previous observation |
| offer_count_below | the number of offers drops below the value |
| offer_count_above | the number of offers rises above the value |
| availability_change | true: the product’s stock state changed since the previous read — between in_stock, no_buybox and out_of_stock. The event carries availability (the new code) and previous_availability (the old), price (the buy-box price, or null), offer_count and, on a no_buybox read, first_offer_price. |
| out_of_stock | true: shorthand for a change to out_of_stock (the same payload) |
| back_in_stock | true: shorthand for a change to in_stock from either other state |
curl -X POST "https://api.logimu.com/v1/track" -H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"asin": "B07YYJRXQR", "country": "us", "interval": "2h",
"webhook_url": "https://hooks.example.com/logimu",
"notify_if": {"price_below": 22.5, "buybox_seller_change": true, "offer_count_above": 15}}'
The answer carries webhook_secret once. Every delivery is a JSON POST with
X-Logimu-Signature: sha256=HMAC-SHA256(secret, raw_body) and X-Logimu-Event (the event name); the body carries
event, tracking_id, asin, marketplace_id, observed_at and the values behind the
event (price / previous_price, the sellers, the counts, the availability text). A non-2xx answer or a timeout
(10 s) is retried after 1, 5 and 30 minutes, then marked failed. GET /v1/track/{id}/events lists a tracking’s events
with their delivery state; GET /v1/track shows the attached webhook (URL and thresholds, never the secret).
Re-posting the tracking with webhook_url: "" (or alert_email: false) detaches it; omitting the fields keeps it.
E-mail alerts carry the event, the values and links to the product and its history; at most 50 a day per tracking (the rest are
recorded as capped in the event log). Thresholds are evaluated on the all-offers observations the hot lane writes (every
2 minutes), so an hourly tracking is told within about an hour of a change, not in real time.
When the buy box is missing: the three stock states 2026-10-14
Every tracked read is recorded, never skipped, and has one of three states, which buybox_price_points_hot
shows per point (state) and the alerts use:
| State | Meaning | What the point carries |
|---|---|---|
| in_stock | a featured (buy-box) offer exists | price = the buy-box price, the seller, fulfillment, offer_count |
| no_buybox | offers exist, but Amazon shows no featured offer (the buy box is suppressed) | price: null, first_offer_price = the cheapest new offer, offer_count; no seller |
| out_of_stock | no offers at all — confirmed by a second read from another location before it is recorded | price: null, offer_count: null |
A read that would turn an in-stock product into no_buybox is also confirmed by a second read first (buy-box presence varies with
the reader’s location). Price alerts compare buy-box prices only: an in_stock read against the last in_stock read, so a
return from a stock-out at a new price fires price_change, and a no_buybox read’s first-offer price never fires one.
buybox_seller_change fires only between two in_stock reads — losing the buy box is an availability_change to
no_buybox, not a seller change. offer_count_below cannot see a stock-out (it has no count): use the state alerts for it.
Every event carries its state; the e-mail says it in words. On GET /v1/product, stock_state / in_stock follow
the newest read when it is newer than the daily history’s last point, and buybox_state always says what the lane saw last.
Bulk: lists, stop and sync 2026-10-14
POST /v1/track takes a list: items (objects with asin and any per-item override) or asins (ASIN strings), up to
1,000 per call; the top-level country, interval, ttl_days, notify_if, webhook_url and
alert_email are the defaults for every item. The answer is HTTP 200 whenever the body parsed: results[] in input order, each
{asin, country, status, id, granted_interval, error} with status created, renewed, refused
(tracking_allowance_full, tracking_capacity, tracking_plan_required) or invalid, plus summary and
allowance. The allowance is consumed in input order; when it runs out the rest come back refused — the call is never
all-or-nothing. One transaction, one request against the rate limit.
curl -X POST "https://api.logimu.com/v1/track" -H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"country": "us", "interval": "4h", "notify_if": {"availability_change": true}, "alert_email": true,
"asins": ["B07YYJRXQR", "B0DS6WTXGP", "B0F3HH834M"]}'
| Call | What it does |
|---|---|
| POST /v1/track/stop | {"ids": [...]} or {"country": "us", "asins": [...]} (up to 1,000): per-item stopped / already_stopped / not_found; the allowance released at once |
| DELETE /v1/track?country=us&asin=B0… | stop one tracking by ASIN instead of id (404 when the key does not track it) |
| POST /v1/track/sync | {"country": "us", "asins": [...], "interval": "4h", ...}: makes the key’s active set on that marketplace equal to the list — creates what is missing (with the fields given), stops active trackings not listed, leaves the rest untouched (their interval and alerts stay). Returns created, stopped, unchanged, refused, invalid with the lists; "dry_run": true shows the same without writing. An empty list is a 422 (use /v1/track/stop to stop everything). The daily call for a list that changes every day: about 10 minutes of single POSTs become one request. |
On the MCP connector the same functions are the track_product (also action: "stop", action: "sync", and asins / ids lists) and list_tracked tools (paid plans); the batch tool runs a product batch with source: "tracked" and the account tool shows the allowance.
Keepa’s API prices tracking in tokens (a marketplace-tracking update is 9 tokens per locale) and deactivates trackings 7 days after a
downgrade; we size each plan’s allowance at no less than twice the marketplace-tracking updates its price would buy there, and keep the
reads priced as they are.
GET /v1/seller 2026-10-04
Paid plans. The seller endpoints and the derived-intelligence endpoints below are available to accounts with a
subscription or purchased credits; a key without one receives 403 paid_plan_required (never billed) and its credits keep working on
/v1/product, /v1/shopping, /v1/search and /v1/serp. On the MCP connector the matching
tools (seller, brand, category, market_lists, keywords) are listed only to those keys.
A seller’s profile by seller id — the A… code in /sp?seller=…,
or the seller_id on any offer /v1/product returns. Rating, lifetime and 12-month counts, positive %,
the feedback summary per period, the rating histogram, up to 5 recent feedback entries and, where the seller publishes one on Amazon,
the business block — plus tracking (since when and how often we have observed the seller) and, with history=true,
the seller’s rating and storefront-size change points. All 11 Amazon marketplaces; no Walmart (no seller pages there).
Our seller tracker re-reads every stored seller about every 14 days, so mode=cache normally returns the full profile without a live fetch. 2026-10-05
| Parameter | Meaning |
|---|---|
| seller_id | required — A + 8–24 letters/digits. |
| country | us (default), uk, de, ca, au, fr, it, es, jp, mx, br. |
| mode | cache: our stored observation — in order: the seller page we fetched in the last 24 h; the seller page as our tracker last read it (the full profile: star rating, per-period feedback, histogram, recent feedback, business block; request_metadata.fetched: false); or, for a seller the tracker has not stored yet, the warehouse record (positive % and feedback count as last seen on a product page, no star rating or business block — the answer carries a note). live: fetch the seller page now (5–20 s, up to ~30 s on a reroute); the fetch also refreshes the stored profile. auto (default): the stored observation when it is younger than max_age_days, else live. A seller the tracker has confirmed as not found is answered 404 without a fetch in cache mode, and in auto while that verdict is fresh. |
| max_age_days | auto only, default 14 2026-10-05 (the tracker’s refresh cadence; was 7). 0 forces a live fetch. |
| history 2026-10-05 | optional — true adds history: ratings[] change points (each observed_at, positive_percent, positive_percent_period, rating, ratings_total, ratings_12m and periods.{30d,90d,12m,lifetime}.{rating,count}) and storefront_size[] (observed_at, total_results), both oldest first, UTC, plus points_returned, truncated and a note. Change points, not daily samples: a point is written only when a value moved, each value holds until the next point, and the last one holds until tracking.last_observed. The series starts when we first observed the seller (tracking.observed_first_seen, 2026-10-04 at the earliest), never when the seller started — expect one or two points per seller for now, more as values move. Storefront size is recorded when a storefront page is fetched (/v1/seller/products mode=live). +0.5 credit once per call when at least one point comes back; an empty history is free. Also available on mode=live answers (the store is refreshed daily, so the newest live point may appear the next day). |
| history_points 2026-10-05 | with history — the latest N change points per series (default 500, max 5,000); truncated: true when more exist. |
Response
| Key | Meaning |
|---|---|
| source | live or cache — what was actually served; mode=auto bills accordingly. |
| seller | seller_id, name, is_amazon, logo, storefront_url, profile_url, rating (12-month average; lifetime when the 12-month count is 0), ratings_total, ratings_total_12m, positive_percent, positive_percent_period (twelve_months | lifetime — the page’s own headline says which), header_ratings_count, icon_rating. Amazon’s own retail seller answers instantly with is_amazon: true. |
| feedback_summary | thirty_days / ninety_days / twelve_months / lifetime → {rating, count}. Amazon no longer publishes positive / neutral / negative splits per period — it shows an average star rating and a count per period, plus one positive-% headline and one histogram for the headline’s period. We do not derive splits from the histogram (its rounding disagrees with the headline). |
| rating_histogram | {period, percent_by_stars: {"5": 78, "4": 7, …}} or null. |
| recent_feedback | up to 5, newest first, each only {date, rating, struck}. Feedback text and the buyer’s name are never collected or returned. |
| business | where Amazon shows a trader block: business_name, business_type, trade_register_number, vat_number, tax_id, share_capital, phone, email, business_address[], customer_service_address[], representative, display_name, is_business_seller, other[] (labels we have no key for). null on au and ca (no trader block on those pages) and in warehouse-only cache answers. |
| observed_at | when the served record was fetched (live) or last observed (stored profile / warehouse record), UTC. |
| tracking 2026-10-05 | present whenever the seller is in our seller store (not billed): observed_first_seen — when we first stored the seller (not when it started selling), last_observed, last_rating_change — when the latest rating change point was written, observations — how many times we have read its page. UTC. |
| history 2026-10-05 | with history=true — see the parameter above. ratings[], storefront_size[], points_returned, truncated, note. |
| request_metadata | fetched: true with the fetch timings on a live answer; fetched: false with processed_at (= observed_at) when the stored profile was served. |
Verdicts (never billed)
- 404
seller_not_found— Amazon’s own 404 for the id on that marketplace, confirmed by more than one attempt; or, incachemode, a seller we have never observed. A confirmed 404 is remembered for a week. - 404
seller_unavailable— a seller we do not serve (opt-out). Same answer in every mode. - 502 — Amazon blocked or did not serve the page after retries. A collection failure, not a fact about the seller; retry. On
amazon.dean unknown id answers with Amazon’s throttle status, so it stays a 502 there, never a 404. - 503 — the marketplace’s live slots are busy (seller pages share the live-search budget: us/uk 2 concurrent, others 1);
Retry-Afteris set.
Rainforest seller_profile mapping
| Rainforest | Logimu |
|---|---|
| seller_profile.name / rating / ratings_total | seller.name / seller.rating / seller.ratings_total |
| seller_profile.positive_percent (per period) | seller.positive_percent + positive_percent_period (Amazon shows one headline now) |
| feedback_summary.*.{positive,neutral,negative} | feedback_summary.*.{rating, count} — the splits no longer exist on Amazon’s page |
| seller_feedback (1 credit per 5) | recent_feedback (5, included; date / rating / struck only) |
| business_name, business_address, … | business.* (included) |
Keepa /seller mapping 2026-10-05
| Keepa seller object | Logimu |
|---|---|
| sellerId / sellerName | seller.seller_id / seller.name |
| trackedSince / lastUpdate / lastRatingUpdate | tracking.observed_first_seen / tracking.last_observed / tracking.last_rating_change (ISO-8601 UTC, not Keepa minutes) |
| currentRating / currentRatingCount | seller.positive_percent (+ positive_percent_period) / seller.ratings_total; the star average is seller.rating |
| csv[0] rating-% history, csv[1] rating-count history | history.ratings[] (positive_percent, ratings_total — plus star rating and the four per-period averages and counts on every point) |
| ratingsLast30Days; positive/neutral/negative per 30 d / 90 d / 365 d / lifetime | feedback_summary.thirty_days.count; feedback_summary.*.{rating, count} — Amazon shows an average and a count per period now, splits only via the histogram for the headline period |
| recentFeedback[].{date, rating (0–50), isStriked} | recent_feedback[].{date, rating (1–5 stars), struck} |
| businessName, address, tradeNumber, vatID, phoneNumber, email, representative | business.{business_name, business_address[], trade_register_number, vat_number, phone, email, representative} — current values, not versioned (as Keepa) |
| totalStorefrontAsins (history) | history.storefront_size[].total_results |
| hasFBA, shipsFromChina, buy-box share, competitors, top brands / categories | not on this endpoint — the observed-products lane (/v1/seller/products mode=cache) carries per-ASIN buy-box days, observed price range and FBA observed; derived seller statistics: not yet |
| per-period positive / neutral / negative splits for the non-headline periods | not yet — Amazon shows them behind a dropdown we do not read; the headline period’s histogram is included |
GET /v1/seller/products 2026-10-04
What a seller sells. Two different things behind one endpoint, chosen with mode:
| Parameter | Meaning |
|---|---|
| seller_id, country | as above. |
| mode | cache (default): the products we have observed this seller offering since Dec 2024 — seller_products[] of asin, buybox_days, days_seen, min_price / max_price / buybox_avg_price, first_seen / last_seen, fba_observed; 25 per page, buy-box days first, has_more for paging. live: the seller’s storefront on Amazon right now — exactly the /v1/serp object (search_results, pagination, refinements…), seconds not ms. |
| page | cache: 1–40 (25 products each). live: Amazon’s page, 1–10. |
| max_page, sort_by, refinements, q | live only, as on /v1/serp; q searches inside the storefront. |
An empty live storefront (result_count: 0 with Amazon’s own no-results page) is a valid answer and is not billed — and it does not confirm the seller exists: on amazon.com an unknown seller’s storefront is a genuine empty page. /v1/seller answers that question. Rainforest’s seller_products ≡ mode=live; the observed-products lane has no Rainforest equivalent.
Derived intelligence 2026-10-05
What our observations add up to. Every product and offer we observe is also an observation about a brand, a seller and a
category. These endpoints serve those aggregates: who sells a brand and how much of it, how contested or Amazon-dominated it is, which brands a
seller carries, which brands are connected because the same sellers win the buy box on both, how a category is structured — and ranked lists to
discover all of that. Everything is computed from observed buy-box data since Dec 2024, refreshed daily; nothing is an estimate, and
every response says so in data_source. The family also carries the one observed signal that is not about listings:
/v1/keywords, Amazon’s own autocomplete suggestion lists as we observe them 2026-10-07. Paid plans only — see the note under /v1/seller.
- Observed, not asserted.
observed_first_seenis when we first recorded the brand or seller — our data horizon, never a founding date. Buy-box days scale with how often we observed a listing; compare shares and per-ASIN ratios across brands, not raw day counts. - Seller identity. A merchant id is returned when we hold a real one; otherwise the seller is named as Amazon prints it. Sellers who have opted out never appear in any row.
- Amazon marketplaces only (
country=us|uk|de|ca|au|fr|it|es|jp|mx|br); Walmart has no derived rows yet. - Pricing: 1 credit per record, 1 per page of 25 rows, 0 for lookups and for anything not found;
history=trueadds +0.5 once. Each key has a daily cap on this family (2,000 calls by default —429 derived_daily_cappast it, never billed).
GET /v1/brand 2026-10-05
The brand dossier. ?brand=Nike&country=us (brand as Amazon prints it, case-insensitive).
| Key | Meaning |
|---|---|
| observed | observed_first_seen, months_observed, oldest_month — how long we have been watching this brand (the data horizon, not the brand’s age). |
| catalog | asins_3m (ASINs with a buy-box observation in the last 3 months), avg_price, avg_rating, bought_past_month_30d (sum of Amazon’s badges), revenue_30d (badge-based signal), velocity_90d_units_per_day, catalog_churn_30d_pct, oos_frequency_30d_pct, asin_count_trend_1m/4m_pct. |
| sellers | unique_sellers_3m, buybox_days_3m, control_score (share of buy-box days won by FBA offers, 0–100), winner_diversity (how spread the buy box is across sellers), amazon_retail_share_pct (Amazon’s own share of buy-box days), fba_penetration_pct, seller_hhi_top3 (concentration), seller_churn_30d_pct and its delta vs the category, pct_asins_gated_to_3p, is_amazon_private_label, seller_pressure_trend (short/long momentum grades, −100…+100, from sellers-per-ASIN recent vs prior). |
| category | the brand’s dominant root category with benchmarks: p25/p50/p75 of control_score, unique_sellers, buybox_days, avg_price across the brands in that root, plus this_brand — so you can place the brand against its peers. |
| top_sellers | up to 10 sellers by observed buy-box days (16-month window), each with seller_id (when real), asins_touched, first_seen/last_seen, avg_price, fba_observed and the seller’s feedback record. The full list: /v1/brand/sellers. |
| history +0.5 | history=true: history.monthly[] up to 24 calendar months — ASINs, unique sellers, buy-box days, FBA buy-box days, price, rating, review total, winner diversity, sellers_per_100_asins; oldest first. |
GET /v1/brand/sellers
?brand=&country=&page= — every seller observed winning the buy box on the brand’s listings in the rolling 16-month window, most buy-box days
first, 25 per page (has_more), each row with the seller’s feedback record. 1 credit per page returned. The window dates are on the response.
Verdicts (never billed)
- 404
brand_not_found— we have not observed the brand on that marketplace. - 503
derived_data_unavailable— the tables are being refreshed on the server; retry later. - 429
derived_daily_cap— the key’s daily cap on derived calls (resets 00:00 UTC).
GET /v1/brand/network 2026-10-05
The brand’s seller map. ?brand=Nike&country=us&limit=20 returns the brands connected to Nike because the same
third-party sellers were observed winning the buy box on both — edges[] with shared_sellers (how many sellers both brands share,
16 months) and each side’s buy-box days, strongest first, up to 50; and nodes[] for the brand and every neighbour with sellers_3m,
asins_3m, control_score, winner_diversity, amazon_retail_share_pct, pressure_score, cluster_id,
trend, category and, on us/uk, layout {x, y, centrality} from our precomputed graph. One hop per call — walk the
graph by calling it on a neighbour. 1 credit. This is the object the network map on www.logimu.com is drawn from.
GET /v1/seller/network
?seller_id=… or ?name=… — the sellers that win the buy box on the same brands as this one (connected_sellers[] with
shared_brands, buy-box days and feedback record), strongest first, up to 50. 1 credit.
GET /v1/seller/brands 2026-10-05
The operator footprint. ?seller_id=A2ENTBEZKGXKVW&country=us or ?name=hearthshire. operator carries the
header — brands_touched, asins_touched, buybox_days (16 months), fba_share_pct, bought_past_month_30d,
revenue_30d (badge-based signal), avg_rating, observed_first_seen/last_seen, top_brands — and brands[]
lists every brand the seller was observed winning the buy box on, most buy-box days first, 25 per page. history=true (+0.5) adds up to 24 months of
brands / ASINs / buy-box days. 1 credit per page. Pairs with /v1/seller (the seller’s own profile page) and
/v1/seller/products (what it lists today). Seller names are canonicalised (lower-case) in this family.
GET /v1/category 2026-10-05
The category landscape. ?category_id=7926&country=us — category_id is the
warehouse’s own id for the category (the one every /v1/search result and
product category chain carries), not an Amazon browse-node id; pass node_id= instead to look a category up by its
Amazon browse-node id 2026-10-07. Find ids with
GET /v1/categories (the taxonomy, free) or
GET /v1/categories/search?q=toothbrush&country=us (by name, free). Keys: size (asins, asins_30d, brands,
unique_sellers_30d, closeout_candidates), pricing, competition (amazon_retail_share_pct,
fba_penetration_pct, amazon_private_label_pct, seller_hhi_top5, avg_heat = competitive intensity 0–100,
avg_winner_diversity, Amazon’s 90-day brand additions and gatings), demand (velocity_tier, bought_past_month_30d,
revenue_30d), catalog_churn_30d, benchmarks (root-level p25/p50/p75), subcategories[] (children, by size) and, for
root categories, top_brands[] (by observed buy-box days). history=true (+0.5): months of products / brands / sellers. 1 credit.
GET /v1/keywords 2026-10-07
What buyers type, as Amazon itself suggests it. ?seed=electric%20toothbrush&country=us — the
suggestion lists Amazon’s search box shows for the seed, as our harvest observed them. We crawl Amazon’s own autocomplete
continuously on all eleven marketplaces (since Aug 2026, each marketplace against its own country host and in its own language) and keep
every list we see: up to 10 terms per prefix × department, with the term’s position in that list and the day
each observation started and ended. This endpoint returns, for the seed, the lists of the longest crawled prefix the seed
extends that has current observations (the seed itself when we crawl it exactly), otherwise the shortest crawled prefix that
extends the seed — up to 6 lists, “all departments” (aps) first — plus related observed vocabulary that starts
with the seed.
| Key | Meaning |
|---|---|
| lists[] | one entry per suggestion list: prefix (the text Amazon was asked for), department (aps = all departments, or an Amazon department alias such as electronics) and terms[] — the current list, in order: keyword, position (1–10 within this list), first_observed / last_observed (the term anywhere in this marketplace’s suggestions), in_list_since (the day the term took this position in this list) and observed_in (the marketplaces whose suggestions carry the same term). |
| list_count | how many lists came back (0–6). |
| related_terms[] | up to related_limit (default 25, max 50) further observed suggestions that start with the seed and are not already in a list, ordered by times_observed — how many harvest passes and prefixes the term surfaced under — with first_observed, last_observed, observed_in. A breadth heuristic, not a demand number. |
| history +0.5 | history=true: history.lists[].observations[] — every observation of each returned list since the harvest began (observed_since), oldest first: keyword, position, valid_from, valid_to (null = still in the list at that position). A term with several rows moved position; a row with valid_to left the list or moved. history_points caps the rows (default 500, max 5,000); points_returned and closed_points say what came back. Billed +0.5 only when closed_points > 0 — a list that never changed costs nothing extra. |
| data_source / note | what the figures are — observed suggestion lists, positions comparable only within one list — on every response. Quote them when you re-publish the numbers. |
What this is not. Amazon publishes no search volume for its suggestions and none is implied here:
a position is a place in one list, never a count, and a term’s position in one list says nothing about its position in another
(the lists are different questions). For the products Amazon shows on page 1 for a term, as we observed it, see
/v1/keywords/rankings (Amazon US, about weekly); for products matching a term in our
catalogue, /v1/shopping?q=. Each
marketplace has its own vocabulary in its own language (country=de returns German suggestions); observed_in is a
text match across marketplaces, useful for brand names and model numbers. Amazon marketplaces only; Walmart has no suggestion corpus.
GET /v1/keywords/compare
?seed=&countries=us,uk,de (2–11 marketplaces) — the seed’s primary list (aps, longest-prefix rule as above)
on each requested marketplace under lists.{cc}, and matrix[]: every term seen in any of those lists with its
positions per marketplace (null where the term is not in that marketplace’s list), observed_in (every marketplace whose
suggestions carry the term at all) and in_requested. Positions compare across the matrix only as “in the list / not in the list”
and as order within one marketplace’s column. 1 credit; nothing observed on any requested marketplace is a free 404.
Verdicts (never billed)
- 404
keywords_not_found— no suggestion observation matches the seed on that marketplace (the harvest is continuous; coverage grows). - 422 — seed under 3 characters, an unknown marketplace, Walmart, or fewer than two distinct marketplaces on
compare. - 503
derived_data_unavailable— the corpus is being refreshed on the server; retry later. - 429
derived_daily_cap— the key’s daily cap on the derived family (2,000 calls by default, resets 00:00 UTC).
curl "https://api.logimu.com/v1/keywords?seed=electric%20toothbrush&country=us" -H "X-API-KEY: $KEY" curl "https://api.logimu.com/v1/keywords?seed=yoga%20mat&country=de&history=true" -H "X-API-KEY: $KEY" curl "https://api.logimu.com/v1/keywords/compare?seed=air%20fryer&countries=us,uk,de,fr" -H "X-API-KEY: $KEY"
{
"marketplace": "us", "source": "warehouse", "seed": "electric toothbrush",
"lists": [
{"prefix": "electric toothbrush", "department": "aps",
"terms": [
{"keyword": "electric toothbrush", "position": 1, "first_observed": "2026-08-07", "last_observed": "2026-10-06",
"in_list_since": "2026-08-07", "observed_in": ["us", "uk", "ca", "au"]},
{"keyword": "electric toothbrush heads", "position": 2, ...}
]},
{"prefix": "electric toothbrush", "department": "beauty", "terms": [...]}
],
"list_count": 2,
"related_terms": [{"keyword": "electric toothbrush for kids", "times_observed": 412, "first_observed": "2026-08-09",
"last_observed": "2026-10-06", "observed_in": ["us", "ca"]}, ...],
"data_source": "Terms observed in Amazon's own autocomplete suggestions, harvested continuously per marketplace since Aug 2026 - ...",
"note": "position = the term's place (1-10) within the suggestion list shown for that prefix; positions are comparable only within one list ...",
"latency_ms": 41
}
GET /v1/keywords/rankings · GET /v1/product/keywords 2026-10-18
Which products show on page 1 for a search, and which searches a product shows up for. We fetch page 1 of
amazon.com search for a set of head search terms — taken from Amazon’s own autocomplete suggestions, all departments, one
fixed US delivery ZIP — about once a week each, and keep what the page showed: the organic order, the sponsored units in the page,
the keyword’s Overall Pick badge (Amazon’s Choice for that keyword) and Amazon’s result count. Amazon US only. The set
fills in week by week; every reverse-ASIN answer carries coverage (terms observed so far, terms in the set, since when).
GET /v1/keywords/rankings
?keyword=chest%20rigs%20tactical — the keyword’s latest observed page 1 (case and spacing
are folded). 1 credit; history=true +0.5 when more than the latest observation exists.
| Key | Meaning |
|---|---|
| organic[] | the non-sponsored results in page order: organic_rank (1–n), asin, badges (overall_pick, best_seller), the product facts we hold (title, brand, price, rating, review_count, image_url) and the product’s latest observed buy box: buybox_seller, buybox_seller_id, fulfillment (AMZ = sold by Amazon, FBA, FBM), other_sellers_count, buybox_observed_date — as of the product’s own observation, not the search page’s. |
| sponsored[] | the sponsored units present in the page HTML: unit (sponsored_products, sponsored_brands, sponsored_brands_video, sponsored_other), slot (the unit’s place on the page), position_in_unit, asin and its facts. |
| sponsored_slots_unresolved | sponsored slots the page HTML holds without the product (Sponsored Products that Amazon loads later by JavaScript): counted, product unknown. |
| page_summary | who holds the page: brands[] and buybox_sellers[] by organic slots (top 10), amazon_buybox_slots, fba_slots, fbm_slots, buybox_known, products_with_facts, overall_pick_asin and sponsored_brands_units[] by brand. Slots on one observed page — never sales or traffic. |
| change_since_previous | when an earlier observation exists: previous_observed_date, entered[] and left[] (organic ASINs that came onto or dropped off page 1). |
| results_total | Amazon’s own “N results” for the search on that page. |
| observed_date / observed_at / scope | when the page was observed (UTC) and what it was: page 1, all departments, the delivery ZIP. |
| head_term / observations | whether the term is a top-level autocomplete term, and how many weekly observations of it we hold. |
| history +0.5 | history=true: observations[] (each stored page oldest first: date, result count, organic order, Overall Pick, sponsored ASINs) and rank_series[] (each product on the latest page with its organic rank in every observation, null when it was not on page 1). history_points keeps the newest N (default 26, max 104). |
GET /v1/product/keywords
?asin=B0CCVRQV7C — reverse ASIN: every keyword in the observed set whose latest page 1 shows the product,
organically (with its rank) or in a sponsored unit, organic first and best rank first. placement = all (default),
organic or sponsored; limit 1–200 (default 50) and offset page through it. 1 credit per
started 25 keywords returned; history=true adds each keyword’s rank_history (+0.5 once when any keyword has more than
one observation).
?asins=B0CCVRQV7C,B0FCS6D7Q5,B0BBR3GWW4 — compare up to 10 products, yours first: every keyword where any of
them appears, sorted by how many share the page. Each row adds competitors[] (asin, organic_rank,
sponsored), asins_on_page and gap (a competitor is on page 1 organically, the first product is not);
gaps=true keeps only those rows. The page price applies once per ASIN compared.
| Key | Meaning |
|---|---|
| totals | for the first product: keywords, organic, organic_top_10, sponsored, overall_pick — counted over every keyword, before paging. matched = rows after the filters, before paging. |
| keywords[] | keyword, organic_rank (null when only sponsored, or with asins when only a competitor is there), sponsored[] (unit, slot, position_in_unit), badges, results_total, observed_date, head_term, observations, and with history rank_history[]. |
| products[] | the requested products with the facts and latest buy box we hold. |
| totals_by_asin / gaps_total | with asins: the totals for each product, and how many keywords are gaps for the first one. |
| coverage | terms_observed, terms_in_set, observed_since, scope: how much of the set this answer could draw on. Head search terms and page 1 only, so a product shows fewer keywords than a full search index would. |
What this is. Observed positions with their date and scope — “#4 organic on page 1 of amazon.com
search (all departments) on 2026-10-16”. One search is a sample: the same query fetched minutes apart differs by a few products, so
read a single week as a sighting and the weekly series as the signal. Sponsored means sponsored units present in the page HTML; it says
nothing about spend, bids or impressions. Not volume figures (Amazon publishes none for search terms and none is implied), not a live
ranking (for a live search page use /v1/serp), not personalised.
Verdicts (never billed)
- 404
keyword_not_found— the keyword is not in the observed set yet, or not observed yet:/v1/serp?q=fetches the search live (1 credit per page); terms Amazon suggests are in/v1/keywords. - 404
asin_not_found— the product (or none of the products passed) was not seen on page 1 of any keyword observed so far: a coverage fact. - 422 — a marketplace other than
us, an invalid ASIN, more than 10 ASINs, bothasinandasins,gapswithout competitors, an invalid placement, or an unknown parameter. - 503
derived_data_unavailable— the map is being refreshed on the server; retry later. - 429
derived_daily_cap— the key’s daily cap on the derived family (2,000 calls by default, resets 00:00 UTC).
curl "https://api.logimu.com/v1/keywords/rankings?keyword=chest%20rigs%20tactical" -H "X-API-KEY: $KEY" curl "https://api.logimu.com/v1/keywords/rankings?keyword=chest%20rigs%20tactical&history=true" -H "X-API-KEY: $KEY" curl "https://api.logimu.com/v1/product/keywords?asin=B0CCVRQV7C&placement=organic" -H "X-API-KEY: $KEY" curl "https://api.logimu.com/v1/product/keywords?asins=B0CCVRQV7C,B0FCS6D7Q5,B0BBR3GWW4&gaps=true" -H "X-API-KEY: $KEY"
{
"keyword": "chest rigs tactical", "marketplace": "amazon-us",
"observed_date": "2026-10-16", "scope": "page 1 of amazon.com search, all departments, delivery ZIP 60601",
"results_total": 2000, "organic_count": 48, "head_term": false, "observations": 1,
"organic": [
{"organic_rank": 1, "asin": "B09B5P353R", "badges": [], "title": "ACE TAC S.O.P. Tactical Chest Rig with 5.56/7.62 ...",
"brand": "ACETAC", "price": 95.95, "rating": 4.6, "review_count": 1069,
"buybox_seller": "ace tac", "buybox_seller_id": "AJE0GCLQJGECI", "fulfillment": "FBM", "other_sellers_count": 0,
"buybox_observed_date": "2026-10-16"},
...
],
"sponsored": [{"asin": "B0BBR3GWW4", "unit": "sponsored_brands", "slot": 0, "position_in_unit": 1, "brand": "WYNEX"}, ...],
"sponsored_slots_unresolved": 1,
"page_summary": {"organic_slots": 48, "products_with_facts": 37, "buybox_known": 37,
"brands": [{"brand": "Condor", "organic_slots": 5}, {"brand": "ACETAC", "organic_slots": 3}, ...],
"buybox_sellers": [{"seller": "ace tac", "seller_id": "AJE0GCLQJGECI", "organic_slots": 3}, ...],
"amazon_buybox_slots": 0, "fba_slots": 22, "fbm_slots": 15, "overall_pick_asin": "B0BBR3GWW4",
"sponsored_brands_units": [{"brand": "WYNEX", "units": 3}, ...]},
"data_source": "Page 1 of Amazon US search results ...", "credits_charged": 1.0
}
A compared row from /v1/product/keywords?asins=B0CCVRQV7C,B0FCS6D7Q5,B0DQNVYMRG,B0BBR3GWW4:
{"keyword": "airsoft chest rig", "organic_rank": 23, "badges": [], "results_total": 1000, "observed_date": "2026-10-16",
"competitors": [{"asin": "B0FCS6D7Q5", "organic_rank": 39, "sponsored": false},
{"asin": "B0DQNVYMRG", "organic_rank": 27, "sponsored": false},
{"asin": "B0BBR3GWW4", "organic_rank": 2, "sponsored": false}],
"asins_on_page": 4, "gap": false}
Ranked lists 2026-10-05
Discovery endpoints — 25 rows per page, 1 credit per page returned, has_more for the next page, every row linking to the dossier above.
| Endpoint | Returns |
|---|---|
| GET /v1/brands/movers?country=&window=30|90&direction=up|down&page= | brands whose count of distinct buy-box sellers rose (or fell) most vs the prior window — sellers_recent, sellers_prior, delta, pct_change, category_root_id. |
| GET /v1/brands/top?country=&sort=buybox_days|sellers|control_score|asins|revenue|amazon_share&category_id=&page= | brands ranked by what we observed; category_id (a root) narrows to brands filed under that root. |
| GET /v1/sellers/movers?country=&window=&direction=&page= | sellers whose observed buy-box footprint grew (or shrank) most. |
| GET /v1/sellers/top?country=&sort=brands|buybox_days|asins|revenue&page= | third-party sellers by cross-brand footprint (16 months) — the operators. |
| GET /v1/categories/top?country=&sort=asins|brands|heat|revenue|price|sellers&root_only=true&parent_id=&page= | categories ranked; parent_id lists one category’s children instead of the roots. |
| GET /v1/categories/search?q=&country=&limit= | category ids by name or path — free. Since 2026-10-07 the English alias of a non-English root matches too (q=Automotive finds amazon.de’s Auto & Motorrad; served as name_en), and every row carries amazon_node_id. |
GET /v1/categories — the taxonomy 2026-10-07 · free, any key
The category names /v1/search’s category filter accepts on a marketplace and
the ids /v1/category takes, walked one level at a time: ?country=de returns the marketplace’s root categories
(20–71), ?country=de&parent_id=<category_id> that category’s children. Every active category, with
category_id (ours), amazon_node_id (null for the few roots we file under a best-seller-list slug, served as amazon_list_slug), name (the marketplace’s own language), name_en
(the English alias where we hold one — most roots on amazon.de), path, depth, is_root,
children, and the observed asins / brands counts (null for a category we have not observed yet).
Not billed, every plan (it is what a customer at zero credits needs to use the search filter), rate-limited like every call, cached ten minutes.
Unknown parent_id → 404 category_not_found.
curl "https://api.logimu.com/v1/categories?country=de" -H "X-API-KEY: $KEY" curl "https://api.logimu.com/v1/categories?country=de&parent_id=12345" -H "X-API-KEY: $KEY"
Where this sits next to Keepa and SmartScout
| Theirs | Here |
|---|---|
| Keepa category object: sellerCount, brandCount, soldByAmazonPercent, isFBAPercent, avgBuyBox, topBrands (3) | /v1/category: the same counts and shares plus seller concentration (HHI), heat, churn, demand signals, root benchmarks, sub-categories and the top-10 brands |
| Keepa seller object: sellerBrandStatistics[] (product counts), competitors[] (top 5), buy-box ownership rates — “based on Keepa’s often incomplete and outdated product offers data” (Keepa’s wording) | /v1/seller/brands (brands with observed BUY-BOX DAYS, not product counts) + /v1/seller/network (up to 50 connected sellers by shared brands) |
| Keepa: no brand endpoint, no brand-to-brand network, no trend grades | /v1/brand, /v1/brand/network, seller_pressure_trend, /v1/brands/movers |
| Keepa: no keyword data; Helium 10 / Jungle Scout: estimated search volumes | /v1/keywords: Amazon’s own suggestion lists as observed, positions within each list, since Aug 2026 — no estimates, no volumes claimed |
| SmartScout API: brand market share / history, seller coverage per brand, brand coverage per seller (estimates) | the same questions answered from observed buy-box days, plus the explicit shared-seller network and the ranked movers |
| Rainforest / ScraperAPI, Oxylabs, Pangolin, Unwrangle | live page scrapes only — nothing derived |
GET /v1/account free
Your balance, plan and recent usage — so a script can check what it has left before it spends. Never billed.
curl "https://api.logimu.com/v1/account" -H "x-api-key: $KEY"
| Field | Notes |
|---|---|
| credits_remaining | credits left on the key (null on unmetered internal keys) |
| plan | metered or internal |
| suspended | true when the account is suspended — calls will be refused |
| usage_30d | calls and credits over the last 30 days, plus a per-endpoint breakdown |
| tracking 2026-10-14 | the plan’s product-tracking allowance: plan, plan_state (active / grace / paused / none), snapshots_per_day, used_snapshots_per_day, remaining_snapshots_per_day, subscription_until |
On the MCP connector this is the account tool (any key).
Batch bulk product data
Submit a list of ASINs (or numeric item IDs for country=walmart), get an
exact warehouse/live split and credit price before anything runs or bills,
then run it and stream results as JSONL or CSV — partials included, mid-run. Rows are served
through the same path as /v1/product. Also available as a
dashboard UI and, since 2026-10-14, as the MCP connector’s batch tool
(action: estimate, create, run, status, results, list, schedule, delete — the same handlers and
request fields as below). Since 2026-08-09 the same infrastructure also runs
search batches (kind: "search") — a list of search TERMS served through
the live /v1/serp path — and since 2026-10-07 seller, brand, category and
keyword batches (kind: "seller" | "brand" | "category" | "keywords", paid plans) — lists of seller
ids, brand names, category ids or seed terms served through /v1/seller,
/v1/brand, /v1/category and
/v1/keywords; see the sub-sections below. Since 2026-10-12 every other endpoint runs as a
batch too (shopping and warehouse search, Best Sellers, seller products, the brand and seller maps, keyword comparison, the
category tree and the ranked lists): see Every endpoint as a batch.
From the dashboard — no code needed 2026-09-16
Everything below is also a form. Sign in and open Batches:
| Step | What happens |
|---|---|
| New batch | pick what you are batching — a group (Products, Search, Sellers, Brands, Categories, Keywords, Ranked lists), then the endpoint inside it, with that endpoint's options every endpoint, 2026-10-12 — name it, pick the marketplace, then paste the list (one per line, or any CSV — for ids we take the first column that looks like one; headers, extra columns, BOM and duplicates are fine) or drop a CSV file. Bad lines are shown before anything is priced. Seller / brand / category / keyword batches are part of the paid plans, like the endpoints they run. |
| Submit | a free estimate: the warehouse / stale / not-tracked split of your list, the credit upper bound and its dollar value. Nothing runs or bills yet. |
| Mode & max age | cache / auto / live and the freshness slider re-price instantly from the age histogram. live scrapes every row on demand (1 credit per served row, ~28 s each, several in parallel; runs are serialized per marketplace, and the estimate shows the expected duration and how many rows would be scraped); auto scrapes only the rows older than your max age. On Walmart 2026-10-18 a live row is one walmart.com product page at 2 credits, 3 rows at a time, up to 5,000 rows a batch; Walmart live runs queue apart from Amazon runs, so neither holds the other back. |
| Attach history | products: tick Buy-box & per-seller price history and/or BSR rank history — included in the row price 2026-10-10. With the price history you can set how many sellers carry a series (default 10, max 50) and how many points each (default 500, max 20,000), also included. Or tick History only: just the stored series per row at 0.05 credit, whatever the age of the last observation, never a live scrape. Amazon marketplaces only; the blocks land in the JSONL rows, the CSV stays lean. |
| Create batch & run | the batch is saved and queued; the run page shows live progress (per-state counters, credits so far) and the Download CSV / JSONL buttons work mid-run with every row completed so far. You get an email when the run completes or pauses, with the download links. |
| Batch page | Run now re-runs the same list against a fresh estimate; the Schedule card sets daily / weekly / monthly firings with a per-firing credit ceiling (default 2× the estimate at save time) and an optional signed webhook; Delete cancels in-flight runs and keeps existing downloads until retention. Every run records the mode and max age it launched with. |
Same rules as the API: nothing bills until a row is actually served, failed / not-found / not-tracked rows are never billed, a run that reaches your credit floor pauses (rows stay pending, partials stay downloadable) and resumes after a top-up, and results are kept for 30 days. The form and the endpoints below share one pipeline, so a batch created in the dashboard can be listed, re-run, scheduled or downloaded through the API and vice versa.
Freshness — on every row, by default
Not opt-in: every result row (JSONL and default CSV columns) carries
| Field | Notes |
|---|---|
| observed_at | when the row's data was observed (UTC) |
| age_days | age of that observation in days — 0 on a live scrape |
| source | cache or live — where this row came from |
Row states
Every submitted line comes back as a result row — nothing is silently dropped from a billed batch.
| status | Meaning | Billed |
|---|---|---|
| ok | served, with product data | 0.5 (warehouse) / 1.0 (live; Walmart 2.0), history included · 0.05 with include: ["history_only"] |
| stale_skipped | tracked, but older than max_age_days in cache mode | 0 — never |
| not_tracked | not in the warehouse (coverage is best-seller-scoped, not the full catalog) | 0 — never |
| failed | invalid ID, or the live scrape did not return the product | 0 — never |
Search batches and the endpoint batches add empty (the call answered with no results, never billed). Duplicate lines are served in the output but billed once. Unknown request
fields are a loud 422 before anything bills. History blocks attached with include
(offer_history, bsr_history, wider series) are included in the row price 2026-10-10
— the estimate keeps history_credits_max and history_surcharge_ceiling_credits, now 0.
include: ["history_only"] returns only the stored series per row at 0.05: every tracked product
serves whatever the age of its last observation, the batch runs as cache (a live mode is a 422), and a
product with no stored series comes back not_tracked, unbilled. It cannot be combined with reviews or
used; the series are in the JSONL file, the CSV carries the row status.
Modes
| mode | Behaviour |
|---|---|
| cache | warehouse only — rows older than max_age_days come back stale_skipped, disclosed and unbilled |
| live | scrape every row — on Walmart 2026-10-18 one walmart.com product page per row at 2 credits (live Walmart), up to 5,000 rows a batch |
| auto | default — warehouse when fresher than max_age_days (default 30), scrape the rest |
Endpoints
| Endpoint | Notes |
|---|---|
| POST /v1/batch-estimate | price a list before running it — free, always; returns tracked / not-tracked / fresh / stale counts, an age histogram and the credit upper bound |
| POST /v1/batches | create a named, re-runnable batch — body: name, country, mode, max_age_days, asins[] or gtins[] 2026-10-12 (barcodes: each resolves like gtin= — our observations and the other marketplaces when the batch is created, Amazon’s own search row by row in mode auto / live; every row carries gtin and gtin_resolution, the CSV adds gtin, gtin_source, gtin_confidence after asin, and two barcodes of one product are served once and billed once) (or kind + terms[] / urls[] / seller_ids[] / brands[] / category_ids[] / seeds[], or pages for the ranked lists, with the endpoint's own options in params: see Every endpoint as a batch and the sub-sections below), optional include: "reviews" (the featured-review set on each JSONL row — free), "offer_history" and/or "bsr_history" 2026-09-16 (the same history blocks as /v1/product on each JSONL row — Amazon only, included in the row price 2026-10-10 — no extra credits); with offer_history also history_sellers (default 10, max 50) and history_points (default 500, max 20,000) — same meaning as on the product endpoint, wider series included; "history_only" returns the series alone at 0.05 a row |
| GET /v1/batches | list your batches, newest first, with each batch's last run |
| GET /v1/batches/{id} | batch detail: line stats + recent runs |
| PATCH /v1/batches/{id} | edit mode / max_age_days (product and seller batches; seller_products: mode cache or live only; kinds without a mode answer 422) — applies to future runs only: every run records the mode + max age it was launched with and reports them in run detail |
| DELETE /v1/batches/{id} | soft delete — in-flight runs are cancelled; existing results stay downloadable until retention collects them |
| POST /v1/batches/{id}/estimate | fresh estimate for a saved batch against the current warehouse state — free; the warehouse/live split moves as the nightly walk refreshes rows, so re-estimate before re-running |
| POST /v1/batches/{id}/schedule | recurring runs: daily / weekly / monthly / none, plus enabled, an optional per-firing credit_ceiling and an optional webhook_url — see below |
| POST /v1/batches/{id}/runs | queue a run — stores the estimate it launched under and refuses with 402 when your balance is below it; nothing bills until rows serve. Runs are serialized per marketplace, FIFO by creation — the response carries queue_position |
| GET /v1/batches/{id}/runs/{run_id} | progress: per-state counters, credits charged so far, the stored estimate; queued runs carry queue_position |
| POST /v1/batches/{id}/runs/{run_id}/resume | resume a run that paused at the credit floor — it re-queues on its marketplace and pending rows continue; nothing already served is re-billed |
| GET /v1/batches/{id}/runs/{run_id}/result.jsonl | streaming JSONL — downloadable mid-run with every row completed so far |
| GET /v1/batches/{id}/runs/{run_id}/result.csv | streaming CSV (product batches: the 33 summary columns below, incl. the freshness fields; every other kind: one row per key, or per item of its list, as its section says) — downloadable mid-run |
Result formats
CSV — 33 summary columns, in order:
line_no, asin, status, source, observed_at, age_days, credits, title, brand, price,
currency, in_stock, out_of_stock, bsr, rating, review_count, bought_past_month, buybox_seller,
seller_count, lowest_offer_price, current_sellers, buybox_fulfillment, amz_offers, fba_offers,
fbm_offers, buybox_delivery_days, buybox_delivery_days_max, dispatch_latency, parent_asin,
variation_count, description_source, image_url, description (the seven fulfilment columns
are flat reads of the fulfillment block). The CSV stays lean: array fields live in the
JSONL only.
JSONL — each row carries the complete /v1/product
payload: full per-seller offer list, 30-day price & stock change events, brand stats, and the
listing content blocks — image gallery (images), feature_bullets,
breadcrumbs and the variations matrix. Used / refurbished / open-box / collectible
offers ride along in current_sellers (and in the per-seller history when attached) when the batch was
created with include: ["used"] 2026-09-28
— same rows as /v1/product?include_used=true, free. Featured reviews are
included only when the batch was created with include: ["reviews"] (the one wide
array — up to 50 × ~500 B per row); review_count_scraped is always
present so you can see reviews exist without the payload. offer_history and
bsr_history ride the JSONL row too when the batch attached them — the same
blocks as the product endpoint, every seller listed, series up to the batch's
history_sellers × history_points; the CSV never carries them.
| Column | Notes |
|---|---|
| current_sellers | compact JSON of the full per-seller offer list, in the cell — parse it as JSON; per-seller price / fba / prime / feedback / buybox_days_30d / buybox_share_30d / buybox_observations_30d / buybox_observation_share_30d / condition / condition_class / seller_rating. New-condition list by default; a batch created with include: ["used"] 2026-09-28 carries the used / refurbished / open-box / collectible rows as well (conditions_included: "all"), and lowest_offer_price stays the lowest new offer |
| lowest_offer_price | minimum per-seller price; empty when the row has no priced offer list |
| bought_past_month | the Amazon “N+ bought in past month” badge as an integer; empty when the product shows no badge |
| description | last column — may be multi-line and quoted; empty when the source never showed one |
Caps: 20,000 rows per batch. Results are retained for 30 days
(410 after). A run that hits your credit floor pauses — rows stay
pending, partials stay downloadable, and it resumes after a top-up; it never bills into a negative
balance. A live row typically takes ~28 s (measured at the current operating point); rows run
concurrently, and the estimate returns estimated_live_duration_seconds for your list.
Seller, brand, category and keyword batches kind: "seller" | "brand" | "category" | "keywords" · 2026-10-07
One key per line — a seller id, a brand name, a
category id or a seed term — each served through the same service as the matching endpoint and billed exactly as that
endpoint bills; the same batches / runs / downloads / emails / webhooks / schedules as product batches. Paid plans:
a key without a subscription or purchased credits gets 403 paid_plan_required (never billed), like
/v1/seller, /v1/brand, /v1/category
and /v1/keywords themselves. Amazon marketplaces only.
| Field | Notes |
|---|---|
| kind | "seller", "brand", "category" or "keywords" on POST /v1/batches and POST /v1/batch-estimate |
| seller_ids | seller batches: Amazon seller ids (A + 8–24 letters/digits — the seller_id on any offer in /v1/product). Capped at 5,000 per batch. |
| brands | brand batches: names as Amazon prints them (case-insensitive, duplicates folded). Capped at 2,000 per batch. |
| category_ids | category batches: the warehouse’s category ids (list them with /v1/categories or /v1/categories/search, both free — not Amazon browse-node ids). Capped at 2,000 per batch. |
| seeds | keyword batches: seed terms or prefixes, 3–120 characters each (case-insensitive, duplicates folded), served like /v1/keywords. Capped at 2,000 per batch. |
| mode | seller batches only: cache (the stored profile; a seller we have never observed comes back not_tracked), live (fetch every seller page now) or auto (default — stored when younger than max_age_days, else live). Brand, category and keyword batches are always served from the warehouse — sending a mode there is a 422. |
| include | optional ["history"] attaches the endpoint’s history block to each JSONL row — the seller’s rating / storefront-size change points, the brand’s or category’s monthly series, the keyword lists’ observation record — at +0.5 per row when it comes back (non-empty; for keywords: at least one closed observation), the endpoint rule. |
| Kind | Row serves | Billed | Not billed |
|---|---|---|---|
| seller | the /v1/seller profile — rating, counts per period, histogram, recent feedback (no names), business block, tracking | 0.5 stored profile / 1.0 live fetch (auto bills what was served) +0.5 history | unknown or suppressed seller (not_tracked), a fetch Amazon blocked after retries (failed) |
| brand | the /v1/brand dossier — catalog, sellers and buy-box control, Amazon-retail share, FBA, concentration, churn, trend grades, benchmarks, top sellers | 1.0 per brand found +0.5 history | unknown brand (not_tracked) |
| category | the /v1/category landscape — size, pricing, competition, demand, churn, benchmarks, sub-categories, top brands | 1.0 per category found +0.5 history | unknown id (not_tracked) |
| keywords | the /v1/keywords answer — Amazon’s observed suggestion lists for the seed (positions within each list, first / last observed, marketplaces observed in) and related observed vocabulary | 1.0 per seed with observations +0.5 history | a seed with no observations on that marketplace (not_tracked) |
Daily cap. Brand, category and keyword rows bill under the endpoint they mirror, so they count
against the key’s daily derived-intelligence cap (2,000 calls per UTC day by default) together with
REST and MCP calls. The estimate reports derived_daily_cap {cap, used_today, remaining}; a run that reaches the
cap pauses (rows stay pending, partials stay downloadable, you get an email) and
POST .../runs/{run_id}/resume continues it after 00:00 UTC. Seller rows are not capped.
Estimate = upper bound. Seller batches price 0.5 per row in cache mode and 1.0
in auto / live (auto bills 0.5 wherever the stored profile is fresh enough); brand, category and keyword
batches price 1.0 per row; +0.5 per row with include: ["history"]. Not-found rows never bill. Seller runs fetch at the
marketplace’s live-search budget (us/uk 2 concurrent, others 1 — seller pages share it with /v1/serp);
the estimate returns estimated_live_duration_seconds for live / auto seller batches.
Row states: ok (served and billed as above) · not_tracked
(unknown key — never billed; reported as n_not_found on the run) · failed (invalid key, or the
live seller fetch did not return the page after retries — never billed). Duplicate lines are answered on their canonical line.
Result formats: the JSONL row carries the complete record under
"seller", "brand", "category" or "keywords" (plus line_no, term = the key,
status, source, credits, error) — everything the matching endpoint returns,
the history block included when requested. The CSV is a flat summary per line: seller —
line_no, seller_id, status, source, observed_at, credits, name, is_amazon, rating, ratings_total, ratings_total_12m,
positive_percent, positive_percent_period, storefront_url, business_name, observed_first_seen, error; brand —
line_no, brand, status, source, as_of, credits, asins_3m, unique_sellers_3m, buybox_days_3m, amazon_retail_share_pct,
fba_penetration_pct, control_score, seller_hhi_top3, seller_churn_30d_pct, trend_short, trend_long, avg_price, avg_rating,
bought_past_month_30d, revenue_30d, catalog_churn_30d_pct, category_root_id, category_name, velocity_tier, observed_first_seen,
months_observed, top_seller, error; category — line_no, category_id, status, source, as_of, credits, path,
root_id, root_name, is_root, depth, asins, asins_30d, brands, unique_sellers_30d, avg_price, avg_rating, amazon_retail_share_pct,
fba_penetration_pct, amazon_private_label_pct, seller_hhi_top5, avg_heat, velocity_tier, bought_past_month_30d, revenue_30d,
catalog_churn_30d_pct, subcategories, top_brand, error; keywords — line_no, seed, status, source, credits, list_count,
top_prefix, top_department, top_terms (the primary list’s terms in order, |-separated), related_count,
history_closed_points, error.
curl -X POST "https://api.logimu.com/v1/batches" \
-H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"name":"brand-sweep","kind":"brand","country":"us",
"brands":["Anker","Logitech","YETI"],"include":["history"]}'
curl -X POST "https://api.logimu.com/v1/batches" \
-H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"name":"operators","kind":"seller","country":"us","mode":"auto","max_age_days":14,
"seller_ids":["A2L77EE7U53NWQ","A3P5ROKL5A1OLE"]}'
curl -X POST "https://api.logimu.com/v1/batches" \
-H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"name":"category-map","kind":"category","country":"us",
"category_ids":[7926,37904]}'
curl -X POST "https://api.logimu.com/v1/batches" \
-H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"name":"seed-vocabulary","kind":"keywords","country":"de",
"seeds":["elektrische zahnbürste","yogamatte","luftfritteuse"],"include":["history"]}'
Every endpoint as a batch 17 more kinds · 2026-10-12
Every /v1 endpoint runs as a batch, with the same batches, estimates, runs,
downloads, emails, webhooks and schedules as product batches, and the same billing as the endpoint itself. The list goes in the field
below, one key per line; the endpoint's own query parameters go in params and apply to every row. They are validated
like the endpoint's, so an unknown name is a 422 before anything prices. The ranked lists take no list:
pages (1–40) is how many pages of 25 rows to take, one result row per page, which makes a scheduled batch a daily or
weekly snapshot. Kinds marked paid need a subscription or purchased credits, like their endpoints (403
paid_plan_required, never billed). Kinds marked cap count against the daily derived-intelligence
cap; a run that reaches it pauses and resumes after 00:00 UTC. In the dashboard: pick the group, then the
endpoint, and the form shows the same options.
| kind | List field | Each row runs | params | Billed per row |
|---|---|---|---|---|
| shopping | terms | /v1/shopping (11 Amazon marketplaces and Walmart; a barcode or a bare ASIN returns that product) | limit, sort, min_price, max_price, brand, category, in_stock, include_unavailable, accessories, group, per_group, intent, format, collapse, detail | 2 with results, 5 with detail; no results or no exact match: 0 |
| warehouse_search | terms | /v1/search with the line as q (and Walmart) | limit, sort, brand, seller, category, price_min, price_max, rating_min, rating_max, reviews_min, bsr_min, bsr_max, fba, fbm, fulfillment, seller_count_min, seller_count_max, max_per_category | 1 per 25 products returned; nothing matched, or matched only after dropping terms: 0 |
| bestsellers | urls | /v1/bestsellers, live (us/uk 2 at a time, other marketplaces 1) | pages (1 or 2, default 2) | 1 per page of 50 returned; a root list is free; not found, blocked or empty: 0 |
| offers | asins | /v1/offers, live (a few at a time per marketplace) | include_used | 0.5 per product with at least one offer; no offer right now, not found or blocked: 0 |
| deals | category_ids | /v1/deals for each deals department id (all = the whole deals page), live (us/uk 2 at a time, other marketplaces 1) | deal_types, collection, discount, min_discount, max_discount, min_price, max_price, prime_exclusive, minimum_rating, brand, page, page_size (30, 60, 90 or 120; default 60), pages (1–5) | 1 per page that returned deals (any page size); an empty list or a blocked fetch: 0 |
| seller_products | seller_ids | /v1/seller/products; mode cache (default) or live | page; live only: max_page, sort_by, refinements, q | 1 per page returned (paid) |
| seller_brands | seller_ids | /v1/seller/brands | page; include ["history"] | 1 per page of 25 brands, +0.5 with history (paid, cap) |
| seller_network | seller_ids | /v1/seller/network | limit | 1 (paid, cap) |
| brand_sellers | brands | /v1/brand/sellers | page | 1 per page of 25 sellers (paid, cap) |
| brand_network | brands | /v1/brand/network | limit | 1 (paid, cap) |
| keywords_compare | seeds | /v1/keywords/compare | countries (2–11, default us,uk,de) | 1 (paid, cap) |
| keyword_rankings | terms | /v1/keywords/rankings (Amazon US) | include ["history"] | 1, +0.5 history (paid, cap) |
| product_keywords | asins | /v1/product/keywords (Amazon US, one ASIN a row) | placement, limit; include ["history"] | 1 per 25 keywords returned (paid, cap) |
| categories | category_ids | /v1/categories: the children of each parent id (root = the top level) | none | free |
| category_search | terms | /v1/categories/search | limit | free (paid, cap) |
| brands_top | none (pages) | /v1/brands/top, one row per page | sort, category_id | 1 per page of 25 (paid, cap) |
| brands_movers | none (pages) | /v1/brands/movers | window (30 or 90), direction (up or down) | 1 per page of 25 (paid, cap) |
| sellers_top | none (pages) | /v1/sellers/top | sort | 1 per page of 25 (paid, cap) |
| sellers_movers | none (pages) | /v1/sellers/movers | window, direction | 1 per page of 25 (paid, cap) |
| categories_top | none (pages) | /v1/categories/top | sort, root_only, parent_id | 1 per page of 25 (paid, cap) |
curl -X POST https://api.logimu.com/v1/batches -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
"kind": "shopping", "name": "Supplier list", "country": "us",
"terms": ["wireless earbuds", "012345678905", "B07YYJRXQR"], "params": {"limit": 10}}'
curl -X POST https://api.logimu.com/v1/batches -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{
"kind": "brands_top", "name": "Top brands by revenue", "country": "uk", "pages": 4, "params": {"sort": "revenue"}}'Estimate = upper bound: rows × the endpoint's largest answer (for example 2 per shopping
query, 5 with detail), with estimated_live_rows and estimated_live_duration_seconds for the live
kinds. Row states: ok (served and billed as the endpoint bills) · empty (the call
answered with no results, never billed) · not_tracked (unknown key, never billed) · failed
(invalid line, or a live fetch that did not return after retries, never billed); empty and not_tracked are
reported together as n_not_found on the run. Result formats: the JSONL row carries the complete endpoint
answer under the kind's name ("shopping", "bestsellers" ...) next to line_no, term
(the key), status, source and credits; the CSV has one row per (key, item of the endpoint's
list), for example one row per (query, product) or (URL, ranked product), and a line with no items is a single status row, so every
submitted line is in the file. Caps per batch: shopping and warehouse_search 20,000 lines, bestsellers and deals 500, offers 10,000,
the seller kinds 5,000, the others 2,000.
Search batches kind: "search"
A batch of search terms, one live SERP
fetch per term per page — same batches/runs/downloads/emails/webhooks/schedules as product batches.
Because every row is a live fetch (there is no warehouse copy of a SERP), search batches are
always live: there is no mode, and sending one is a 422.
All 11 Amazon marketplaces and, since 2026-10-18, Walmart (country: "walmart":
walmart.com search, 2 credits per page returned, 3 terms at a time;
include: ["blocks"] is Amazon-only).
| Field | Notes |
|---|---|
| kind | "search" on POST /v1/batches and POST /v1/batch-estimate |
| terms | the search queries (replaces asins). Capped at 500 terms per batch. Duplicate terms are answered on their canonical line rather than fetched twice. |
| pages | pages fetched per term, 1–3 (default 1). Positions stay continuous across pages. |
| include | optional ["blocks"] attaches ad_blocks / video_blocks / brand_stores to each JSONL row. These live at the top of page 1 only — that is where Amazon renders them, so a multi-page term still carries at most one set. No extra charge. |
Estimate = upper bound. The estimate prices
terms × pages, but you are billed per page actually fetched —
Amazon can run out of results before the requested page count, and blocked fetches, zero-result
terms and duplicate lines are never billed.
Row states: ok (results returned; billed per page
fetched) · empty (the fetch succeeded but Amazon returned no results — never billed) ·
failed (invalid term, or Amazon blocked the fetch after retries — never billed). Every
submitted term comes back as a result row; nothing is silently dropped from a billed batch.
Result formats: the CSV is one row per
(term, result position): term, page, position, asin, title, price, currency, list_price,
rating, ratings_total, recent_sales, sponsored, is_prime, link, image, status, error — terms
with no result rows appear as single status rows. The JSONL carries the complete
per-term /v1/serp payload: search_information,
pagination, related_searches, round-trip-ready refinements, and
(with include: ["blocks"]) the paid-placement blocks — none of which fit the CSV.
Capacity: search runs are serialized per marketplace like
product runs, and each run fetches at the marketplace’s live-search budget (us/uk: 2 concurrent,
others: 1) — deliberately small, because each fetch holds a real browser context for ~8–13 s.
A 500-term us batch at 1 page/term is therefore roughly an hour of wall time; the estimate returns
estimated_live_duration_seconds for your list. Walmart search runs fetch 3 terms at a time
on the live Walmart lane, which queues apart from the Amazon runs.
curl -X POST "https://api.logimu.com/v1/batches" \
-H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"name":"category-sweep","kind":"search","country":"us","pages":1,
"terms":["wireless earbuds","yoga mat","usb c hub"],"include":["blocks"]}'
Schedules & webhooks
A schedule fires at most once per period (server date:
daily after midnight, weekly on Monday, monthly on the 1st). Each firing computes a
fresh estimate and refuses to run — recording a cancelled run and emailing
you — when that estimate exceeds the credit_ceiling (default: 2× the
estimate at schedule-set time) or your balance. A schedule never surprises you with a bill.
Setting webhook_url returns the signing secret
once — store it. We POST the run summary to your URL on completion and on
pause, signed X-Logimu-Signature: sha256=<hex HMAC-SHA256(secret, raw body)>,
with 3 retries on failure.
curl -X POST "https://api.logimu.com/v1/batch-estimate" \
-H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"asins":["B0BDHQSZCV","B072YVWBXH"],"country":"us","mode":"auto"}'
{
"country": "us", "mode": "auto", "max_age_days": 30,
"rows_submitted": 2, "rows_valid": 2, "rows_invalid": 0, "rows_duplicate": 0,
"tracked": 2, "not_tracked": 0, "fresh_within_max_age": 2, "stale": 0,
"estimated_credits_max": 1.0, "estimated_usd_max": 0.0,
"history_blocks": [], "history_credits_max": 0.0, "history_surcharge_ceiling_credits": 0.0,
"billing_note": "Upper bound: failed, not-found and not-tracked rows are never billed. Warehouse rows 0.5 credits, live rows 1.0.",
"age_histogram_days": { "3": 1, "11": 1 }, "estimate_valid_minutes": 60
}
# create the batch, then run it
curl -X POST "https://api.logimu.com/v1/batches" \
-H "X-API-KEY: sk_live_..." -H "Content-Type: application/json" \
-d '{"name":"my-skus","country":"us","mode":"auto","max_age_days":30,
"asins":["B0BDHQSZCV","B072YVWBXH"]}'
# => {"id": 12, ...}
curl -X POST "https://api.logimu.com/v1/batches/12/runs" -H "X-API-KEY: sk_live_..."
# => {"id": 34, "status": "queued", "estimate": { ... }}
curl "https://api.logimu.com/v1/batches/12/runs/34" -H "X-API-KEY: sk_live_..."
curl -o out.csv "https://api.logimu.com/v1/batches/12/runs/34/result.csv" -H "X-API-KEY: sk_live_..."
Rate limits, errors & honesty
- Per-key rate limit ~10 req/s (burst 20) →
429withRetry-After. Credits are the volume limit. 401missing/invalid key ·402out of credits ·403paid_plan_required(seller + derived endpoints on a key without a paid plan; unbilled) ·404not found (unbilled; the body may carryfound_on+ ahint— e.g. the ASIN is tracked on another marketplace, or a US live scrape can be requested withmode=live) ·422bad params.- Every record carries an
as_oftimestamp — data is observed, not real-time. Sales figures are estimates.