AMAZON DSP: the seller's Amazon DSP (Demand-Side Platform) advertising, Amazon's PROGRAMMATIC display and video ads bought in the DSP console: banners and video on Amazon's own sites and devices (its stores, Fire TV, Twitch...) and on third-party sites and apps, bought by audience rather than by keyword and billed per line item. It is NOT Sponsored ads: Sponsored Products / Brands / Display are the search-and-browse PPC that query_advertising serves. Separate budgets, separate consoles, separate attribution: a DSP conversion is counted post-click AND post-view over 14 days (a shopper who saw the ad and bought later counts), where PPC conversions are click-attributed. So NEVER add DSP spend to PPC spend, never add DSP sales to PPC sales, never compute one ACOS or ROAS across the two, and never compare a DSP ROAS with a PPC ROAS. In the app, the Advertising filter has three channels read side by side, PPC, Creator Connections and DSP; the P&L line 'Amazon DSP' (dspCost, under Advertising Cost) is this spend allocated to products, which query_metrics serves. Use query_dsp for anything about the DSP: what it costs, what it drives, which advertiser / order / line item / product / inventory / device / creative / audience / country, whether a line item is running; use query_advertising for Sponsored ads, query_metrics for advertising totals in the P&L. WHO IS READ: the DSP advertisers LINKED to the accounts of this call (Nova links each DSP advertiser to one of the seller's accounts, Seller Central or Vendor Central); `accounts` narrows them. History: Amazon's DSP reports reach back about 95 days, so an advertiser's figures start about 95 days before its connection to Nova; an earlier period comes back empty, never as zero spend. When no DSP advertiser is linked to the accounts, the answer says so (`dspAdvertisers: 0`, a `notice`, no rows): it is not an error, the seller does not run Amazon DSP through Nova. `level` (REQUIRED) picks the row: 'advertiser' (one per linked DSP advertiser), 'order' (a DSP campaign, with its budget, flight dates, pacing and Amazon's reach to date, household reach and frequency in attrs, as of the latest closed month), 'lineItem' (the grain Amazon bills, with its current status, type, budget and flight dates), 'product' (per ASIN, conversions only: Amazon reports no cost per ASIN), 'supplyFamily' and 'supplySource' (where the ads ran), 'device' (the screen), 'creative' (the ad asset), 'audience' (the segments reached: NOT additive, segments overlap), 'country' (where the ads served; the row with id '' is Unattributed). Each level is one of Amazon's DSP reports with its own metric universe, and the answer's `levelNote` says in one sentence what its rows are and what may be added across them: relay it whenever it qualifies the figures. Start at 'advertiser' or 'lineItem' for totals (no time grain here: a trend is several periods, one call each); the partitions (supply, device, creative, country) re-add to the line items; 'audience' is read beside them, never summed. Rows come biggest first on the first metric of the call unless `sortBy` says otherwise, and a row stays while it spent or sold over the period (sold, at 'product'), whatever `metrics` asks: the page's own population. METRICS are a SEPARATE universe from list_metrics and from query_advertising (same spellings, different meanings): spend (the total cost: supply cost plus every fee), supplyCost, fees, audienceFee, consoleFee, agencyFee, thirdPartyFees, impressions, viewableImpressions, viewabilityRate, clicks, ctr, ecpm, detailPageViews, dpvr, ecpdpv, addToCart, addToCartViews, addToCartClicks, atcr, purchases, unitsSold, sales (the PROMOTED products' conversions), totalPurchases, totalUnitsSold, totalSales (the promoted products plus the brand halo), purchaseRate, ecpp, newToBrandPurchases, newToBrandUnitsSold, newToBrandSales, newToBrandShare, totalNewToBrandPurchases, totalNewToBrandUnitsSold, totalNewToBrandShare, roas (promoted sales over spend), totalRoas (total sales over spend). Each level serves the subset its report carries: a key outside it is refused with the keys the level serves (no spend, impressions or ROAS at 'product'; no sales, units or halo at 'audience'; newToBrandSales and the four fee lines read on the 'advertiser', 'order' and 'lineItem' levels, the other reports carry fewer of them). Omit `metrics` for the level's core: spend, impressions, clicks, purchases, sales, totalSales, roas (the conversions at 'product'; no sales at 'audience'). FILTERS, on every level: dspAdvertiserIds, dspOrderIds, dspLineItemIds (the ids the upper levels return, strings), lineItemStatuses (the CURRENT status of the line items the rows belong to: RUNNING, PAUSED_BY_USER, ENDED, the DSP page's Status chip, Running / Paused / Ended), marketplaces. The level's own: asins and promoted ('product'), supplyFamilies and supplySources ('supplyFamily', 'supplySource'), deviceTypes ('device'), creativeIds and creativeTypes ('creative'), segmentIds, segmentClassCodes and targetingMethods ('audience'), countries ('country', '' allowed for the unattributed row). A filter of another level is refused by name. ANSWER: `data` rows with `key` (the level's type and id), `attrs` (the row's name and the level's attributes), `metrics` (value, and compared_value / variance with a comparison period); `summary` (total, mean and count over the whole selection before `limit`; the count only on 'audience'); `level`, `levelNote`, `dspAdvertisers` (the linked advertisers in scope), `period` and the reporting `currency`. 💱 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.
