Skip to main content

List Ad Health Products

GET 

/api/advertising/products

Lists advertised products with their ad health: the worst stock-cover pool across ad accounts, inbound supply, forecast, break-even ACoS, 7- and 30-day spend / ACoS / TACoS / POAS, overall health, open guardrail signals, active holds, a per-platform breakdown and the product's live ad items. Only products with a health snapshot (that is, products evaluated by the guardrails) are listed.

Required scope: advertising:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

health is one of paused, throttled, at_risk, unprofitable, overstock, no_data, healthy (the worst across the product's accounts). Ratios (acos_*, tacos_30d, attributed_share, break_even_acos) are fractions, e.g. 0.2287 = 22.87%. poas_7d / poas_30d cover every account shown (each account's POAS weighted by its spend), and tacos_30d / attributed_share use the product's actual sales summed across the sales channels its accounts draw on. Each entry in holds carries ad_change_id, the change set line that applied the hold.

Filters (filter[...]):

  • platform, signal_type, health, brand_id, goal: one value or a comma-separated list. Each also accepts the operator forms .is, .is_one_of (match any) and .is_not, .is_not_one_of (exclude), e.g. filter[health.is_not]=healthy. signal_type matches products with an open signal of that type; goal values are profit (also matches products with no goal), growth, launch, liquidate, defend, hold.
  • has_open_signal (boolean): with / without any open signal.
  • cover_below (number): cover days below this value.
  • acos_above_break_even (boolean): 30-day ACoS above break-even.
  • poas_below (number): 30-day POAS below this value.
  • product_ids: comma-separated product IDs.
  • waiting_on_po (purchase order ID): products whose next inbound is that purchase order.
  • search: matches SKU or name.
  • Numeric operator filters on cover_days, poas_7d, poas_30d, spend_30d, lead_time_days and text operator filters on sku, name, in the form filter[<column>.<operator>].

Sorts (sort, prefix - for descending): sku, name, cover_days, available, lead_time_days, next_inbound_eta, break_even_acos, acos_7d, acos_30d, tacos_30d, poas_7d, poas_30d, spend_7d, spend_30d, health. Default: worst health first, then lowest cover.

Pagination: per_page defaults to 10 (max 200); page selects the page.

Requires the advertising.view permission. Personal access tokens need the advertising:read scope.

Request​

Responses​

OK

Response Headers
    Content-Type