Skip to main content

List Campaign Ad Groups

GET 

/api/advertising/campaigns/:campaign/ad-groups

Lists one campaign's ad groups with performance metrics for the date window, attached labels and the inline-edit controls each row supports. Each row carries name and default_bid.

Required scope: advertising:read

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

The window defaults to the trailing 30 days ending yesterday. Paginated (default 10, max 500 per page). Returns 404 for an unknown campaign.

Sorts: id, state, name, default_bid, spend, sales, impressions, clicks, orders, units, acos, roas, ctr, cpc, cvr, attributed_contribution, contribution_after_ads, poas (default -spend).

Filter operators. Text filters accept filter[<field>]=value (exact match) or filter[<field>.<operator>]=value with operators contains, does_not_contain, is, is_not, is_one_of, is_not_one_of, starts_with, does_not_start_with, ends_with, does_not_end_with, is_empty, is_not_empty. Numeric filters accept is, is_not, is_one_of, is_not_one_of, greater_than, less_than, greater_than_or_equal, less_than_or_equal, between (comma-separated pair), is_empty, is_not_empty.

Every window metric (spend, sales, impressions, clicks, orders, units, acos, roas, ctr, cpc, cvr, attributed_contribution, contribution_after_ads, poas) is also a numeric filter and a sort key.

platform_link opens the row in the ad platform's own console: {url, label, scope} where label reads e.g. "Open in Meta Ads Manager" and scope is entity (the link opens this campaign, ad set or ad itself) or account (the console can't address it by URL, so the link opens its ad account). It is null when the console URL needs an ID SKU.io doesn't store (Amazon Ads, Google Ads and Walmart Connect today). On these rows a Meta ad set opens itself, a Meta ad opens its campaign, and a target always opens its campaign (or account).

controls.state may also carry refused_values: an object mapping a state the platform refuses for this row to the reason (for example an eBay negative keyword can be removed but not paused: {"paused": "eBay negative keywords cannot be paused, only removed."}). Absent when every state is allowed.

effective_state is the state that actually applies: it equals state unless the row's campaign (or, for items and targets, its ad group) is archived or ended, in which case it is that parent's state. serving_status_label says why in words (for example "Campaign archived", "Ad group ended"), or is null. A row whose parent no longer serves has every control disabled with the reason "Not serving: its campaign is archived, so nothing under it serves and it cannot be changed." The stored state is the platform's own value and is not rewritten.

Requires the advertising.view permission.

Request​

Responses​

OK

Response Headers
    Content-Type