Amazon advertising console — Sponsored Products + Sponsored Brands + Sponsored Brands Video + Sponsored Display — at the AD PRODUCT / PORTFOLIO / CAMPAIGN / AD GROUP / KEYWORD grain, the same pipeline as the app's PPC page. Answers: which keywords or campaigns waste spend (high spend, low sales, high acos), where to cut or raise bids, which keyword drives sales on a given ASIN/SKU, which placement (top of search vs product pages) the money goes to, where the money goes across ad products. groupBy takes the ad product (adProduct), an ad-structure grain (portfolio, campaign, adGroup, targetingType, targetingDetail, keyword), the placement grain, a product grain (childAsin, sku), or a TIME grain (day/week/month/quarter/year) for a series in ONE call. adProduct, portfolio and placement need the stacked-cut ads fact: where it is not enabled yet the call is refused with a message naming ADS_FACT_ENABLED, so try them and read the answer rather than assuming. Keyword rows carry BOTH bids: bid is the target's current setting (falling back to the ad group default) and reportedBid is the bid Amazon reported on the last day of the window. Metric keys are a SEPARATE universe from list_metrics — use ONLY: spend, sales, sales14d, impressions, clicks, orders, units, units14d, acos, roas, cpc, ctr, cvr, marginBeforeAds, breakEvenAcos, profitAfterAds, spendWithoutSales, newToBrandOrders, newToBrandSales, newToBrandUnits, videoCompleteViews, viewableImpressions, brandedSearches, topOfSearchImpressionShare. 🏷️ THE BRAND KEYS (2026-09-17) are what only the Sponsored Brands / Brands Video / Display reports publish: newToBrandOrders / newToBrandSales / newToBrandUnits (14-day, click-attributed), videoCompleteViews (video rows only), viewableImpressions, brandedSearches; and topOfSearchImpressionShare, the share of top-of-search impressions the TARGET won (0-100, impression-weighted when rows are grouped): Sponsored Brands / Brands Video at any grain, and Sponsored Products at a TARGET grain only (groupBy keyword / targetingType / targetingDetail), from September 2026 (earlier days are null). ⚠️ It is NOT the console's 'IS | IR' (search-term impression share and rank): those ride on the KEYWORD rows as attributes, attrs.searchTermImpressionShare (0-100) and attrs.searchTermImpressionRank (1 = first), Amazon's numbers per account × marketplace × keyword TEXT over a rolling 30 days ending on attrs.searchTermImpressionAsOf (the latest daily snapshot, from 2026-09-18), independent of the period and NOT additive: never sum or average them; Sponsored Products keywords only, null on product targets and on every other ad product. Sponsored Products publishes none of the other six: with adProducts limited to sponsored_products (the default) they come back null on every row with an unservedMetrics note, never a 0 — pass the other ad products to read them; topOfSearchImpressionShare gets the same note when Sponsored Products is asked at a grain that is not a target grain. 💰 THE PROFIT KEYS answer 'is this advertising actually making money': marginBeforeAds is the P&L's Margin before Ads of the advertised products (exact per ASIN and marketplace, ad-sales-weighted elsewhere), breakEvenAcos is the same number read against ACOS (spending above it loses money), profitAfterAds is (margin x ad sales) - ad spend, and spendWithoutSales is the spend on TARGETS with zero attributed sales over the whole period (not per day). Asking for any of them joins the P&L and resolves the attributed target_asin cut, so spend/sales on those rows become the attributed estimate rather than the exact advertised reading (it re-sums within 0.01%); omit them for the exact reading. They cannot be combined with the placement grain or a search-term filter (neither carries an ASIN or a target) and the call is refused with a message saying so. They are Sponsored Products / Sponsored Display keys: with sponsored_brands or sponsored_brands_video in adProducts they come back null on every row with an unservedMetrics note (per-ASIN Sponsored Brands is an allocation — query_metrics serves it), never a refusal; likewise the margin keys at a target grain with sponsored_display (no SD target → ASIN attribution). Sponsored Brands has no advertised-product report either, so childAsin / sku / parentAsin / tags with it are refused by name. ⚠️ Never sum or compare these with query_metrics' ad metrics (adSpend & co cover SP+SD+SB allocated to products, over the full history) — totals legitimately differ. ⚠️ Placement rows cannot be combined with a keyword or product dimension (Amazon reports placement per campaign only); such a combination is refused rather than silently emptied. Returns rows with value, comparison value and variance, plus the reporting currency. 🧭 AD PRODUCTS: the console serves Sponsored Products, Sponsored Brands, Sponsored Brands Video and Sponsored Display as DISJOINT blocks of rows — adProducts picks which (default ['sponsored_products'] until the fact serves the others; pass several to read them in ONE call, or groupBy='adProduct' to split the money by product). Each block is read from its own cut of the fact at its OWN attribution window: SP orders/sales/units are 7-day on a Seller Central account and 14-day on a Vendor Central account (each console's own window), SB and SBV 14-day, SD 14-day CLICK-attributed (view-attributed SD conversions are never included) — so never sum or compare sales, orders, ACOS or ROAS across products; spend is the ONE additive column across all four, sponsored_brands + sponsored_brands_video (one report, split per row) the ONE additive pair, and sales14d / units14d the like-for-like 14-day reading. Sponsored Display has no search-term and no placement report (such a call is refused by name). Entity rows carry attrs.adProduct; it is null on a VALUE row (an ASIN, a placement, a targeting type, a search term) that folds two products. ⏳ HISTORY & ROUTING: this console route is built on Amazon's per-product advertising reports, so EACH AD PRODUCT HAS ITS OWN HISTORY FLOOR — the response's historyStartsAtByProduct is the first day held per product for the queried accounts (Sponsored Products ~95 days of report retention, Sponsored Brands / Brands Video 60 days, Sponsored Display 65–95 days; all backfilled ~60 days before the account's Ads connection), and historyStartsAt is the earliest floor among the products you queried. Nothing before a product's floor is served for it (null, never zero spend). For ad TOTALS by account, product or period, and for ANY year-over-year or long-history comparison that needs no ad-product / portfolio / campaign / ad group / keyword / search-term / placement breakdown, use query_metrics instead (adSpend, sponsoredSales, organicSales, sponsoredAcos, sponsoredRoas, sponsoredTacos, impressions, clicks, costPerClick, clickThroughRate): it carries the whole ads history Nova holds for each account (from ~60 days before its Ads connection, complete from there; adsHistory gives the first day when a period starts earlier), Sponsored Products + Display + Brands allocated to products. routingNotice, when present, says which route to prefer and where this one's history starts — relay its history part to the user whenever a requested period precedes a queried product's floor. 💱 CURRENCY: monetary values are served in the caller's Nova display currency when it is one of the organization's configured currencies (its primary or up to four secondary currencies), else in the organization's primary. In the response, currency is the code, currencyBasis says why (user_preference | organization | pinned) and currencyNotice, when present, MUST be relayed to the user. Quote the code; never assume a symbol from the marketplace. Pass currency to pin any configured code — e.g. to reproduce a figure the seller read on a dashboard set to another currency.