query_live
The CURRENT DAY as it happens — Nova's Live page: today's sales and ad spend HOUR BY HOUR, against a comparison day cut AT THE SAME TIME of day, the products and the campaigns that move, the campaigns out of budget, and the latest orders. Seller Central accounts. Use THIS tool when the question is about the pace of today, an hour of today, "right now", "so far today against yesterday at this time", a budget running out, or the last orders. view picks the read: "sales" = today's sales, units and orders, in total and by hour; "ads" = today's ad spend, clicks, impressions, attributed sales and orders, in total and by hour, with ACOS and TACOS (the sponsored ads of Amazon's hourly stream: Sponsored Products, Display and Brands, and the Full-Funnel campaigns, whose attributed sales are every sale Amazon attributes to the campaign, as the P&L's sponsored totals count them); "products" = the table of the products (or accounts, or marketplaces) by sales today, each against the comparison at the same time, with its change and its rank; "campaigns" = the table of the campaigns (or portfolios, or products) by ad spend today, each campaign with its daily budget, the share of it Amazon says is spent (campaign.budgetUsage.percent, null on a Full-Funnel campaign) and its portfolio's cap — budgetAlert: true returns only the campaigns out of budget or past 80 % of it; "orders" = the latest order lines, newest first, each with its product's name; "promotions" = how many PRODUCTS a promotion runs on right now, in two families as the page's two cards count them: Amazon deals and price discounts (the discount is in the price; with the products one starts on within 24 hours), and coupons and the seller's own promotions (the customer redeems them; with the products a deal or a price discount also runs on, and the promotions on the whole catalogue counted apart, since they name no product). For the coupons' family it also gives today's units of those products hour by hour and the units sold WITH the coupon or the promotion redeemed (redeemed), read on the order report: redeemed.through is where that report stops (about an hour behind the orders), redeemed.share is the redeemed units over the units the report holds to that same point (unitsSoldThrough), never over unitsSold to now; the redeemed units are a floor (a coupon on a Subscribe & Save delivery leaves no trace on the line). For the deals' family, dealsAndPriceDiscounts.today tells what the deals changed today, on the products that can be COMPARED only (productsCompared; unitsShareCompared is their share of the units every product in a deal sold today, and rule says what makes a product comparable): sales is what they sold today, salesAtUsualPrice the same units at each product's usual price, so discountGiven is the discount in the price; referenceDay.salesBySameTime is what an average day WITHOUT a deal or a price discount on the product sold by the same time (the product's own such days over the eight weeks before), so extraSales, salesRatio and unitsRatio are the uplift. It stops at through too, and it is a total over the products compared: never read it per product, and never as profit (no cost is in it). A coupon is no deal: a product under a coupon today and on its reference days carries it on both sides. registryLastReadAt is when Amazon's promotions registry was last read (every six hours). The promotions one by one, with their dates and terms: query_promotions. 🕒 ONE CLOCK: "today" is the calendar day on ONE clock — clock.timezone, the time zone of clock.marketplaceId (by default the marketplace with the most sales in scope; clockMarketplace names another). Every marketplace of the scope is read on that clock. query_metrics and query_advertising cut the day of each marketplace on its own clock: over several marketplaces their total for "today" is NOT this one. Quote a figure with its clock (clock.nowLocal) and never reconcile the two. 📊 COMPARISON: comparison.atSameTime is the comparison day cut at the same time of day — the figure to set today against; comparison.wholeDay is that day in full. change and every changePct are today against the same time; changePct is a RATIO (0.12 = +12 %), null when the comparison is 0. When change is null, changeNote says why: relay it, never compute a change yourself. hours is the day hour by hour on the clock (hour 0 = 00:00 to 00:59): today is null for an hour that has not started, and the hour in progress is partial. ⏱ FRESHNESS: an order arrives within about a minute; a recent line is priced by estimate until Amazon's report confirms it (isProvisional on a line, today.liveLines on the day). The ads are read through the last hour Amazon has finished delivering, through on the clock (the ads view) — an hour that ended 45 minutes to two hours ago, the same hour as the page's PPC tile, the P&L and query_advertising: the hour being delivered holds a part of its spend and not yet its sales, so it is left out; through is the END of the last hour read (through 04:00 = the hours 00:00 to 03:59, spelled in covers; the hour starting at 04:00 is not in the figures); it is null, with throughNote, while no hour of today is whole. acos and tacos are RATIOS (0.069 = 6.9 %) at that same cut, today and the comparison: ACOS is the spend over the sales Amazon attributes to the ads, TACOS the spend over the TOTAL sales (tacos.totalSales, the orders cut at through). tacos.comparison is null, with tacos.comparisonNote, when the ads and the orders do not hold the same days of the comparison (an hourly ad history that starts inside the days compared with): relay the note, never divide the two yourself. Quote these; never divide this view's spend by the sales of the sales view, which run to the minute: that TACOS is too low. Over SEVERAL ACCOUNTS this tool holds an hour for every account once Amazon has finished delivering it to the first, while query_metrics and query_advertising wait for each account's own delivery: for about ten minutes of an hour their total for today can be lower than this one. Both are right: say which tool a figure comes from, and never reconcile the two. freshness.latestHourReceivedAt is the latest hour Nova holds, which can still be in delivery: the figures stop at through, not there. Attributed ad sales keep growing for days. A campaign's budget figures (campaign.budgetAmount, budgetDay, budgetUsage, portfolioCap) are in the campaign's own currency, named beside them, never converted, on the campaign's own Amazon day. ↪ ROUTING: this tool reads TODAY only, as the Live page shows it. For today's total as the P&L and the Advertising page show it (each marketplace on its own day), for a day that is over or for a period of days, use query_metrics or query_advertising. 💱 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": {
"view": "<view>"
},
"name": "query_live"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| skus | No | ||
| tags | No | "Your Filters" tag IDS from list_tags (manual custom tags or predefined segmentations, Brand included) — a tag NAME is rejected. | |
| view | Yes | The read: "sales", "ads", "products", "campaigns", "orders" or "promotions". | |
| limit | No | Rows of a table or lines of the orders feed, 1 to 100 (default 20). A table's `keys` says how many rows exist and `totals` sums them all. | |
| 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 | The order of a table: "current" (default; the sales of a product, the spend of a campaign, today), "comparison", "change" (the movers) or "changePct". | |
| compare | No | The comparison day, cut at the same time of day: "yesterday" (default; the day before), "last-week" (the same weekday a week before), "two-weeks-ago" or "last-year" (the same date a year before). The answer names the day compared with in `comparison.dates`: check it. Not with view="orders" or view="promotions". | |
| groupBy | No | The rows of a table. view="products": sellerAccount, marketplace, parentAsin, childAsin (default) or sku. view="campaigns": campaign (default), portfolio, or the same five. | |
| 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. | |
| 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. | |
| sortOrder | No | Default "desc". | |
| childAsins | No | ||
| budgetAlert | No | view="campaigns" only: true returns every campaign out of budget or past 80 % of its budget, and no other. | |
| parentAsins | No | ||
| compareDates | No | Instead of `compare`: one day before today (YYYY-MM-DD, on the clock), or 2 to 8 days averaged hour by hour ("the last four Mondays"). | |
| marketplaces | No | Marketplaces to read: country codes (US, DE), domains (amazon.de) or marketplace ids. Omit for every marketplace of the accounts. | |
| clockMarketplace | No | The marketplace whose time zone is the clock of "today" (a country code, a domain or an id). Omit for the marketplace with the most sales in scope. |