query_advertising
Amazon advertising console — Sponsored Products + Sponsored Brands + Sponsored Brands Video + Sponsored Display + Full-Funnel campaigns — 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. 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), under the organization's saved P&L rules and its own costs as the app's P&L page shows it (the answer then carries pnlRules and pnlRulesNote, to relay once), 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, sponsored_brands_video or full_funnel in adProducts they come back null on every row with an unservedMetrics note (per-ASIN Sponsored Brands is an allocation — query_metrics serves it; a Full-Funnel campaign's sales cover the whole brand), 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, Sponsored Display and Full-Funnel campaigns 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 after a click OR a view, as Amazon's console counts them (the *14d metrics keep the clicks alone) — so never sum or compare sales, orders, ACOS or ROAS across products; spend is the ONE additive column across all of them, 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. 🎯 FULL-FUNNEL ('full_funnel'): Amazon's Full-Funnel campaigns, ONE campaign serving on Amazon, off Amazon and on streaming video. Read them in total, over time, by campaign, or by product (childAsin / sku / parentAsin: the spend Amazon reports on no product, streaming video mostly, is one row with no ASIN, so the products re-sum to the campaign). They have no ad group, no keyword or target, no search term and no placement of this console: those grains and filters are refused by name. Their sales / orders / units are EVERY sale Amazon attributes to the campaign, the promoted products and the rest of the brand together, at a window Amazon does not state; sales14d / units14d, the profit keys, newToBrandUnits, viewableImpressions, brandedSearches and topOfSearchImpressionShare come back null with an unservedMetrics note, while newToBrandOrders, newToBrandSales and videoCompleteViews are served. A campaign Amazon's weekly report has not named yet reads its id without a name, and their current day is as of Nova's last hourly build, not the live stream. The P&L counts the same campaigns' cost as fullFunnelCost (query_metrics), where the part on no product is shared among the campaign's 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; Full-Funnel from the first day Amazon's Full-Funnel report or its ads spend stream delivered for the account), 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, plus the Full-Funnel campaigns. 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. 🕒 CURRENT DAY: on Seller Central accounts the current day is served live, from Amazon's hourly advertising stream, through the last hour Amazon has finished delivering (an hour that ended 45 minutes to two hours ago; the hour being delivered is left out, it holds its spend before its sales): all four ad products at the total, time, adProduct, portfolio and campaign grains, and Sponsored Products / Sponsored Display at the adGroup, childAsin and sku grains too. Attributed orders and sales of a recent day keep growing as Amazon attributes them. The keyword / targetingType / targetingDetail and placement grains, and Vendor Central accounts, follow Amazon's reports instead: their current day arrives hours later and can read lower than the live total — say so, never sum the two, and read a current-day total at a grain that is served live. ⏱ INTRADAY: the smallest grain of this tool is the DAY, and the current day is partial until it ends — its total against a whole earlier day is not a like-for-like comparison. For today by the hour, today against another day at the same time of day, the campaigns out of budget right now or the latest orders, use query_live. TODAY as this tool reads it: each marketplace on its own day; the orders within about a minute; the ad figures of an account through the last hour Amazon has finished delivering to THAT account, 45 minutes to two hours behind the clock — so today's TACOS and profit set sales to the minute against ad spend an hour behind, and are provisional. query_live reads today on ONE clock and holds an hour for every account once the first has it: over several time zones or several accounts its total for today can differ from this tool's, and neither is wrong. 💱 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"metrics": "<metrics>",
"from": "<from>",
"to": "<to>"
},
"name": "query_advertising"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Period end, INCLUSIVE (YYYY-MM-DD): a calendar month is from=YYYY-MM-01 to=its LAST day. to=the 1st of the next month adds one extra day to every total (and one extra bucket with a time grain). | |
| from | Yes | Period start, INCLUSIVE (YYYY-MM-DD). | |
| skus | No | Attributed product SKUs. | |
| tags | No | "Your Filters" tag IDS from list_tags — a tag NAME is rejected. | |
| limit | No | Rows per call of an entity grouping, 1 to 1000 (default 50). A time grain is never cut: its series comes whole, in date order, 1000 buckets at most. | |
| reason | No | One sentence, ALWAYS IN ENGLISH (regardless of the conversation language), on WHY you are making this call — the user question or your analytical goal. Recorded so the seller can see how their data is used. | |
| sortBy | No | ADS metric key to rank rows by (e.g. "spend"). Refused with a time grain: a series comes in date order. | |
| groupBy | No | Ad product (adProduct), ad-structure grain (portfolio/campaign/adGroup/targetingType/targetingDetail/keyword), placement, product grain (childAsin/sku), or time grain. Omit for a single total row. | |
| metrics | Yes | ADS metric keys (spend, sales, acos, roas, marginBeforeAds, breakEvenAcos, profitAfterAds, spendWithoutSales, newToBrandSales, viewableImpressions, topOfSearchImpressionShare, …) — NOT product keys from list_metrics. | |
| accounts | No | Restrict to a subset of your own seller account IDs (from list_accounts). Omit to include all your accounts. A brand/account name is accepted and resolved to its id when it matches one of your accounts unambiguously; a label that carries the id ("Brand (A1B2C3D4E5F6G)") resolves to that id. | |
| channels | No | ONE Amazon programme per call. 'SELLER' = Seller Central (3P) advertising: the seller's own Amazon Ads campaigns. 'VENDOR' = Vendor Central (1P) advertising: the campaigns of the vendor's own Amazon Ads profile. Omit = SELLER whenever the accounts of the call include a Seller Central account, else VENDOR. Pass ['VENDOR'] only when the user asks about Vendor Central / 1P advertising. Both at once is refused: 3P and 1P spend and sales are never added into one total. On a Vendor Central read the margin keys (marginBeforeAds, breakEvenAcos, profitAfterAds) come back null with an `unservedMetrics` note: Amazon attributes 1P ad sales at its retail price, while the vendor's margin is earned on what Amazon pays it. | |
| currency | No | Pin the reporting currency: one of the organization's configured codes — its primary or any of its secondary currencies (e.g. "USD"). Omit to follow the caller's Nova display currency, the dashboard's rule. Any other code is refused. | |
| sortField | No | What to rank on: 'value' (default), or 'variance' / 'variancePercentage' (need a comparison period). | |
| sortOrder | No | desc (default) = biggest first. | |
| adGroupIds | No | ||
| adProducts | No | Which ad products to read, as disjoint blocks: sponsored_products, sponsored_brands, sponsored_brands_video, sponsored_display, full_funnel (Amazon's Full-Funnel campaigns: by campaign or by product only). Default ['sponsored_products'] until the fact serves the others. Each has its own attribution window and history floor — see the AD PRODUCTS note. | |
| childAsins | No | Attributed child ASINs. | |
| keywordIds | No | ||
| placements | No | Normalized placement buckets. Only answerable on the placement cut (no keyword/product dimension alongside). | |
| campaignIds | No | ||
| parentAsins | No | Family keys — resolved to child ASINs server-side. | |
| comparisonTo | No | Baseline period end (inclusive). | |
| marketplaces | No | Marketplace IDs. | |
| portfolioIds | No | Portfolio ids as returned by groupBy="portfolio". "0" is the campaigns-in-no-portfolio bucket. | |
| metricFilters | No | Server-side threshold filters (ANDed) on ADS metrics — e.g. spend > 100 AND sales < 1 for wasted spend. Needs an ads entity grouping. | |
| comparisonFrom | No | Baseline period start (inclusive) — enables variance. | |
| targetingTypes | No | e.g. keyword, auto, product, category. | |
| targetingDetails | No | Match types (exact/phrase/broad) or auto groups (close-match/loose-match/complements/substitutes). | |
| excludeUnfinished | No | Exclude the current, still-incomplete period so a partial day/week/month is not read as a drop. |