{"openapi":"3.1.0","info":{"title":"Logimu API","version":"0.1.0"},"paths":{"/v1/search":{"get":{"summary":"Search","description":"Filter our tracked-product warehouse - 11 Amazon marketplaces (US, UK, DE, CA, AU, FR, IT, ES, JP, MX, BR) plus Walmart US.\n\nProvide **one anchor** — any of `q` (keyword), `brand`, or `category` (2026-08-10) is\nenough on its own. `category` browses a whole department or sub-category with no keyword\n(`?category=Home & Kitchen`); its name is matched in full and case-insensitively against\nthe product's category chain, a name we don't carry returns 422 with the nearest matches,\nand a category-only browse returns the category's top products by in-category best-seller\nrank before applying your filters and `sort`. `seller` only refines and cannot start a\nsearch. Every filter (price/rating/reviews/bsr/fba/seller_count) narrows the anchored set;\n`total_matched` is the recall pool so you can see how much your filters and `limit` cut.","operationId":"search_v1_search_get","parameters":[{"name":"marketplace","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Marketplace","default":"amazon-us"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Q"}},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"}},{"name":"seller","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seller"}},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}},{"name":"price_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Min"}},{"name":"price_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price Max"}},{"name":"rating_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating Min"}},{"name":"rating_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating Max"}},{"name":"reviews_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews Min"}},{"name":"bsr_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bsr Min"}},{"name":"bsr_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bsr Max"}},{"name":"fba","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Fba"}},{"name":"fbm","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Fbm"}},{"name":"fulfillment","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fulfillment"}},{"name":"seller_count_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seller Count Min"}},{"name":"seller_count_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seller Count Max"}},{"name":"sort","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SortField","default":"bsr"}},{"name":"max_per_category","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":500,"minimum":1},{"type":"null"}],"title":"Max Per Category"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/shopping":{"get":{"summary":"Shopping","description":"Curated product search across Amazon US, UK, Germany, Canada, Australia and\nWalmart US: keyword -> ranked, grouped product recommendations in under 100ms, in the\nmarketplace's local currency. A bare ASIN (or numeric Walmart item ID) returns exactly\nthat product (mode: \"asin\"). Metered against the caller's credits (2 credits\nper successful query, or 5 with `detail=true`; empty results are never billed).\nWalmart opened 2026-07-29 (Nick) — the engine always supported it and the free demo +\nMCP already served it; the REST guard was the only blocker (demo-to-paid hole).","operationId":"shopping_v1_shopping_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","title":"Q"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart.","default":"us","title":"Country"},"description":"Marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart."},{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Optional keyword filter on the product-category PATH (matched against the full path including all parent categories, singular/plural folded). E.g. q=coffee maker & category=machine keeps only categories whose path mentions Machine(s).","title":"Category"},"description":"Optional keyword filter on the product-category PATH (matched against the full path including all parent categories, singular/plural folded). E.g. q=coffee maker & category=machine keeps only categories whose path mentions Machine(s)."},{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Force grouping: category | price | none (default auto).","title":"Group"},"description":"Force grouping: category | price | none (default auto)."},{"name":"min_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1000000.0,"minimum":0.0},{"type":"null"}],"description":"Minimum price filter (alias: price_min).","title":"Min Price"},"description":"Minimum price filter (alias: price_min)."},{"name":"max_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1000000.0,"minimum":0.0},{"type":"null"}],"description":"Maximum price filter (alias: price_max).","title":"Max Price"},"description":"Maximum price filter (alias: price_max)."},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"description":"Restrict to an exact brand.","title":"Brand"},"description":"Restrict to an exact brand."},{"name":"in_stock","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Only in-stock products when true.","title":"In Stock"},"description":"Only in-stock products when true."},{"name":"include_unavailable","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"false (default): only products with a current offer (a price observed in the activity window). true: also return listings that currently have no offer on the marketplace (Amazon 'Currently unavailable' items: no price, in_stock false). A bare ASIN lookup always returns the product regardless of this flag. Added 2026-09-26.","title":"Include Unavailable"},"description":"false (default): only products with a current offer (a price observed in the activity window). true: also return listings that currently have no offer on the marketplace (Amazon 'Currently unavailable' items: no price, in_stock false). A bare ASIN lookup always returns the product regardless of this flag. Added 2026-09-26."},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(relevance|price|rating)$"},{"type":"null"}],"description":"relevance (default) | price | rating.","title":"Sort"},"description":"relevance (default) | price | rating."},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":50,"minimum":1},{"type":"null"}],"description":"Max products (default 20).","title":"Limit"},"description":"Max products (default 20)."},{"name":"per_group","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10,"minimum":1},{"type":"null"}],"description":"Products per category/tier group.","title":"Per Group"},"description":"Products per category/tier group."},{"name":"accessories","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Include accessory products (default false).","title":"Accessories"},"description":"Include accessory products (default false)."},{"name":"intent","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(on|off)$"},{"type":"null"}],"description":"Category-intent inference on (default) | off.","title":"Intent"},"description":"Category-intent inference on (default) | off."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(kindle|paperback|hardcover|mass_market|audiobook|audio_cd|board_book|spiral|library_binding|other)(,(kindle|paperback|hardcover|mass_market|audiobook|audio_cd|board_book|spiral|library_binding|other))*$"},{"type":"null"}],"description":"Books/media: only this format - kindle, paperback, hardcover, mass_market, audiobook, audio_cd, board_book, spiral, library_binding, other; comma-separate several (format=paperback,hardcover). Added 2026-09-30.","title":"Format"},"description":"Books/media: only this format - kindle, paperback, hardcover, mass_market, audiobook, audio_cd, board_book, spiral, library_binding, other; comma-separate several (format=paperback,hardcover). Added 2026-09-30."},{"name":"collapse","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true (default): one row per book - its other formats (each its own ASIN, with price) are listed in the row's `formats`. false: every format as its own row. Added 2026-09-30.","title":"Collapse"},"description":"true (default): one row per book - its other formats (each its own ASIN, with price) are listed in the row's `formats`. false: every format as its own row. Added 2026-09-30."},{"name":"detail","in":"query","required":false,"schema":{"type":"boolean","description":"Attach to EVERY product everything the basic /v1/product answer carries (2026-09-28): current sellers with fulfillment and delivery, 30-day price/stock change events, stock history and state, brand_stats, dimensions, list-price/coupon/badge/rating history, variation coverage, page content (images, bullets, breadcrumbs, variations) and up to 50 featured reviews, plus a response-wide seller_ratings array. Only bsr_history and offer_history stay product-only. 5 credits per query instead of 2. Note: bought_past_month (Amazon's 'N+ bought in past month' badge) is included on every product in EVERY response — no detail flag needed.","default":false,"title":"Detail"},"description":"Attach to EVERY product everything the basic /v1/product answer carries (2026-09-28): current sellers with fulfillment and delivery, 30-day price/stock change events, stock history and state, brand_stats, dimensions, list-price/coupon/badge/rating history, variation coverage, page content (images, bullets, breadcrumbs, variations) and up to 50 featured reviews, plus a response-wide seller_ratings array. Only bsr_history and offer_history stay product-only. 5 credits per query instead of 2. Note: bought_past_month (Amazon's 'N+ bought in past month' badge) is included on every product in EVERY response — no detail flag needed."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/product":{"get":{"summary":"Product","description":"THE product endpoint (unified 2026-07-23). One call: current snapshot (price, BSR, rating,\nbuy-box — cache-or-live via `mode` + `max_age_days`) plus observed_at, the FULL price-change\ntimeline (price_history, seller-stamped, back to first observation) with a 30-day convenience\nview, the full in/out-of-stock timeline (stock_history, with stock_state +\nstock_observed_since), the Amazon-reported bought-past-month\nbadge (bought_past_month int + raw text — measured, not modeled; Amazon marketplaces only),\nthe current all-seller snapshot, and brand stats. `country=walmart` returns\nthe intelligence blocks (numeric item ID). Partial live scrapes are never billed.\nWalmart products also carry (2026-09-20, additive) image_url / images[], description,\ncategory_path + breadcrumbs[], highlights[] (name/value spec pairs as shown on the PDP),\nwarnings[] (compliance text, e.g. Prop 65), upc, model_number, color, rating / review_count /\nrating_observed_at (null when the page showed none), was_price / discount_pct, additional_offer_count,\nper-seller shipping_cost (a cost, 0 = free; never a landed price), and in_stock / as_of beside the\nunchanged stock_state / observed_at. gtin= resolves Walmart barcodes to item IDs.\nLIVE Walmart (2026-10-18): country=walmart&mode=live reads the walmart.com product page right now (typically\n8-15 s) - price, stock, rating, the featured seller and the sellers the page lists, plus the PDP content above -\nlaid over our stored history for the item (history_available says whether we held any). 2 credits; a partial\npage (title, no price, in stock), an item walmart.com does not have (404) and a failed or busy fetch (503) are\nnever billed. mode=auto on Walmart works like Amazon: the stored record when observed within max_age_days\n(0.5), else a live read (2); mode=cache never fetches. A failed live read on an item we hold answers the stored\nrecord as source=cache_after_live_fail (0.5) with a note. One product page per call: the cheapest other seller\nWalmart shows only on a second page is not fetched (additional_offer_count says how many there are). location\nnames the store walmart.com priced the page for (postal_code, city, state, store_id): each read can land on\nanother store, and fresh grocery is priced per store.\nbuybox_price_points_hot (2026-10-14): every all-offers-page observation of the last 30 days\n{ts, price, seller, seller_id, fulfillment, offer_count}, newest last — sub-daily for hot-lane ASINs\n(observed every few hours), the walk's and on-demand observations for the rest; null when none. tracking:\nthe hot lane's state for the ASIN {hot, interval_min, rate, source, last_fetched_at, next_due_at}, null when\nthe ASIN is not in the lane. Both on every Amazon answer, included in the record; history_only carries\nbuybox_price_points_hot. The cache snapshot's as_of and the fresh flag behind mode=auto follow the latest\nobservation we hold (not only the nightly summary), so a hot-lane fetch makes the record fresh.\nbuybox_state (2026-10-14, §86): what the lane's newest all-offers read saw — in_stock | no_buybox (offers, but no\nfeatured offer) | out_of_stock (no offers) — with buybox_state_observed_at; when that read is newer than the daily\nhistory's last point it decides stock_state / in_stock and stock_state_source names it. stock_state, in_stock and the\ntri-state out_of_stock always agree (2026-10-15). buybox_condition (2026-10-15): new | used | null (no featured offer)\nwith buybox_condition_source (product_page | offers_page) and buybox_condition_detail (the pinned offer's condition\ntext, used_only_buybox, or the used storefront's name — Amazon Resale / Warehouse / Retourenkauf …, which win the buy\nbox like any seller and read as Amazon retail before): live = measured on the fetch; cache = the pinned offer's stored\ncondition at the row's observation, else the storefront name. On LIVE answers variation_status (page_is_sibling |\npage_is_other | null) + page_asin say when Amazon served another ASIN's page for the one asked (cache answers carry\nboth as null); the stock keys describe the ASIN asked for, the content fields the page served.\n\nPDP content (2026-08-09, Amazon marketplaces): description + description_source\n(product_description = prose, feature_bullets = \"About this item\", aplus = brand\nmarketing — bullets read very differently from prose), the full image gallery\n(images[], ≤20 originals), feature_bullets[], breadcrumbs[] (full category path),\nthe variations matrix (variations[] with child_asin + dimension_values +\navailability, variation_count, parent_asin — an EMPTY variations is normal, most\nASINs have no variants; per-variant PRICE is NOT included, Amazon only sends it on\nselection), featured reviews (reviews[], ≤50 — the accumulated set Amazon shows a logged-out\nvisitor, NOT the full review history; the count varies per fetch because Amazon\ndoes not always render the section; date_raw is verbatim and carries the review\ncountry + a localised month name — parse downstream, keep the country), and a\ntri-state out_of_stock (true = out of stock: Amazon's dedicated out-of-stock buybox on\nthe page, or the newest offers read found no offer - it always agrees with stock_state;\nfalse = in stock, null = unknown). bought_past_month null means NO BADGE — Amazon\nonly badges higher-velocity listings — never \"we missed it\". content_observed_at\nnull with empty arrays means content has not been captured for this ASIN yet.\nThe \"Customers say\" AI summary/aspect chips are NOT available (lazy-loaded after\nour snapshot). No extra charge for any content field.\n\n2026-09-27 (additive, Amazon marketplaces, no extra charge): `dimensions` (item weight + package\ndimensions as printed plus parsed value/unit and metric weight_g / *_cm), `deal_history` (list price,\nsavings and coupon/promotion text as segments of consecutive observations, with parsed\ncoupon_amount / coupon_percent and a `current` view), `bought_past_month_history` (the badge as\nsegments; null = page observed without a badge), `rating_history` (one point per observed day:\nrating_count + rating, with ratings_gained_30d / 90d), and `variation_coverage` (the variation\nmatrix as last observed with, per child, whether we track it and its latest 30-day price — current\nstate, not history). With offer_history=true every point also carries the offer's `shipping`\n(cost), `fba` and `prime` for that day, and each series row `fba_days` / `fba_last` /\n`shipping_last` (null on legacy-era days before 2026-04-17). Explicit null on Walmart.\nAlso since 2026-09-27: `sales_estimate` is null whenever the bought-past-month badge is present (the\nbadge is the measured figure; the estimate is served only for unbadged listings), and `reviews[]` lists\nthe marketplace's own reviews (is_local true) before the other-countries set.","operationId":"product_v1_product_get","parameters":[{"name":"asin","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Amazon ASIN (or numeric item ID for country=walmart). Provide either asin or gtin.","title":"Asin"},"description":"Amazon ASIN (or numeric item ID for country=walmart). Provide either asin or gtin."},{"name":"gtin","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"GTIN / UPC / EAN / ISBN-13 barcode (8, 12, 13 or 14 digits; punctuation and leading zeros are tolerated). Resolved to an ASIN in the requested marketplace, cheapest evidence first: the barcode on a listing we observe there, a print book's ISBN-10, the same product's barcode on another Amazon marketplace, and - with mode=auto (the default) or mode=live - Amazon's own search for the barcode (organic results only, never sponsored; the one whose listing carries the barcode wins; adds ~10-20 s the first time, then cached 60 days). gtin_resolution says which step answered, how confident it is, and whether the barcode is printed on that listing (barcode_verified true / false / null). A barcode can legitimately map to several ASINs - the best match is returned and every match is listed in gtin_matches. The lookup is included in the product's price; a barcode nothing resolves is a 404 and never billed. country=walmart resolves against the UPC of observed walmart.com listings and returns numeric item IDs.","title":"Gtin"},"description":"GTIN / UPC / EAN / ISBN-13 barcode (8, 12, 13 or 14 digits; punctuation and leading zeros are tolerated). Resolved to an ASIN in the requested marketplace, cheapest evidence first: the barcode on a listing we observe there, a print book's ISBN-10, the same product's barcode on another Amazon marketplace, and - with mode=auto (the default) or mode=live - Amazon's own search for the barcode (organic results only, never sponsored; the one whose listing carries the barcode wins; adds ~10-20 s the first time, then cached 60 days). gtin_resolution says which step answered, how confident it is, and whether the barcode is printed on that listing (barcode_verified true / false / null). A barcode can legitimately map to several ASINs - the best match is returned and every match is listed in gtin_matches. The lookup is included in the product's price; a barcode nothing resolves is a 404 and never billed. country=walmart resolves against the UPC of observed walmart.com listings and returns numeric item IDs."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart.","default":"us","title":"Country"},"description":"Marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","default":"auto","title":"Mode"}},{"name":"max_age_days","in":"query","required":false,"schema":{"type":"integer","default":30,"title":"Max Age Days"}},{"name":"bsr_history","in":"query","required":false,"schema":{"type":"boolean","description":"Attach the full per-category BSR rank history (both eras, era-tagged daily points, legacy top-100 segments flagged censored). Included in the record - no extra credits. Amazon marketplaces only.","default":false,"title":"Bsr History"},"description":"Attach the full per-category BSR rank history (both eras, era-tagged daily points, legacy top-100 segments flagged censored). Included in the record - no extra credits. Amazon marketplaces only."},{"name":"offer_history","in":"query","required":false,"schema":{"type":"boolean","description":"Attach the buy-box owner timeline + per-seller price series (daily points from our multi-seller offer stream; US buy-box depth to Dec 2024). Every observed seller is listed; point series for the 10 most-observed sellers, 500 points each, by default - widen with history_sellers / history_points. Also attaches buybox_price_history: the lowest buy-box price of every observed day, Amazon US from Nov 2023 (the legacy daily snapshot), every point labelled with its source. Included in the record - no extra credits. Amazon marketplaces only.","default":false,"title":"Offer History"},"description":"Attach the buy-box owner timeline + per-seller price series (daily points from our multi-seller offer stream; US buy-box depth to Dec 2024). Every observed seller is listed; point series for the 10 most-observed sellers, 500 points each, by default - widen with history_sellers / history_points. Also attaches buybox_price_history: the lowest buy-box price of every observed day, Amazon US from Nov 2023 (the legacy daily snapshot), every point labelled with its source. Included in the record - no extra credits. Amazon marketplaces only."},{"name":"history_only","in":"query","required":false,"schema":{"type":"boolean","description":"Return ONLY the stored history series - bsr_history, offer_history and buybox_price_history - with no snapshot, content, current_sellers or brand stats, for 0.05 credit (Amazon marketplaces, served from stored observations: mode=live is refused). The cheap lane for price / rank tracking at volume; history_sellers / history_points still shape the offer series. Not billed when nothing is stored for the ASIN.","default":false,"title":"History Only"},"description":"Return ONLY the stored history series - bsr_history, offer_history and buybox_price_history - with no snapshot, content, current_sellers or brand stats, for 0.05 credit (Amazon marketplaces, served from stored observations: mode=live is refused). The cheap lane for price / rank tracking at volume; history_sellers / history_points still shape the offer series. Not billed when nothing is stored for the ASIN."},{"name":"full_offers","in":"query","required":false,"schema":{"type":"boolean","description":"Return the COMPLETE seller list instead of the buy box + first page (~10 offers). Only affects a live scrape (mode=live, or mode=auto when the cache is stale). Adds roughly 15-20s. NOT billed extra - still one call. Use it for unauthorized-seller, MAP and hijacker work, where sellers deeper than the top 10 are the whole point; leave it off for repricing and sourcing, where the buy box plus top offers is enough.","default":false,"title":"Full Offers"},"description":"Return the COMPLETE seller list instead of the buy box + first page (~10 offers). Only affects a live scrape (mode=live, or mode=auto when the cache is stale). Adds roughly 15-20s. NOT billed extra - still one call. Use it for unauthorized-seller, MAP and hijacker work, where sellers deeper than the top 10 are the whole point; leave it off for repricing and sourcing, where the buy box plus top offers is enough."},{"name":"history_sellers","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"With offer_history: how many of the most-observed sellers carry a point series (default 10, max 50). Every observed seller is always listed as a summary row (name, seller_id, first/last seen, days_observed, buybox_days, points_total).","default":10,"title":"History Sellers"},"description":"With offer_history: how many of the most-observed sellers carry a point series (default 10, max 50). Every observed seller is always listed as a summary row (name, seller_id, first/last seen, days_observed, buybox_days, points_total)."},{"name":"history_points","in":"query","required":false,"schema":{"type":"integer","maximum":20000,"minimum":1,"description":"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). Wider series are included too - no extra credits (the points beyond the default 10 sellers x 500 are still disclosed as offer_history.points_extra, with extra_credits 0).","default":500,"title":"History Points"},"description":"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). Wider series are included too - no extra credits (the points beyond the default 10 sellers x 500 are still disclosed as offer_history.points_extra, with extra_credits 0)."},{"name":"marketplace","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for country, accepting /v1/search-style values (amazon-de, amazon-us, … or bare de/us/walmart).","title":"Marketplace"},"description":"Alias for country, accepting /v1/search-style values (amazon-de, amazon-us, … or bare de/us/walmart)."},{"name":"include_used","in":"query","required":false,"schema":{"type":"boolean","description":"Include used, refurbished, open-box and collectible offers in current_sellers (and, with offer_history, one series per seller+condition_class). Default false keeps the new-condition list unchanged. Every seller row always carries `condition` (the marketplace's own label) and `condition_class` (new, used_like_new, used_very_good, used_good, used_acceptable, used, refurbished, open_box, collectible, unknown); current_sellers always carries used_offer_count, lowest_new (the cheapest new offer - the list is buy-box first, not price-sorted) and lowest_used (the cheapest second-hand offer of the snapshot) whether or not you opt in. Applies to cached, live and historical data alike. Not billed extra.","default":false,"title":"Include Used"},"description":"Include used, refurbished, open-box and collectible offers in current_sellers (and, with offer_history, one series per seller+condition_class). Default false keeps the new-condition list unchanged. Every seller row always carries `condition` (the marketplace's own label) and `condition_class` (new, used_like_new, used_very_good, used_good, used_acceptable, used, refurbished, open_box, collectible, unknown); current_sellers always carries used_offer_count, lowest_new (the cheapest new offer - the list is buy-box first, not price-sorted) and lowest_used (the cheapest second-hand offer of the snapshot) whether or not you opt in. Applies to cached, live and historical data alike. Not billed extra."},{"name":"track","in":"query","required":false,"schema":{"type":"boolean","description":"Answer AND track (2026-10-14): after this answer the ASIN is pinned into our hot lane, which re-reads its all-offers page every `interval` for 30 days and adds every read to buybox_price_points_hot - the same as POST /v1/track. 0 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.","default":false,"title":"Track"},"description":"Answer AND track (2026-10-14): after this answer the ASIN is pinned into our hot lane, which re-reads its all-offers page every `interval` for 30 days and adds every read to buybox_price_points_hot - the same as POST /v1/track. 0 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."},{"name":"interval","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"With track=true: 1h, 2h, 4h (default), 12h or 24h.","title":"Interval"},"description":"With track=true: 1h, 2h, 4h (default), 12h or 24h."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/track":{"post":{"summary":"Track Create","description":"TRACK a product (2026-10-14): pin an ASIN into our hot lane so its all-offers page is re-read every 2 / 4 /\n12 / 24 hours (hourly too) for as long as the plan is active - or ttl_days if you set one. Every read becomes a point in the product's buybox_price_points_hot (price,\nbuy-box seller, fulfillment, offer count), so GET /v1/product - and its 0.05-credit history_only lane, or a\nproduct batch with source: \"tracked\" - carries sub-daily buy box, price and offer-count history for it.\n\n0 credits. What a plan sells is a daily ALLOWANCE of tracked snapshots: Solo 2,500 (e.g. 416 products every\n4 hours), Starter 6,000, Growth 18,000, Standard 40,000, Scale 170,000, Volume 710,000. When the allowance is\nspent the call answers 402 tracking_allowance_full with the upgrade link; when only a longer interval fits, that\ninterval is granted and the answer says so (granted_interval). Posting the same ASIN again renews it and sets\nthe new interval (same id). A lapsed subscription keeps its trackings 7 days, then they pause and resume by\nthemselves when the subscription returns. Alerts: webhook_url + notify_if (signed POSTs) and / or alert_email\n(one e-mail per event, 50 a day per tracking). The lane picks a new tracking up within ~10 minutes (pending: true\nuntil then); one fetch serves every account tracking the same ASIN.","operationId":"track_create_v1_track_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"Track List","description":"The key's trackings (2026-10-14), newest first, each with the lane's own state for the ASIN - in_lane,\nlast_snapshot_at, next_due_at, lane_snapshots (from the hot lane's table, mirrored every 10 minutes) - and the\nplan's allowance (snapshots a day: total, used, remaining). 0 credits, never billed.","operationId":"track_list_v1_track_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this marketplace's trackings (us, uk, de, ...); default all.","title":"Country"},"description":"Only this marketplace's trackings (us, uk, de, ...); default all."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this state: active, paused, expired or stopped (default all; stopped trackings stay listed 30 days).","title":"Status"},"description":"Only this state: active, paused, expired or stopped (default all; stopped trackings stay listed 30 days)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Track Stop By Asin","description":"Stop a tracking by ASIN instead of id (P87, 2026-10-14): DELETE /v1/track?country=us&asin=B0... 404 when this\nkey does not track it. 0 credits.","operationId":"track_stop_by_asin_v1_track_delete","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"asin","in":"query","required":true,"schema":{"type":"string","minLength":10,"maxLength":10,"title":"Asin"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/track/{tracking_id}/events":{"get":{"summary":"Track Events","description":"The webhook events of one tracking (2026-10-14, §84), newest first: which notify_if threshold fired on which\nobservation, the payload that was (or will be) POSTed, and the delivery state (pending / delivered / failed with\nattempts and the last error). Events are kept with the tracking. 0 credits.","operationId":"track_events_v1_track__tracking_id__events_get","parameters":[{"name":"tracking_id","in":"path","required":true,"schema":{"type":"integer","title":"Tracking Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/track/{tracking_id}":{"delete":{"summary":"Track Stop","description":"Stop a tracking at once (2026-10-14): its allowance is released immediately; the row stays in GET /v1/track\nas stopped for 30 days. 404 when the id is not this key's. 0 credits.","operationId":"track_stop_v1_track__tracking_id__delete","parameters":[{"name":"tracking_id","in":"path","required":true,"schema":{"type":"integer","title":"Tracking Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/track/stop":{"post":{"summary":"Track Stop Bulk","description":"Stop trackings in bulk (P87, 2026-10-14): by ids, or by country + asins (up to 1,000). Per-item results in\ninput order - stopped / already_stopped / not_found (an id that is not this key's, an ASIN it does not track) -\nthe allowance released at once; HTTP 200 whenever the body parsed. 0 credits.","operationId":"track_stop_bulk_v1_track_stop_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackStopRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/track/sync":{"post":{"summary":"Track Sync","description":"Make the key's active trackings on one marketplace EQUAL to the list (P87, 2026-10-14): creates what is\nmissing (at interval and with the alert fields given), stops active trackings not listed, leaves the rest\nuntouched. Returns created, stopped, unchanged, refused (allowance or capacity), invalid, with the lists; dry_run\nreturns the same without writing. An empty list is a 422 (use /v1/track/stop to stop everything). 0 credits.","operationId":"track_sync_v1_track_sync_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackSyncRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/serp":{"get":{"summary":"Serp","description":"LIVE Amazon search-results (SERP) fetch — a real browser navigates Amazon's search page\nright now and returns the parsed result grid plus everything around it: search_information\n(Amazon's own result-count estimate), pagination, related_searches, refinements (round-trip\nready), and the paid-placement blocks (ad_blocks, video_blocks, brand_stores).\n\nNOT the same thing as /v1/shopping (curated warehouse search, <100ms) or /v1/search\n(warehouse filter, <100ms): this is a live fetch, straight from Amazon — expect SECONDS\n(typically ~8-13s, occasionally up to ~90s when the retry ladder runs; set client timeouts\nto 180s+). There is no cached copy of a SERP, so there is no `mode` parameter: every call\nis live.\n\nBilling: 1 credit per page actually fetched (request_metadata.pages_fetched), never per\npage requested. A blocked fetch (502) or an empty result set is never billed.\n\nHonest limits (measured): result count per page is Amazon's choice and varies (16-48);\ntotal_results is Amazon's estimate; total_pages is the pagination window Amazon offers,\nnot the true last page; `sponsored` is usually false (paid placements sit in separate\nblocks); `is_prime` means \"prime icon rendered\", not \"not Prime\" when false;\n`recent_sales` is Amazon's verbatim badge string in the page's own language;\nspelling_correction reports Amazon's autocorrect, it cannot disable it; ad/video block\nlinks are Amazon ad-redirectors, not clean catalogue URLs; brand_stores lists organic\nstore headers only and can be legitimately empty.\n\nWalmart (2026-10-18): country=walmart searches walmart.com right now (typically 4-12 s a page). Same parameter\nnames and the same result keys where they mean the same thing (position, asin = the Walmart item id, title,\nlink, image, rating, ratings_total, price, list_price, badges, recent_sales, sponsored, organic_rank), plus\nitem_id, unit_price, seller {name, id}, additional_offer_count, availability, delivery, flags and category_path;\nsearch_information carries Walmart's total_results and any corrected_query. Only the results grid is returned\n(Walmart's recommendation carousels are skipped); sponsored products sit inline and are flagged. Billing: 2\ncredits per results page actually returned (max_page - page + 1 <= 3); an empty result set, a failed fetch\n(502) and a busy refusal (503) are never billed. Prices and delivery promises are those walmart.com shows for\nthe store named in location (postal_code, city, state, store_id); a store or ZIP cannot be chosen.","operationId":"serp_v1_serp_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"The search query, e.g. 'wireless earbuds'. Alias: search_term (Rainforest-compatible).","title":"Q"},"description":"The search query, e.g. 'wireless earbuds'. Alias: search_term (Rainforest-compatible)."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx forms accepted), or walmart (live walmart.com search, 2026-10-18: 2 credits per results page, at most 3 pages per call, sort_by maps to Walmart's sorts, category_id / refinements are Amazon-only).","default":"us","title":"Country"},"description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx forms accepted), or walmart (live walmart.com search, 2026-10-18: 2 credits per results page, at most 3 pages per call, sort_by maps to Walmart's sorts, category_id / refinements are Amazon-only)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Start page (default 1).","default":1,"title":"Page"},"description":"Start page (default 1)."},{"name":"max_page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10,"minimum":1},{"type":"null"}],"description":"Auto-paginate page..max_page and concatenate (max 10 pages per request). Billed per page ACTUALLY fetched — Amazon can run out of results before max_page.","title":"Max Page"},"description":"Auto-paginate page..max_page and concatenate (max 10 pages per request). Billed per page ACTUALLY fetched — Amazon can run out of results before max_page."},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"featured | price_low_to_high | price_high_to_low | average_review | most_recent | bestseller_rankings.","title":"Sort By"},"description":"featured | price_low_to_high | price_high_to_low | average_review | most_recent | bestseller_rankings."},{"name":"category_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Amazon browse-node id (becomes &node=).","title":"Category Id"},"description":"Amazon browse-node id (becomes &node=)."},{"name":"refinements","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"description":"Amazon rh= refinement value. Round-trips: feed back any refinements[*].value from a previous response.","title":"Refinements"},"description":"Amazon rh= refinement value. Round-trips: feed back any refinements[*].value from a previous response."},{"name":"exclude_sponsored","in":"query","required":false,"schema":{"type":"boolean","description":"Drop inline sponsored results. Often a no-op: Amazon usually places paid results in separate carousels outside the organic grid.","default":false,"title":"Exclude Sponsored"},"description":"Drop inline sponsored results. Often a no-op: Amazon usually places paid results in separate carousels outside the organic grid."},{"name":"number_of_results","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":500,"minimum":1},{"type":"null"}],"description":"Truncate the returned list.","title":"Number Of Results"},"description":"Truncate the returned list."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/bestsellers":{"get":{"summary":"Bestsellers","description":"LIVE Amazon Best Sellers list for one category — up to 100 products in Amazon's rank order\n(rank, ASIN, title, link, image, rating, ratings_total, price), the category's full breadcrumb\nname and path (current_category), and its direct subcategories with their URLs, so a caller can\nwalk the tree. A root URL (or country alone) returns the marketplace's top-level categories\ninstead (page_type \"root\").\n\nFetched from Amazon at request time — expect ~15-35 s for the top 100, ~15 s for a root list (set\nclient timeouts to 180 s+). Amazon refreshes these lists hourly, so an answer may come from our\ncache: up to 30 min old for a category, 24 h for the root list (`cached`, `cache_age_seconds`,\n`observed_at` = when the list was fetched from Amazon).\n\nBilling: 1 credit per page of 50 products returned (the full top 100 = 2), cached or fresh — it\nis the same list. The root list is free. A category Amazon does not have (404), a blocked fetch\n(502) and an empty list are never billed; a partial answer (page 2 failed) bills the page returned.\n\nHonest limits: names are in the page's language (German pages are local; fr / it / es / jp / mx /\nbr are requested in English); ranks are Amazon's at fetch time; price is null when the card shows\nnone; node_id is null where Amazon's URL carries only a slug (top-level departments).","operationId":"bestsellers_v1_bestsellers_get","parameters":[{"name":"url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"description":"Any Amazon Best Sellers URL: a category (/gp/bestsellers/kitchen/289814, /Best-Sellers-.../zgbs/..., with or without the /ref=... tail, query string or /-/en/ prefix) or a marketplace's root (/gp/bestsellers/). The marketplace comes from the host (all 11 Amazon marketplaces).","title":"Url"},"description":"Any Amazon Best Sellers URL: a category (/gp/bestsellers/kitchen/289814, /Best-Sellers-.../zgbs/..., with or without the /ref=... tail, query string or /-/en/ prefix) or a marketplace's root (/gp/bestsellers/). The marketplace comes from the host (all 11 Amazon marketplaces)."},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional. Alone (no url): that marketplace's root list of top-level categories. With url: must match the URL's marketplace. us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted).","title":"Country"},"description":"Optional. Alone (no url): that marketplace's root list of top-level categories. With url: must match the URL's marketplace. us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted)."},{"name":"pages","in":"query","required":false,"schema":{"type":"integer","maximum":2,"minimum":1,"description":"1 = ranks 1-50, 2 = ranks 1-100 (default). Page 2 is fetched only when page 1 is full.","default":2,"title":"Pages"},"description":"1 = ranks 1-50, 2 = ranks 1-100 (default). Page 2 is fetched only when page 1 is full."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/deals":{"get":{"summary":"Deals","description":"LIVE Amazon Today's Deals - the deals page of one marketplace, read from Amazon at request time, filtered\nthe way Amazon's own page filters it: department, deal collection (lightning deals, coupons, trending,\nstarted / ending today, or any collection id an answer lists), percent off, price, Prime Exclusive, rating,\nbrand. Each deal: position, ASIN, title, link, image, deal_id + deal_link, deal_type (BEST_DEAL /\nLIGHTNING_DEAL ...), deal_state, percent_claimed, ends_at (the countdown), deal_price, list_price (Amazon's\nreference price with its label - RRP / Was / Typical ...), percent_off, savings, deal_badge, coupon, brand,\ndepartment_ids, product_type, variations. The answer also carries the page's departments (categories), deal\ncollections and facets to filter by next, filter_check (did Amazon apply each filter you asked for), and\npagination with has_more.\n\nFetched from Amazon at request time - expect ~10-30 s a page (pages=5 can take ~2 min; set client timeouts\nto 300 s). Lightning deals move fast, so an identical request may be answered from our cache for up to\n15 min (`cached`, `cache_age_seconds`, `observed_at` = when the deals were read from Amazon).\n\nBilling: 1 credit per deals page fetched that returned at least one deal, whatever its page_size (30, 60, 90\nor 120 deals a page are all 1 credit, so page_size=120 is the best value), cached or fresh. A page with no\ndeals is free: an empty list (e.g. no lightning deals running right now), a blocked fetch (502), a busy\nmarketplace (503) and bad input (422) are never billed; a partial answer (a later page failed) bills the pages\nreturned.\n\nHonest limits: no starts_at (the page does not carry it) and ends_at only where Amazon shows a countdown; no\ntotal count - Amazon publishes none, so pagination.has_more says whether the last page came back full;\ncategory_id applies one department at a time; collections differ per marketplace and over time (events) - the\nfive deal_types are the stable ones, and an unknown collection id silently returns the default list\n(filter_check.collection = unverified); filter_check per requested filter is applied / not_applied /\nunverified, read from Amazon's own selected refinements and the returned deals - a filter Amazon did not apply\n(not_applied, e.g. a category_id that is not one of the marketplace's deals departments) is a 422 naming it,\nnever billed, instead of the unfiltered page. Page language follows the on-demand locale policy (fr / it / es /\njp in English, de / mx / br local); prices are numbers.","operationId":"deals_v1_deals_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Amazon marketplace: 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. Amazon only.","title":"Country"},"description":"The Amazon marketplace: 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. Amazon only."},{"name":"url","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"Optional: an Amazon deals URL (/deals, /events/deals or /gp/goldbox, optionally behind /-/xx/). The host decides the marketplace; its query string is kept (e.g. a discounts-widget filter copied from the browser).","title":"Url"},"description":"Optional: an Amazon deals URL (/deals, /events/deals or /gp/goldbox, optionally behind /-/xx/). The host decides the marketplace; its query string is kept (e.g. a discounts-widget filter copied from the browser)."},{"name":"category_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":400},{"type":"null"}],"description":"A deals department id from categories[] of any answer (comma list accepted; Amazon applies one department).","title":"Category Id"},"description":"A deals department id from categories[] of any answer (comma list accepted; Amazon applies one department)."},{"name":"collection","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"description":"A deal collection id from collections[] of any answer (e.g. deals-collection-lightning-deals). Not with deal_types.","title":"Collection"},"description":"A deal collection id from collections[] of any answer (e.g. deals-collection-lightning-deals). Not with deal_types."},{"name":"deal_types","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"One of lightning_deal, trending, coupons, started_today, ending_today - the stable collections on every marketplace. Not with collection.","title":"Deal Types"},"description":"One of lightning_deal, trending, coupons, started_today, ending_today - the stable collections on every marketplace. Not with collection."},{"name":"discount","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Rainforest form: 10_percent_off, 25_percent_off, 50_percent_off or 70_percent_off (= min_discount). Not with min_discount.","title":"Discount"},"description":"Rainforest form: 10_percent_off, 25_percent_off, 50_percent_off or 70_percent_off (= min_discount). Not with min_discount."},{"name":"min_discount","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"description":"Minimum percent off, 0-100.","title":"Min Discount"},"description":"Minimum percent off, 0-100."},{"name":"max_discount","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"description":"Maximum percent off, 0-100.","title":"Max Discount"},"description":"Maximum percent off, 0-100."},{"name":"min_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"description":"Minimum deal price in the marketplace currency. Amazon applies whole units; a fraction is rounded outward (down).","title":"Min Price"},"description":"Minimum deal price in the marketplace currency. Amazon applies whole units; a fraction is rounded outward (down)."},{"name":"max_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"description":"Maximum deal price in the marketplace currency. Amazon applies whole units; a fraction is rounded outward (up).","title":"Max Price"},"description":"Maximum deal price in the marketplace currency. Amazon applies whole units; a fraction is rounded outward (up)."},{"name":"prime_exclusive","in":"query","required":false,"schema":{"type":"boolean","description":"true = Prime Exclusive deals only.","default":false,"title":"Prime Exclusive"},"description":"true = Prime Exclusive deals only."},{"name":"minimum_rating","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"1-4 (or 4_and_up form): products rated at least that many stars.","title":"Minimum Rating"},"description":"1-4 (or 4_and_up form): products rated at least that many stars."},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"A brand id from facets.brands of an answer (e.g. 811979|dreame).","title":"Brand"},"description":"A brand id from facets.brands of an answer (e.g. 811979|dreame)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":400,"minimum":1,"description":"1-based page of the deals list (default 1).","default":1,"title":"Page"},"description":"1-based page of the deals list (default 1)."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":120,"minimum":30,"description":"Deals per page: 30, 60 (default), 90 or 120 - Amazon serves deals pages in steps of 30 and ignores any other size. Every page is 1 credit whatever its size, so 120 gives the most deals per credit.","default":60,"title":"Page Size"},"description":"Deals per page: 30, 60 (default), 90 or 120 - Amazon serves deals pages in steps of 30 and ignores any other size. Every page is 1 credit whatever its size, so 120 gives the most deals per credit."},{"name":"pages","in":"query","required":false,"schema":{"type":"integer","maximum":5,"minimum":1,"description":"Consecutive pages merged into one answer, from page (1-5, default 1). Stops early on a short page; 1 credit per page that returned deals.","default":1,"title":"Pages"},"description":"Consecutive pages merged into one answer, from page (1-5, default 1). Stops early on a short page; 1 credit per page that returned deals."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/offers":{"get":{"summary":"Offers","description":"LIVE Amazon offers page for one product - every offer on every page of Amazon's \"All offers\" view (up to 10\npages): seller, seller_id, price, shipping_cost, condition, buy box, FBA / Prime, ships-from, delivery text and\nthe seller's feedback - plus the buy box and the page's own header (title, image, rating, review count). No\nproduct page is fetched: no brand, BSR, description, bullets or reviews (use /v1/product for those).\n\nFetched at request time - typically 4-12 s (one page ~4 s; a long list walks every page). current_sellers has the\nsame shape /v1/product returns (buy box first, then price ascending; buybox_days_30d and the 30-day buy-box\nshares carried over from our observations), fulfillment classifies every offer AMZ / FBA / FBM with delivery\ndays, seller_ratings lists the sellers' feedback records.\n\nno_sellers=true means Amazon lists no offer for the product right now - an answer, not a failure: we confirm it\nthrough a second, independent fetch before serving it. Billing: 0.5 credit when the answer carries at least one\noffer (any condition); a no-offers answer, an ASIN Amazon does not have (404), a failed fetch (502) and a busy\nmarketplace (503) are never billed. Second-hand offers are counted either way; include_used lists them.\nSince 2026-10-15 the answer carries buybox_condition (new | used | null = no featured offer) with\nbuybox_condition_source (offers_page) and buybox_condition_detail (the pinned offer's condition text or the used\nstorefront's name, e.g. Amazon Resale) — with zip= too.","operationId":"offers_v1_offers_get","parameters":[{"name":"asin","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Amazon ASIN (10 characters; a print book's ISBN-10). Provide asin or gtin.","title":"Asin"},"description":"Amazon ASIN (10 characters; a print book's ISBN-10). Provide asin or gtin."},{"name":"gtin","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"A barcode instead of an ASIN (UPC / EAN / GTIN / ISBN-13), resolved exactly as /v1/product resolves gtin - the barcode on a listing we observe, a book's ISBN-10, the same product on another Amazon marketplace, then Amazon's own search (gtin_resolution says which). A barcode nothing resolves is a 404, never billed.","title":"Gtin"},"description":"A barcode instead of an ASIN (UPC / EAN / GTIN / ISBN-13), resolved exactly as /v1/product resolves gtin - the barcode on a listing we observe, a book's ISBN-10, the same product on another Amazon marketplace, then Amazon's own search (gtin_resolution says which). A barcode nothing resolves is a 404, never billed."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted). Amazon only.","default":"us","title":"Country"},"description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted). Amazon only."},{"name":"marketplace","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for country (amazon-de or de).","title":"Marketplace"},"description":"Alias for country (amazon-de or de)."},{"name":"include_used","in":"query","required":false,"schema":{"type":"boolean","description":"Include used, refurbished, open-box and collectible offers in current_sellers.sellers. Default false lists the new-condition offers; current_sellers always carries used_offer_count, lowest_new and lowest_used either way. Not billed extra.","default":false,"title":"Include Used"},"description":"Include used, refurbished, open-box and collectible offers in current_sellers.sellers. Default false lists the new-condition offers; current_sellers always carries used_offer_count, lowest_new and lowest_used either way. Not billed extra."},{"name":"zip","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"(2026-10-14) A US 5-digit ZIP: the offers page as Amazon shows it to a shopper at that ZIP, with location (Amazon's confirmed 'Deliver to' answer) and deliverable (whether the item is offered to that ZIP right now - Amazon Fresh and Whole Foods items deliver only to some ZIPs). Page 1 of the offers only; a one-off session, nothing stored. country=us only. 1 credit when the answer carries an offer; a ZIP Amazon rejects is a 422, never billed.","title":"Zip"},"description":"(2026-10-14) A US 5-digit ZIP: the offers page as Amazon shows it to a shopper at that ZIP, with location (Amazon's confirmed 'Deliver to' answer) and deliverable (whether the item is offered to that ZIP right now - Amazon Fresh and Whole Foods items deliver only to some ZIPs). Page 1 of the offers only; a one-off session, nothing stored. country=us only. 1 credit when the answer carries an offer; a ZIP Amazon rejects is a 422, never billed."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/seller":{"get":{"summary":"Seller Profile","description":"Seller profile: rating, counts, positive %, feedback summary per period, rating histogram, up to 5 recent\nfeedback entries (date, rating, struck - never the rater or the text) and, where the seller publishes one on\nAmazon, the business block (name, registration, address...). tracking{} says since when and how often we have\nobserved the seller; history=true adds the change-point series. Not found / suppressed / failed: never billed.","operationId":"seller_profile_v1_seller_get","parameters":[{"name":"seller_id","in":"query","required":true,"schema":{"type":"string","minLength":9,"maxLength":25,"description":"Amazon seller id (A + 8-24 letters/digits), as in /sp?seller=... or the seller_id of any offer in /v1/product.","title":"Seller Id"},"description":"Amazon seller id (A + 8-24 letters/digits), as in /sp?seller=... or the seller_id of any offer in /v1/product."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br. Walmart has no seller pages.","default":"us","title":"Country"},"description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br. Walmart has no seller pages."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(cache|live|auto)$","description":"cache: our stored observation (0.5 credit) - the seller page as our tracker last read it (full profile: star rating, per-period feedback, histogram, recent feedback, business block), or the seller page we fetched in the last 24 h, or - for sellers not stored yet - the warehouse record (positive % + feedback count). live: fetch the seller page now (1 credit). auto (default): the stored observation when it is younger than max_age_days, else live; billed as what was served.","default":"auto","title":"Mode"},"description":"cache: our stored observation (0.5 credit) - the seller page as our tracker last read it (full profile: star rating, per-period feedback, histogram, recent feedback, business block), or the seller page we fetched in the last 24 h, or - for sellers not stored yet - the warehouse record (positive % + feedback count). live: fetch the seller page now (1 credit). auto (default): the stored observation when it is younger than max_age_days, else live; billed as what was served."},{"name":"max_age_days","in":"query","required":false,"schema":{"type":"integer","maximum":3650,"minimum":0,"description":"auto only: how old a stored observation may be before we fetch live (default 14, the tracker's refresh cadence).","default":14,"title":"Max Age Days"},"description":"auto only: how old a stored observation may be before we fetch live (default 14, the tracker's refresh cadence)."},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","description":"Also return history{}: the seller's rating change points (positive %, star rating, counts per period) and storefront-size points since we first observed the seller, oldest first, UTC. +0.5 credit when at least one point comes back.","default":false,"title":"History"},"description":"Also return history{}: the seller's rating change points (positive %, star rating, counts per period) and storefront-size points since we first observed the seller, oldest first, UTC. +0.5 credit when at least one point comes back."},{"name":"history_points","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"description":"history=true: the latest N change points per series (default 500).","default":500,"title":"History Points"},"description":"history=true: the latest N change points per series (default 500)."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/seller/products":{"get":{"summary":"Seller Products","description":"What a seller sells: the live storefront (mode=live) or the products we have observed the seller offering\n(mode=cache). Empty storefront, not found, suppressed, blocked: never billed.","operationId":"seller_products_v1_seller_products_get","parameters":[{"name":"seller_id","in":"query","required":true,"schema":{"type":"string","minLength":9,"maxLength":25,"description":"Amazon seller id (A + 8-24 letters/digits).","title":"Seller Id"},"description":"Amazon seller id (A + 8-24 letters/digits)."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br.","default":"us","title":"Country"},"description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(cache|live)$","description":"cache (default): products we OBSERVED this seller offering, 25 per page with buy-box days and the observed price range - 1 credit per page. live: the seller's storefront on Amazon right now, the /v1/serp object - 1 credit per page actually fetched.","default":"cache","title":"Mode"},"description":"cache (default): products we OBSERVED this seller offering, 25 per page with buy-box days and the observed price range - 1 credit per page. live: the seller's storefront on Amazon right now, the /v1/serp object - 1 credit per page actually fetched."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page (cache: 25 products per page, up to 40 pages; live: Amazon's page, 1-10).","default":1,"title":"Page"},"description":"Page (cache: 25 products per page, up to 40 pages; live: Amazon's page, 1-10)."},{"name":"max_page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10,"minimum":1},{"type":"null"}],"description":"live only: auto-paginate page..max_page (max 10); billed per page actually fetched.","title":"Max Page"},"description":"live only: auto-paginate page..max_page (max 10); billed per page actually fetched."},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"live only: featured | price_low_to_high | price_high_to_low | average_review | most_recent | bestseller_rankings.","title":"Sort By"},"description":"live only: featured | price_low_to_high | price_high_to_low | average_review | most_recent | bestseller_rankings."},{"name":"refinements","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"live only: Amazon refinement list (rh=...).","title":"Refinements"},"description":"live only: Amazon refinement list (rh=...)."},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"description":"live only: search inside this seller's storefront. Alias: search_term.","title":"Q"},"description":"live only: search inside this seller's storefront. Alias: search_term."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/brand":{"get":{"summary":"Brand Profile Route","description":"Brand dossier from our observations: catalog size, sellers and buy-box control, Amazon-retail share, FBA penetration, seller\nconcentration and churn, trend grades, since-when-observed, category benchmarks and the top-10 sellers. 1 credit; unknown brand 404, free.","operationId":"brand_profile_route_v1_brand_get","parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Brand name as Amazon prints it (case-insensitive).","title":"Brand"},"description":"Brand name as Amazon prints it (case-insensitive)."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br.","default":"us","title":"Country"},"description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br."},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","description":"Also return history.monthly: up to 24 calendar months of ASINs / sellers / buy-box days / price / rating. +0.5 credit when non-empty.","default":false,"title":"History"},"description":"Also return history.monthly: up to 24 calendar months of ASINs / sellers / buy-box days / price / rating. +0.5 credit when non-empty."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/brand/sellers":{"get":{"summary":"Brand Sellers Route","description":"Who sells the brand: every seller observed winning the buy box on its listings in the rolling 16-month window, most buy-box\ndays first, 25 per page with each seller's feedback record. 1 credit per page returned.","operationId":"brand_sellers_route_v1_brand_sellers_get","parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"title":"Brand"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":1,"title":"Page"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/brand/network":{"get":{"summary":"Brand Network Route","description":"The brand's seller map: the brands connected to it because the same third-party sellers win the buy box on both -\nnodes (with each brand's seller/ASIN counts, control, pressure, cluster and layout where available) and weighted edges, one hop. 1 credit.","operationId":"brand_network_route_v1_brand_network_get","parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"title":"Brand"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Strongest edges to return (max 50).","default":20,"title":"Limit"},"description":"Strongest edges to return (max 50)."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/seller/brands":{"get":{"summary":"Seller Brands Route","description":"The operator footprint: the brands this seller was observed winning the buy box on (16 months), with the operator header\n(brands/ASINs touched, buy-box days, FBA share, revenue signal). 1 credit per page of 25.","operationId":"seller_brands_route_v1_seller_brands_get","parameters":[{"name":"seller_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":9,"maxLength":25},{"type":"null"}],"description":"Amazon seller id - or give name.","title":"Seller Id"},"description":"Amazon seller id - or give name."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"description":"Seller display name as Amazon prints it.","title":"Name"},"description":"Seller display name as Amazon prints it."},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":1,"title":"Page"}},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","description":"Also return history.monthly: up to 24 months of brands / ASINs / buy-box days. +0.5 credit when non-empty.","default":false,"title":"History"},"description":"Also return history.monthly: up to 24 months of brands / ASINs / buy-box days. +0.5 credit when non-empty."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/seller/network":{"get":{"summary":"Seller Network Route","description":"Connected operators: sellers observed winning the buy box on the same brands as this one, strongest overlap first, one hop. 1 credit.","operationId":"seller_network_route_v1_seller_network_get","parameters":[{"name":"seller_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":9,"maxLength":25},{"type":"null"}],"title":"Seller Id"}},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}],"title":"Name"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/category":{"get":{"summary":"Category Route","description":"Category landscape: size, pricing, Amazon-retail share, FBA penetration, seller concentration (HHI), heat, catalog churn, demand\nsignals, root-level benchmark percentiles, sub-categories and (for roots) the top-10 brands. 1 credit.","operationId":"category_route_v1_category_get","parameters":[{"name":"category_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"The warehouse's category id - from /v1/categories, /v1/categories/search, or the category field of any /v1/search result. Either this or node_id.","title":"Category Id"},"description":"The warehouse's category id - from /v1/categories, /v1/categories/search, or the category field of any /v1/search result. Either this or node_id."},{"name":"node_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Alternative to category_id (2026-10-07): the Amazon browse-node id, resolved to the category we hold under it on that marketplace.","title":"Node Id"},"description":"Alternative to category_id (2026-10-07): the Amazon browse-node id, resolved to the category we hold under it on that marketplace."},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","description":"Also return history.monthly: products / brands / sellers per month. +0.5 credit when non-empty.","default":false,"title":"History"},"description":"Also return history.monthly: products / brands / sellers per month. +0.5 credit when non-empty."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/categories":{"get":{"summary":"Categories List Route","description":"The category taxonomy (2026-10-07) - the names /v1/search's `category` filter accepts on this marketplace and the ids\n/v1/category takes. Roots by default, one level down per call with parent_id. Every active category, with the warehouse id,\nthe Amazon browse-node id, the local name (and its English alias where we hold one), path, depth, number of children and the\nobserved ASIN / brand counts. Free, any key, rate-limited like every call; cached ten minutes.","operationId":"categories_list_route_v1_categories_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br.","default":"us","title":"Country"},"description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br."},{"name":"parent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"A category id: list its children. Omit for the marketplace's root categories.","title":"Parent Id"},"description":"A category id: list its children. Omit for the marketplace's root categories."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/categories/search":{"get":{"summary":"Categories Search Route","description":"Find category ids by name or path. Free.","operationId":"categories_search_route_v1_categories_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120,"description":"Part of a category name or path.","title":"Q"},"description":"Part of a category name or path."},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keywords":{"get":{"summary":"Keywords Route","description":"Amazon's own autocomplete suggestion lists for a seed (2026-10-07): up to 6 lists - one per crawled prefix / department -\neach term with its position 1-10 within that list, when it was first and last observed, since when it has been in the list\nand the marketplaces it was observed in; plus related observed vocabulary. Observed suggestion ranking, not volume figures,\nnot a product-ranking map. 1 credit; unknown seed 404, free.","operationId":"keywords_route_v1_keywords_get","parameters":[{"name":"seed","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":120,"description":"A seed term or prefix, e.g. 'electric toothbrush' - at least 3 characters.","title":"Seed"},"description":"A seed term or prefix, e.g. 'electric toothbrush' - at least 3 characters."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br (Walmart has no autocomplete corpus).","default":"us","title":"Country"},"description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br (Walmart has no autocomplete corpus)."},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","description":"Also return history: every observation of each returned list since the harvest began (a term entering, leaving or moving position). +0.5 credit when at least one closed observation exists.","default":false,"title":"History"},"description":"Also return history: every observation of each returned list since the harvest began (a term entering, leaving or moving position). +0.5 credit when at least one closed observation exists."},{"name":"history_points","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"description":"history=true: at most N observation rows across the lists (oldest first).","default":500,"title":"History Points"},"description":"history=true: at most N observation rows across the lists (oldest first)."},{"name":"related_limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":0,"description":"Related observed vocabulary starting with the seed (default 25).","default":25,"title":"Related Limit"},"description":"Related observed vocabulary starting with the seed (default 25)."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keywords/compare":{"get":{"summary":"Keywords Compare Route","description":"The seed's primary suggestion list on each requested marketplace and a matrix of every term's position per marketplace\n(null where absent) plus the marketplaces each term was observed in - the cross-marketplace vocabulary. 1 credit; nothing\nobserved anywhere 404, free.","operationId":"keywords_compare_route_v1_keywords_compare_get","parameters":[{"name":"seed","in":"query","required":true,"schema":{"type":"string","minLength":3,"maxLength":120,"description":"A seed term or prefix, at least 3 characters.","title":"Seed"},"description":"A seed term or prefix, at least 3 characters."},{"name":"countries","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated Amazon marketplaces to compare (2-11), e.g. us,uk,de.","default":"us,uk,de","title":"Countries"},"description":"Comma-separated Amazon marketplaces to compare (2-11), e.g. us,uk,de."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keywords/rankings":{"get":{"summary":"Keyword Rankings Route","description":"Page 1 of Amazon US search for a keyword, as we last observed it: the organic order with product facts and each\nproduct's latest observed buy box, the sponsored units present in the page HTML, the keyword's badges (Overall Pick),\nAmazon's result count, who holds the page (page_summary) and what changed since the previous observation, dated.\nObserved positions, a weekly sample, never volume figures. 1 credit; a keyword not in the set or not observed yet is\na 404, free.","operationId":"keyword_rankings_route_v1_keywords_rankings_get","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"description":"A search term, e.g. 'micro sd card 128gb high endurance' (case-insensitive).","title":"Keyword"},"description":"A search term, e.g. 'micro sd card 128gb high endurance' (case-insensitive)."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon US only: the map covers amazon.com search.","default":"us","title":"Country"},"description":"Amazon US only: the map covers amazon.com search."},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","description":"Also return history: every stored observation of the keyword (about one a week) and the organic-rank series of the products on the latest page. +0.5 credit when more than the latest observation came back.","default":false,"title":"History"},"description":"Also return history: every stored observation of the keyword (about one a week) and the organic-rank series of the products on the latest page. +0.5 credit when more than the latest observation came back."},{"name":"history_points","in":"query","required":false,"schema":{"type":"integer","maximum":104,"minimum":1,"description":"history=true: at most N observations, the newest kept (default 26).","default":26,"title":"History Points"},"description":"history=true: at most N observations, the newest kept (default 26)."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/product/keywords":{"get":{"summary":"Product Keywords Route","description":"Reverse ASIN: every keyword in the observed set whose latest page 1 shows the product - organically (with its rank) or\nin a sponsored unit seen in the page HTML - with the keyword's result count and badges, dated. Organic first, best rank\nfirst. With asins= (up to 10) it compares the product with its competitors: every keyword where any of them appears,\neach one's rank, how many share the page and the gaps. 1 credit per page of 25 keywords returned, per ASIN; a product\nnot seen on any observed page is a 404, free.","operationId":"product_keywords_route_v1_product_keywords_get","parameters":[{"name":"asin","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":10,"maxLength":10},{"type":"null"}],"description":"10-character Amazon ASIN (or use asins).","title":"Asin"},"description":"10-character Amazon ASIN (or use asins)."},{"name":"asins","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"description":"Up to 10 ASINs, comma-separated: the product first, then the competitors to compare it with. Each row then carries every competitor's rank, asins_on_page and gap.","title":"Asins"},"description":"Up to 10 ASINs, comma-separated: the product first, then the competitors to compare it with. Each row then carries every competitor's rank, asins_on_page and gap."},{"name":"country","in":"query","required":false,"schema":{"type":"string","description":"Amazon US only: the map covers amazon.com search.","default":"us","title":"Country"},"description":"Amazon US only: the map covers amazon.com search."},{"name":"placement","in":"query","required":false,"schema":{"type":"string","description":"all (default), organic or sponsored.","default":"all","title":"Placement"},"description":"all (default), organic or sponsored."},{"name":"gaps","in":"query","required":false,"schema":{"type":"boolean","description":"With asins: only the keywords where a competitor is on page 1 organically and the first product is not.","default":false,"title":"Gaps"},"description":"With asins: only the keywords where a competitor is on page 1 organically and the first product is not."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Keywords per page (default 50); billed 1 credit per started 25 returned, per ASIN.","default":50,"title":"Limit"},"description":"Keywords per page (default 50); billed 1 credit per started 25 returned, per ASIN."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":100000,"minimum":0,"description":"Skip this many keywords (paging).","default":0,"title":"Offset"},"description":"Skip this many keywords (paging)."},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","description":"Also return each keyword's rank_history: the first product's organic rank in every stored observation of that keyword. +0.5 credit once when any returned keyword has more than one observation.","default":false,"title":"History"},"description":"Also return each keyword's rank_history: the first product's organic rank in every stored observation of that keyword. +0.5 credit once when any returned keyword has more than one observation."},{"name":"history_points","in":"query","required":false,"schema":{"type":"integer","maximum":104,"minimum":1,"description":"history=true: at most N observations per keyword, the newest kept.","default":26,"title":"History Points"},"description":"history=true: at most N observations per keyword, the newest kept."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/brands/movers":{"get":{"summary":"Brand Movers Route","description":"Brands gaining (or losing) distinct buy-box sellers fastest over the last 30 or 90 days. 1 credit per page of 25.","operationId":"brand_movers_route_v1_brands_movers_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"window","in":"query","required":false,"schema":{"type":"integer","description":"30 or 90 days.","default":30,"title":"Window"},"description":"30 or 90 days."},{"name":"direction","in":"query","required":false,"schema":{"type":"string","pattern":"^(up|down)$","description":"up = gaining sellers, down = losing sellers.","default":"up","title":"Direction"},"description":"up = gaining sellers, down = losing sellers."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":1,"title":"Page"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/brands/top":{"get":{"summary":"Brands Top Route","description":"Brands ranked by observed buy-box days, sellers, control score, ASINs, revenue signal or Amazon share. 1 credit per page of 25.","operationId":"brands_top_route_v1_brands_top_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"category_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Root category id to narrow to (brands are filed under their dominant root).","title":"Category Id"},"description":"Root category id to narrow to (brands are filed under their dominant root)."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"buybox_days | sellers | control_score | asins | revenue | amazon_share","default":"buybox_days","title":"Sort"},"description":"buybox_days | sellers | control_score | asins | revenue | amazon_share"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":1,"title":"Page"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sellers/movers":{"get":{"summary":"Seller Movers Route","description":"Sellers whose observed buy-box footprint grew (or shrank) most over the last 30 or 90 days. 1 credit per page of 25.","operationId":"seller_movers_route_v1_sellers_movers_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"window","in":"query","required":false,"schema":{"type":"integer","default":30,"title":"Window"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","pattern":"^(up|down)$","default":"up","title":"Direction"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":1,"title":"Page"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sellers/top":{"get":{"summary":"Sellers Top Route","description":"Third-party sellers ranked by cross-brand footprint (16 months). 1 credit per page of 25.","operationId":"sellers_top_route_v1_sellers_top_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"brands | buybox_days | asins | revenue","default":"brands","title":"Sort"},"description":"brands | buybox_days | asins | revenue"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":1,"title":"Page"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/categories/top":{"get":{"summary":"Categories Top Route","description":"Categories ranked by size, brands, heat, revenue signal, price or sellers; or the children of one category. 1 credit per page of 25.","operationId":"categories_top_route_v1_categories_top_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"us","title":"Country"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"asins | brands | heat | revenue | price | sellers","default":"asins","title":"Sort"},"description":"asins | brands | heat | revenue | price | sellers"},{"name":"root_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only root categories (ignored when parent_id is given).","default":true,"title":"Root Only"},"description":"Only root categories (ignored when parent_id is given)."},{"name":"parent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"List the children of this category instead.","title":"Parent Id"},"description":"List the children of this category instead."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":1,"title":"Page"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account":{"get":{"summary":"Account Info","description":"Balance, plan and recent usage for the calling key.\n\nAdded 2026-08-06: an agent-driven evaluation hit five consecutive 404s\n(/v1/credits, /v1/account, /v1/usage, /v1/me, /v1/balance) trying to check\nthe balance before spending. For an API whose callers are increasingly\nscripts and agents, \"how many credits do I have\" is a required call. Never\nbilled — checking your balance must not cost you credits.","operationId":"account_info_v1_account_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch-estimate":{"post":{"summary":"Batch Estimate","description":"Price a batch before it runs. Free, always — an estimate is never billed. Every kind: product (age histogram,\nwarehouse / live split), search, the keyed kinds and every other endpoint (2026-10-12: rows x the endpoint's largest\nanswer, with estimated_live_rows for the live kinds and derived_daily_cap for the capped ones).","operationId":"batch_estimate_v1_batch_estimate_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEstimateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches":{"post":{"summary":"Batch Create","description":"Create a named, re-runnable batch (R2). Validated like the estimate:\ninvalid lines are kept — they come back as `failed` result rows carrying the\nreason (R11: never silently dropped) — and duplicates are noted and folded\nfor billing. kind=search (0539): a list of search TERMS served like /v1/serp\n— always live; duplicate terms are answered on their canonical line rather\nthan fetched twice (a live SERP fetch is a real cost). Every other endpoint\nis a kind too (2026-10-12): one key per line (or `pages` for the ranked\nlists), the endpoint's query parameters in `params`, each row billed as\nthe endpoint bills it - see /docs#batch-all.","operationId":"batch_create_v1_batches_post","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"Batch List","description":"List this account's batches (soft-deleted excluded), newest first.","operationId":"batch_list_v1_batches_get","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}":{"get":{"summary":"Batch Detail","description":"Batch detail: line stats + recent runs.","operationId":"batch_detail_v1_batches__batch_id__get","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"summary":"Batch Update","description":"Edit a batch's serving settings (mode and/or max_age_days). Applies to\nFUTURE runs only: every run snapshots the settings it launches with (0537)\nand keeps them — an in-flight run finishes under its launch settings, and\npast runs' recorded values never change. Same validation as create:\nWalmart + live is a loud 422 (R14) — a mode is never silently downgraded.","operationId":"batch_update_v1_batches__batch_id__patch","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchUpdateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Batch Delete","description":"Soft delete. In-flight runs are cancelled; existing result files remain\nreadable until the 30-day retention cron collects them.","operationId":"batch_delete_v1_batches__batch_id__delete","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}/runs":{"post":{"summary":"Batch Run Create","description":"Queue a run. Computes and stores a fresh estimate (G1) and refuses with\n402 when the account balance is below the estimate — nothing is billed\nuntil rows actually serve (R13). The worker picks the run up within\nseconds; watch progress on the run endpoint and download partials any time.","operationId":"batch_run_create_v1_batches__batch_id__runs_post","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}/estimate":{"post":{"summary":"Batch Fresh Estimate","description":"Fresh estimate for a saved batch against the CURRENT warehouse state —\nnever billed (R5). The cache/live split moves as the nightly walk refreshes\nrows, so re-estimate before re-running.","operationId":"batch_fresh_estimate_v1_batches__batch_id__estimate_post","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}/schedule":{"post":{"summary":"Batch Schedule","description":"Set / enable / disable the recurring schedule (R3: daily, weekly,\nmonthly). Firing is period-based (server date): daily fires on the first\nscheduler tick after midnight, weekly on Monday, monthly on the 1st — at\nmost once per period. Each firing computes a FRESH estimate and refuses to\nrun (recording a cancelled run + emailing you) when the estimate exceeds\nthe credit ceiling or your balance (G2) — a schedule never surprises you\nwith a bill.","operationId":"batch_schedule_v1_batches__batch_id__schedule_post","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}/runs/{run_id}":{"get":{"summary":"Batch Run Detail","description":"Progress (R8): all row-state counters plus credits charged so far, and the\nestimate the run launched under. Queued runs carry queue_position (runs are\nserialized per marketplace, FIFO by creation).","operationId":"batch_run_detail_v1_batches__batch_id__runs__run_id__get","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","title":"Run Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}/runs/{run_id}/resume":{"post":{"summary":"Batch Run Resume","description":"Resume a run that PAUSED at the credit floor (G3). The run RE-QUEUES on\nits marketplace (pausing released the slot; runs are serialized per\nmarketplace, FIFO by creation order) and continues exactly where it\nstopped; nothing already served is re-billed. If the balance is still at\nthe floor the run will pause again.","operationId":"batch_run_resume_v1_batches__batch_id__runs__run_id__resume_post","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","title":"Run Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}/runs/{run_id}/result.jsonl":{"get":{"summary":"Batch Run Result Jsonl","description":"Streaming JSONL download — works MID-RUN (R9): you get every row completed\nso far. Every row carries status, source, observed_at and age_days (R12).\nAuth: X-API-KEY, or the per-run ?token= from the completion email/webhook.","operationId":"batch_run_result_jsonl_v1_batches__batch_id__runs__run_id__result_jsonl_get","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","title":"Run Id"}},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batches/{batch_id}/runs/{run_id}/result.csv":{"get":{"summary":"Batch Run Result Csv","description":"Streaming CSV download (default columns) — works MID-RUN (R9).\nAuth: X-API-KEY, or the per-run ?token= from the completion email/webhook.","operationId":"batch_run_result_csv_v1_batches__batch_id__runs__run_id__result_csv_get","parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"integer","title":"Batch Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"integer","title":"Run Id"}},{"name":"token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["ops"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Health Health Get"}}}}}}}},"components":{"schemas":{"BatchCreateRequest":{"properties":{"name":{"type":"string","maxLength":120,"minLength":1,"title":"Name"},"kind":{"type":"string","pattern":"^(product|search|seller|brand|category|keywords|bestsellers|brand_network|brand_sellers|brands_movers|brands_top|categories|categories_top|category_search|deals|keyword_rankings|keywords_compare|offers|product_keywords|seller_brands|seller_network|seller_products|sellers_movers|sellers_top|shopping|warehouse_search)$","title":"Kind","description":"product (default): a list of ASINs served like /v1/product. search: a list of search TERMS served like /v1/serp — every run is a live Amazon fetch, Amazon marketplaces only. seller / brand / category / keywords (paid plans): seller ids / brand names / category ids / seed terms served like /v1/seller, /v1/brand, /v1/category and /v1/keywords. Every other endpoint (2026-10-12): shopping, warehouse_search, category_search (terms), bestsellers (urls), offers (asins), deals (category_ids: deals department ids or all), seller_products / seller_brands / seller_network (seller_ids), brand_sellers / brand_network (brands), keywords_compare (seeds), categories (category_ids), and the ranked lists brands_top / brands_movers / sellers_top / sellers_movers / categories_top (no list: pages). The endpoint's query parameters go in params. See /docs#batch-all.","default":"product"},"country":{"type":"string","title":"Country","description":"us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart (search batches: Amazon only)"},"mode":{"anyOf":[{"type":"string","pattern":"^(cache|live|auto)$"},{"type":"null"}],"title":"Mode","description":"Product batches (required there): cache = warehouse only (stale rows skipped, disclosed); live = scrape every row; auto = warehouse when fresh enough, scrape the rest. Walmart: the same three since 2026-10-18 (live = 2 credits a row). Seller batches: the same three (default auto, stored profile when younger than max_age_days). seller_products batches: cache (default) or live. Every other kind is served the way its endpoint serves it - sending a mode there is a 422."},"max_age_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Max Age Days","default":30},"asins":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Asins","description":"Product batches: ASINs (10-char) — or numeric item IDs for country=walmart. Every submitted line comes back as a result row."},"gtins":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Gtins","description":"Product batches, instead of asins (2026-10-12): barcodes (UPC / EAN / GTIN / ISBN-13; 8, 12, 13 or 14 digits). Each resolves like /v1/product?gtin= - our observed listings, a book's ISBN-10, the same product on another Amazon marketplace, and in mode auto / live one Amazon search per barcode we cannot place; every row says how (gtin_resolution). Unresolvable barcodes are never billed."},"source":{"anyOf":[{"type":"string","pattern":"^(tracked)$"},{"type":"null"}],"title":"Source","description":"Product batches (2026-10-14): tracked = the list is every ASIN this key is tracking on the batch's marketplace, read when the batch is created and at every re-run (POST /v1/track, GET /v1/product?track=true); typically with include [\"history_only\"]. Amazon only."},"terms":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Terms","description":"Search batches: the search terms. shopping / warehouse_search: the queries. category_search: category names. Every submitted line comes back as a result row (ok / empty / failed - never silently dropped)."},"seller_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Seller Ids","description":"seller / seller_products / seller_brands / seller_network batches: Amazon seller ids. Every line comes back as a result row (ok / empty / not_tracked / failed)."},"brands":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Brands","description":"brand / brand_sellers / brand_network batches: brand names as Amazon prints them."},"category_ids":{"anyOf":[{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","minItems":1},{"type":"null"}],"title":"Category Ids","description":"category batches: the warehouse's category ids. categories batches: parent ids, or root. deals batches: deals department ids, or all."},"seeds":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Seeds","description":"keywords / keywords_compare batches: seed terms or prefixes (3-120 characters), one per line."},"pages":{"anyOf":[{"type":"integer","maximum":40.0,"minimum":1.0},{"type":"null"}],"title":"Pages","description":"Search batches: pages per term (1-3, default 1). Positions stay continuous across pages; billed per page ACTUALLY fetched. Ranked-list batches: how many pages of 25 rows to take (1-40, default 1) - one result row per page."},"urls":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Urls","description":"Best Sellers batches: Amazon Best Sellers URLs, one per line, all on the batch's marketplace."},"params":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Params","description":"Endpoint batches: the query parameters of the endpoint the batch runs, fixed for every row (validated like the endpoint's own; unknown names are a 422). See /docs#batch-all."},"webhook_url":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Webhook Url","description":"Optional: POSTed on run completion/pause, HMAC-SHA256 signed (X-Logimu-Signature: sha256=<hex>). The signing secret is returned ONCE in the create response — store it."},"include":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Include","description":"Optional extras per JSONL result row. Seller / brand / category batches: [\"history\"] attaches the endpoint's history block (+0.5 per row when it comes back). Product batches: [\"reviews\"] attaches the observed featured-review set (≤50 per product, free); [\"used\"] adds the used / refurbished / open-box / collectible offers to current_sellers (and the per-condition series with offer_history; free, 2026-09-28; the CSV lowest_offer_price stays the lowest NEW offer); [\"offer_history\"] attaches the buy-box timeline + per-seller price series and [\"bsr_history\"] the per-category BSR rank history (Amazon only, included in the row price - no extra credits); [\"history_only\"] returns only the stored series per row at 0.05 credit (Amazon only, stored data, any age; the batch runs as cache). Search batches: [\"blocks\"] attaches the paid-placement blocks (ad_blocks/video_blocks/brand_stores — page-1-only by nature, free). Off by default; CSV columns unaffected."},"history_sellers":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"History Sellers","description":"With include offer_history: sellers carrying a point series per row (default 10, max 50); every observed seller is listed regardless.","default":10},"history_points":{"type":"integer","maximum":20000.0,"minimum":1.0,"title":"History Points","description":"With include offer_history: points per series - the most recent observed days (default 500, max 20,000). Wider series are included too - no extra credits.","default":500}},"additionalProperties":false,"type":"object","required":["name","country"],"title":"BatchCreateRequest"},"BatchEstimateRequest":{"properties":{"kind":{"type":"string","pattern":"^(product|search|seller|brand|category|keywords|bestsellers|brand_network|brand_sellers|brands_movers|brands_top|categories|categories_top|category_search|deals|keyword_rankings|keywords_compare|offers|product_keywords|seller_brands|seller_network|seller_products|sellers_movers|sellers_top|shopping|warehouse_search)$","title":"Kind","description":"product (default): a list of ASINs served like /v1/product. search: a list of search TERMS served like /v1/serp — always live, Amazon marketplaces only. seller / brand / category / keywords (paid plans): a list of seller ids / brand names / category ids / seed terms served like /v1/seller, /v1/brand, /v1/category and /v1/keywords. Every other endpoint (2026-10-12): shopping (/v1/shopping, terms), warehouse_search (/v1/search, terms), bestsellers (/v1/bestsellers, urls), offers (/v1/offers, asins), deals (/v1/deals, category_ids = deals department ids or all), seller_products / seller_brands / seller_network (seller_ids), brand_sellers / brand_network (brands), keywords_compare (seeds), categories (category_ids = parent ids or root), category_search (terms) and the ranked lists brands_top / brands_movers / sellers_top / sellers_movers / categories_top (no list - pages); the endpoint's query parameters go in `params`.","default":"product"},"asins":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Asins","description":"Product batches: ASINs (10-char) — or numeric item IDs for country=walmart."},"gtins":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Gtins","description":"Product batches, instead of asins (2026-10-12): barcodes (UPC / EAN / GTIN / ISBN-13; 8, 12, 13 or 14 digits). Each resolves like /v1/product?gtin= - our observed listings, a book's ISBN-10, the same product on another Amazon marketplace, and in mode auto / live one Amazon search per barcode we cannot place; every row says how (gtin_resolution). Unresolvable barcodes are never billed."},"source":{"anyOf":[{"type":"string","pattern":"^(tracked)$"},{"type":"null"}],"title":"Source","description":"Product batches (2026-10-14): tracked = run over every ASIN this key is tracking on the batch's marketplace (POST /v1/track, GET /v1/product?track=true) instead of an asins list - typically with include [\"history_only\"], the 0.05-credit daily series pull. Amazon only."},"terms":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Terms","description":"Search batches: the search terms (one live Amazon SERP fetch per term per page). shopping / warehouse_search: the queries (one /v1/shopping or /v1/search call each). category_search: category names."},"seller_ids":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Seller Ids","description":"seller / seller_products / seller_brands / seller_network batches: Amazon seller ids (A + 8-24 letters/digits)."},"brands":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Brands","description":"brand / brand_sellers / brand_network batches: brand names as Amazon prints them (case-insensitive)."},"category_ids":{"anyOf":[{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","minItems":1},{"type":"null"}],"title":"Category Ids","description":"category batches: the warehouse's category ids (list them with /v1/categories or /v1/categories/search). categories batches: parent ids, or root for the top level. deals batches: deals department ids (categories[] of a /v1/deals answer), or all for the whole deals page."},"seeds":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Seeds","description":"keywords / keywords_compare batches: seed terms or prefixes (3-120 characters) served like /v1/keywords or /v1/keywords/compare."},"pages":{"anyOf":[{"type":"integer","maximum":40.0,"minimum":1.0},{"type":"null"}],"title":"Pages","description":"Search batches: pages fetched per term (1-3, default 1), billed per page ACTUALLY fetched. Ranked-list batches (brands_top, brands_movers, sellers_top, sellers_movers, categories_top): how many pages of 25 rows to take (1-40, default 1) - one result row per page."},"urls":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Urls","description":"Best Sellers batches: Amazon Best Sellers URLs (a category or a marketplace root), one per line, all on the batch's marketplace."},"params":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Params","description":"Endpoint batches: the query parameters of the endpoint the batch runs, fixed for every row (e.g. shopping {\"limit\": 50, \"detail\": true}, bestsellers {\"pages\": 1}, brands_top {\"sort\": \"revenue\"}). Validated like the endpoint's own parameters; unknown names are a 422."},"country":{"type":"string","title":"Country","description":"us, uk, de, ca, au, fr, it, es, jp, mx, br, walmart","default":"us"},"mode":{"anyOf":[{"type":"string","pattern":"^(cache|live|auto)$"},{"type":"null"}],"title":"Mode","description":"Product and seller batches (default auto); seller_products batches: cache (default) or live. Every other kind is served the way its endpoint serves it - sending a mode there is a 422."},"max_age_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Max Age Days","default":30},"include":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Include","description":"Optional extras: [\"history\"] (seller / brand / category batches) attaches the endpoint's history block at +0.5 per row when it comes back; [\"reviews\"] (product batches) adds the featured-review set to each JSONL row (free); [\"used\"] (product batches) adds the used / refurbished / open-box / collectible offers to current_sellers and, with offer_history, the per-condition series (free, 2026-09-28); [\"offer_history\"] / [\"bsr_history\"] (product batches, Amazon only) attach the history blocks to each JSONL row, included in the row price (no extra credits); [\"history_only\"] (product batches, Amazon only) returns ONLY the stored series per row (bsr_history + offer_history + buybox_price_history) at 0.05 credit, any age, stored data only - the batch runs as cache; [\"blocks\"] (search batches) adds ad_blocks/video_blocks/brand_stores (free)."},"history_sellers":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"History Sellers","description":"With include offer_history: sellers carrying a point series per row (default 10, max 50).","default":10},"history_points":{"type":"integer","maximum":20000.0,"minimum":1.0,"title":"History Points","description":"With include offer_history: points per series (most recent observed days; default 500, max 20,000). Wider series are included too - no extra credits.","default":500}},"additionalProperties":false,"type":"object","title":"BatchEstimateRequest"},"BatchUpdateRequest":{"properties":{"mode":{"anyOf":[{"type":"string","pattern":"^(cache|live|auto)$"},{"type":"null"}],"title":"Mode","description":"cache = warehouse only; live = scrape every row; auto = warehouse when fresh enough, scrape the rest. Walmart: cache/auto only (422 on live). seller_products batches: cache or live. Kinds without a mode: 422."},"max_age_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Max Age Days"}},"additionalProperties":false,"type":"object","title":"BatchUpdateRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Marketplace":{"type":"string","enum":["amazon-us","amazon-uk","amazon-de","amazon-ca","amazon-au","amazon-fr","amazon-it","amazon-es","amazon-jp","amazon-mx","amazon-br","walmart"],"title":"Marketplace"},"ProductRow":{"properties":{"asin":{"type":"string","title":"Asin"},"product_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Id"},"product_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Url"},"marketplace":{"type":"string","title":"Marketplace"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Price"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency"},"bsr":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bsr"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"reviews_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reviews Count"},"seller_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seller Count"},"buybox_seller":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buybox Seller"},"buybox_seller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Buybox Seller Id"},"fba":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Fba"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fulfillment"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image"},"review_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Review Count"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"is_fba":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Fba"},"in_stock":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"In Stock"},"bought_past_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bought Past Month"},"sales_estimate":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sales Estimate"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of"}},"type":"object","required":["asin","marketplace"],"title":"ProductRow"},"ScheduleRequest":{"properties":{"schedule":{"type":"string","pattern":"^(none|daily|weekly|monthly)$","title":"Schedule"},"enabled":{"type":"boolean","title":"Enabled","description":"Disable without deleting the batch (R3).","default":true},"credit_ceiling":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Credit Ceiling","description":"A scheduled firing whose fresh estimate exceeds this does not run — you get an email instead (G2). Default: 2x the estimate at schedule-set time."},"webhook_url":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"title":"Webhook Url","description":"POSTed on run completion/pause, HMAC-SHA256 signed (X-Logimu-Signature: sha256=<hex>). The signing secret is returned ONCE in this response — store it."}},"additionalProperties":false,"type":"object","required":["schedule"],"title":"ScheduleRequest"},"SearchResponse":{"properties":{"source":{"type":"string","title":"Source","default":"db"},"marketplace":{"type":"string","title":"Marketplace"},"limit":{"type":"integer","title":"Limit"},"returned":{"type":"integer","title":"Returned"},"total_matched":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Matched"},"credits_charged":{"type":"number","title":"Credits Charged"},"credits_remaining":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Credits Remaining"},"dropped_terms":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Dropped Terms"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"},"seller_ratings":{"anyOf":[{"items":{"$ref":"#/components/schemas/SellerRating"},"type":"array"},{"type":"null"}],"title":"Seller Ratings"},"products":{"items":{"$ref":"#/components/schemas/ProductRow"},"type":"array","title":"Products"}},"type":"object","required":["marketplace","limit","returned","credits_charged","products"],"title":"SearchResponse"},"SellerRating":{"properties":{"seller":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seller"},"seller_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Seller Id"},"seller_positive_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Seller Positive Pct"},"seller_feedback_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seller Feedback Count"},"seller_rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Seller Rating"},"observed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Observed At"}},"type":"object","title":"SellerRating","description":"Seller feedback as last observed on the marketplace (nightly MV mv_seller_rating_current;\nNick 2026-09-18). One entry per seller named anywhere in the response; Amazon's own offers\ncarry no feedback. `observed_at` = the observation the values come from."},"SortField":{"type":"string","enum":["rating","reviews","bsr","price","sales_estimate","seller_count"],"title":"SortField"},"TrackRequest":{"properties":{"asin":{"anyOf":[{"type":"string","maxLength":10,"minLength":10},{"type":"null"}],"title":"Asin","description":"The product's 10-character Amazon ASIN. Or give a list: items / asins (P87, 2026-10-14)."},"items":{"anyOf":[{"items":{"anyOf":[{"type":"object"},{"type":"string"}]},"type":"array","maxItems":1000},{"type":"null"}],"title":"Items","description":"Bulk (2026-10-14): up to 1,000 trackings in one call, each an object {asin, country?, interval?, ttl_days?, notify_if?, webhook_url?, alert_email?} or just the ASIN string; the top-level fields are the defaults for every item. results[] comes back in input order with created / renewed / refused / invalid per item; the allowance is consumed in input order and the call is never all-or-nothing."},"asins":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":1000},{"type":"null"}],"title":"Asins","description":"Bulk shorthand: a list of ASINs, all with the top-level fields."},"country":{"type":"string","title":"Country","description":"Amazon marketplace: us, uk, de, ca, au, fr, it, es, jp, mx, br (amazon-xx accepted). Amazon only - no Walmart.","default":"us"},"interval":{"type":"string","title":"Interval","description":"How often the lane re-reads the all-offers page: 1h, 2h, 4h (default), 12h or 24h. A shorter interval draws more of the daily allowance (1h = 24 snapshots a day, 2h = 12, 4h = 6, 12h = 2, 24h = 1).","default":"4h"},"ttl_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":0.0},{"type":"null"}],"title":"Ttl Days","description":"Optional: stop after this many days (1-365). Omit (or 0) and the tracking runs for as long as the plan is active; a lapsed plan keeps it 7 days, then it pauses and resumes with the plan."},"alert_email":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"null"}],"title":"Alert Email","description":"Optional (2026-10-14): e-mail alerts for the notify_if thresholds - true for the account's own address, or an address. One e-mail per event, at most 50 a day per tracking, from noreply@logimu.com. false (or \"\") detaches; omit to keep. Works with or without webhook_url."},"webhook_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Webhook Url","description":"Optional (2026-10-14): an https URL we POST to when a notify_if threshold fires on a new observation of the product (signed X-Logimu-Signature: sha256=HMAC-SHA256(secret, raw_body); the secret is returned once). Send an empty string to detach; omit to keep."},"notify_if":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Notify If","description":"With webhook_url: the thresholds - price_below, price_above (a price), price_change_pct (a percent move since the previous observation), buybox_seller_change (true), offer_count_below / offer_count_above (a count), availability_change (true). {} attaches the webhook and fires on nothing."}},"additionalProperties":false,"type":"object","title":"TrackRequest"},"TrackStopRequest":{"properties":{"ids":{"anyOf":[{"items":{"type":"integer"},"type":"array","maxItems":1000},{"type":"null"}],"title":"Ids","description":"Tracking ids to stop (from GET /v1/track)."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"With asins: the marketplace (us, uk, de, ...)."},"asins":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":1000},{"type":"null"}],"title":"Asins","description":"With country: the ASINs to stop."}},"additionalProperties":false,"type":"object","title":"TrackStopRequest"},"TrackSyncRequest":{"properties":{"country":{"type":"string","title":"Country","description":"The marketplace whose active set becomes the list.","default":"us"},"asins":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Asins","description":"The full list (up to 1,000): missing ones are created, active ones not listed are stopped, the rest are left as they are (interval and alerts unchanged)."},"interval":{"type":"string","title":"Interval","description":"For the trackings this call creates.","default":"4h"},"ttl_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":0.0},{"type":"null"}],"title":"Ttl Days"},"alert_email":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"null"}],"title":"Alert Email"},"webhook_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Webhook Url"},"notify_if":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Notify If"},"dry_run":{"type":"boolean","title":"Dry Run","description":"true returns what would be created and stopped without writing.","default":false}},"additionalProperties":false,"type":"object","required":["asins"],"title":"TrackSyncRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}