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.
advertising:readGrant 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_typematches products with an open signal of that type;goalvalues areprofit(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_daysand text operator filters onsku,name, in the formfilter[<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
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.