Get live ad-set details
Shows a Meta ad set's current settings straight from Meta, including its learning phase, budget, schedule and targeting.
The ad set is read live from Meta and returned verbatim. The default projection includes:
learning_stage_info: learning-phase status, LEARNING / SUCCESS / FAIL / WAIVING. Meta omits itsstatuskey on paused ad sets.- delivery settings, budgets and schedule
- dayparting (
adset_schedule,pacing_type) - targeting
fields is a raw-passthrough override; unknown fields return Meta's 400 verbatim.
Authentication
API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.
Path parameters
Meta ad set id (platformAdSetId).
Query parameters
Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token.
Comma-separated Graph field override. Supports nested {} projections and Graph field modifiers, so a nested edge can be paged explicitly: without a .limit() modifier the expansion runs at the Meta default page size and the tail is dropped silently.
Responses
Success· the request worked
Errors· the request failed
Create a standalone ad group
Creates an empty ad group under an existing campaign, ready for ads to be added later. The ad group is created WITHOUT an ad (Google Ads compliance row C.190). Ads join it later via `adSetId` on POST /v1/ads/create. Supports Google Ads and Reddit Ads; every other platform returns 501. **Google Ads** (`platform: google`) - The ad group type follows the campaign: a standard ad group under a Search or Display campaign, a Demand Gen ad group under a Demand Gen campaign. - On a Demand Gen campaign the ad group is always created PAUSED, and `maxCpc` or `status: ACTIVE` returns 400 (Demand Gen bids at the campaign). - `targeting` sets a Demand Gen ad group's locations and languages (`countries`, `regions`, `cities`, `zips`, `metros`, `languages`), created atomically with the ad group. Without it the ad group serves worldwide. - `targeting` returns 400 for any other targeting field, and on campaigns that keep geo on the campaign: Search, Display, and Demand Gen campaigns migrated from Discovery. Edit those with PUT /v1/ads/campaigns/{campaignId}/targeting. - Any other campaign type returns 400 (Performance Max has asset groups instead of ad groups). - A campaign that is not in the ad account, or was removed, returns 404. **Reddit Ads** (`platform: reddit`) - `adAccountId` (the Reddit ad account id) is required and must be a selected ad account of the connection (403 otherwise). - When the campaign has no campaign budget, send `budgetAmount` + `budgetType` (a lifetime budget needs `endDate`). - The ad group is optimized for the campaign's objective. `promotedObject.customEventType` is required on a conversions campaign, and the pixel must have received that event, else 422. - It bids with `bidStrategy`/`bidAmount` like POST /v1/ads/create. - Under campaign budget optimization the ad group takes the campaign's bid, goal type, optimization event and pixel, and bid fields return 400. - The ad group must start no earlier than a future campaign start and end no later than the campaign end (400 otherwise). - `targeting` takes the same targeting object as the other ad endpoints (no geo defaults to the US). - A campaign of another ad account returns 404, a Reddit Max campaign 422. - `maxCpc` and `customerId` are Google only (400 on Reddit), and the other Reddit fields return 400 on Google. ### After creation Created `PAUSED` unless `status: ACTIVE`. The new ad group has no ad yet, so it will not appear in GET /v1/ads/tree (built purely from `ads` rows) until one is added. Use GET /v1/ads/ad-sets to see it in the meantime. It can be read, edited and deleted through `/v1/ads/ad-sets/{adSetId}` right away (targeting, schedule, name, `status`, `budget` and bid fields). A budget on an ad group that spends its campaign budget returns 422. **Idempotency:** send an `Idempotency-Key` header to make retries safe.
Update an ad set
Changes an ad set's settings, such as its budget, bid strategy, status or delivery options. At least one updatable field is required. Use it for: - ABO budget updates. - Ad-set-scoped pause/resume. - Bid-strategy edits. - Meta value-rule-set attach/detach. - Meta beneficiary and payer: `dsaBeneficiary` / `dsaPayor` for the EU, `regionalRegulatedCategories` / `regionalRegulationIdentities` for the regional regimes. - Meta-only post-launch delivery settings via `platformSpecificData`. ### Value rule sets (Meta only) See `/v1/ads/value-rule-sets`. - ATTACH or REPLACE: send `valueRuleSetId`. Attachment is driven by the id's presence, so `valueRulesApplied: true` is optional. Sending a different id replaces the previous association; there is no separate replace call. - DETACH: send `valueRulesApplied: false` and OMIT `valueRuleSetId`. - Sending `valueRulesApplied: false` TOGETHER with `valueRuleSetId` returns 400 `mutually_exclusive_fields`. - Eligibility: only ad sets on `LOWEST_COST_WITHOUT_CAP` or `COST_CAP`. Meta rejects the rest server-side. - Read back with `GET /v1/ads/ad-sets/{adSetId}?fields=value_rule_set_id`. Meta does not document `value_rules_applied` as a readable ad-set field, so the boolean cannot be read back. The `mutually_exclusive_fields` error is deliberate. Meta attaches the rule set whenever `value_rule_set_id` is present, even with `value_rules_applied` false, so echoing stored state while asking to detach would silently keep the bid adjustments live. ### Bid strategy compatibility (per Meta's spec) - `LOWEST_COST_WITHOUT_CAP`: no `bidAmount`, no `roasAverageFloor`. - `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: `bidAmount` REQUIRED (whole currency units). - `LOWEST_COST_WITH_MIN_ROAS`: `roasAverageFloor` REQUIRED (decimal multiplier, e.g. 2.0 = 2.0x ROAS). Meta only: send `bidAmount` WITHOUT `bidStrategy` to change the cap amount on an ad set whose strategy (its own, or the campaign's under CBO) is COST_CAP / LOWEST_COST_WITH_BID_CAP, leaving the strategy untouched. Send `roasAverageFloor` WITHOUT `bidStrategy` the same way to change the floor of a LOWEST_COST_WITH_MIN_ROAS ad set. Either field against an incompatible current strategy is a 400. Meta CBO (the campaign holds the budget): the campaign also holds the bid strategy, so only `bidAmount` or `roasAverageFloor` is written on the ad set. A `bidStrategy` equal to the campaign's is accepted; a different one is a 409 (change it with PUT /v1/ads/campaigns/{campaignId}). ### Delivery settings and budget Delivery settings are validated by Meta against the campaign objective. Incompatible combinations (e.g. a billingEvent the optimization goal doesn't allow) surface as 400s from Meta. When updating `budget` on an ad set whose campaign holds the budget (CBO), the response is 409 with code `invalid_field_value`. Send it to PUT /v1/ads/campaigns/{campaignId} instead. ### Status `status` behaves exactly as PUT /v1/ads/ad-sets/{adSetId}/status describes. Only the ad set's own switch is written and its ads keep theirs. `statusUpdated` / `statusSkipped` report whether that switch was written or a live read showed it already in place. ### Placements and targeting (Meta only) `placements` and `targeting` take the same shapes as POST /v1/ads/create. Meta replaces an ad set's targeting wholesale, so Zernio reads the live targeting first, changes only what the request names and writes the merged spec back. Custom audiences, geo, age, interest groups and `targeting_automation` you do not send are kept. - `placements` replaces the whole placement set. - `placements: null` returns the ad set to automatic placements. - Omitting it leaves placements as they are. Other platforms return 400 for either field before anything in the request is written (use PUT /v1/ads/{adId} with `targeting` where that platform supports it). The live read and the `incomeTier` lookup run before any other field is written, so a 502 or 422 from them leaves the ad set unchanged. ### Reddit Ads: budget, name and bidding - `budget` changes the ad group's amount. An ad group that spends its campaign budget returns 422 (update the campaign instead). - Reddit cannot switch a published budget between daily and lifetime, so `budget.type` must match the current one (422 otherwise). - `name` renames the ad group. `bidStrategy` maps to the ad group's `bid_strategy`: - LOWEST_COST_WITHOUT_CAP: automatic bidding (BIDLESS). - LOWEST_COST_WITH_BID_CAP: MANUAL_BIDDING with `bidAmount` as the bid. - COST_CAP: MAXIMIZE_VOLUME with `bidAmount` as the cap. - LOWEST_COST_WITH_MIN_ROAS: returns 422. ### Reddit Ads: targeting and schedule `targeting` (same shape as on create; `placements` is a 400) and `startDate` / `endDate` change the ad group with one PATCH to Reddit. Read the current values with GET /v1/ads/ad-sets/{adSetId}/targeting. Zernio reads the live ad group first and replaces only the targeting groups the request names: - The included locations (`countries`, `regions`, `metros`, `cities`, `zips`) are one list on Reddit, so sending any of them replaces all included locations. - Devices, platforms, carriers and automated expansion set in Reddit Ads Manager are kept. The schedule is checked against the campaign before anything in the request is written. Each of these returns 400 naming `startDate` or `endDate`: - The ad group starts before a campaign that starts in the future. - The ad group ends after the campaign's end. - Under campaign budget optimization, it must end by the campaign end (and has no end date when the campaign has none). Zernio never resends the PATCH on its own, so after a 5xx read the ad group back before retrying.