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.
advertising:readGrant 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
- 200
- 401
- 403
- 404
- 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.
Not Found
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.