Zernio
APIFor you
Zernio
APIFor you
API Reference

Campaigns and Ads

Overview

Get campaign treeGETGet daily account metricsGET

Campaigns

List campaignsGETCreate a standalone campaignPOSTGet live campaign detailsGETUpdate a campaignPUTDuplicate a campaignPOSTDelete a campaignDELETEPause or resume a campaignPUTPause or resume many campaignsPOSTList campaign assetsGETAttach campaign assetsPOSTUpdate campaign assetsPUTRemove campaign assetsDELETERead a Google campaign's device, location, excluded location, and language targetingGETEdit a Google campaign's device, location, excluded location, or language targetingPUTRead a campaign's ad schedule (dayparting)GETReplace a campaign's ad schedule (dayparting)PUTGet campaign conversion goalsGETUpdate campaign conversion goalsPATCH

Asset Groups

List Performance Max asset groupsGETCreate a Performance Max asset groupPOSTGet a Performance Max asset groupGETUpdate a Performance Max asset groupPATCHRemove a Performance Max asset groupDELETELink or unlink asset group assetsPOSTReplace an asset group's listing-group treePUT

Ad Sets

List ad setsGETCreate a standalone ad groupPOSTGet live ad-set detailsGETUpdate an ad setPUTDuplicate an ad setPOSTDelete an ad setDELETEPause or resume a single ad setPUTList ad-group assetsGETAttach ad-group assetsPOSTUpdate ad-group assetsPUTRemove ad-group assetsDELETE

Ads

List adsGETGet ad detailsGETCreate standalone adPOSTBoost post as adPOSTUpdate adPUTDuplicate an adPOSTCancel an adDELETEPause or resume a single adPUT

Keywords

List Search keywordsGETAdd Search ad-group keywordsPOSTPause or enable a Search keywordPATCHRemove a Search keywordDELETEList campaign-level negative keywordsGETReplace campaign-level negative keywordsPUTList campaign negative listsGETReplace campaign negative listsPUT

Bidding

Read a campaign's current biddingGETList portfolio bid strategiesGETCreate portfolio bid strategyPOSTUpdate portfolio bid strategyPATCH

Recommendations

List Google Ads recommendationsGETApply Google Ads recommendationsPOSTDismiss Google Ads recommendationsPOST

Other

Create a shared budgetPOSTRead the platform's review verdict for an adGETReview status of each creative in a TikTok Smart+ adGETList shared budgetsGETReview status of every TikTok Smart+ ad of an advertiserGET
Dashboard
OverviewPlatformsAPI ReferenceResources
Campaigns and Ads

Update an ad set

Changes an ad set's settings, such as its budget, bid strategy, status or delivery options.

Use this for ABO budget updates, ad-set-scoped pause/resume, bid-strategy edits, Meta value-rule-set attach/detach, and Meta-only post-launch delivery settings via platformSpecificData. At least one updatable field is required.

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. This 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.
  • 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.

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 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.

Reddit Ads: budget changes the ad group's amount; an ad group that spends its campaign budget returns 422 (update the campaign instead), and 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.

status behaves exactly as PUT /v1/ads/ad-sets/{adSetId}/status describes: only the ad set's own switch is written, its ads keep theirs, and 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, and 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.

PlatformsMetaGoogleTikTokLinkedInPinterestXOpenAI
PUT
/v1/ads/ad-sets/{adSetId}

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.

In: header

Path Parameters

adSetId*string

Platform ad set ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.adcampaigns.updateAdSet({  path: {    adSetId: 'adset_abc123',  },  body: {    platform: 'facebook',  },});console.log(data);
{  "budget": {    "amount": 0,    "type": "daily"  },  "budgetLevel": "adset",  "status": "active",  "platformAdSetStatus": "string",  "platformCampaignStatus": "string",  "statusReadAt": "2019-08-24T14:15:22Z",  "statusUpdated": 0,  "statusSkipped": 0,  "statusSkippedReasons": [    "string"  ],  "bidStrategy": "LOWEST_COST_WITHOUT_CAP",  "bidAmount": 0,  "roasAverageFloor": 0,  "platformSpecificData": {},  "targeting": {}}
Was this page helpful?

Get live ad-set details

Shows a Meta ad set's current settings straight from Meta, including its learning phase, budget, schedule and targeting. Reads the ad set live from Meta, returned verbatim. The default projection includes `learning_stage_info` (learning-phase status: LEARNING / SUCCESS / FAIL / WAIVING; Meta omits its `status` key on paused ad sets), delivery settings, budgets, schedule and targeting. `fields` is a raw-passthrough override; unknown fields return Meta's 400 verbatim.

Duplicate an ad set

Copies an ad set, optionally with its ads and into another campaign, created paused so you can review it before launch. The copy is created paused so callers can review before launching. `campaignId` retargets the copy into another campaign; omitted = the source's own campaign. Meta: ads and creatives are included by default (`deepCopy: true`) via Meta's native `POST /{adset-id}/copies`; the new hierarchy materializes asynchronously and sync discovery is triggered automatically (`syncAfter: false` to skip). TikTok: the ad group is read and recreated under the campaign with its targeting, bidding, budget and schedule (start reset to now); `deepCopy: true` recreates its ads too (default false). `startTime`, `endTime` and `renameStrategy` are ignored and `statusOption` must be PAUSED or absent. The copy appears on the next discovery sync.

platform*string

Value in

  • "facebook"
  • "instagram"
  • "tiktok"
  • "linkedin"
  • "pinterest"
  • "google"
  • "twitter"
  • "openai"
  • "reddit"
budget?

Omit if not updating budget

status?string

Writes the ad set's own on/off switch (Meta: configured_status; X: the line item's entity_status ACTIVE / PAUSED), whatever delivery status its ads report. Omit if not toggling delivery state.

Value in

  • "active"
  • "paused"
name?string

Rename the ad set on any supported platform: Meta, Google (the ad group), TikTok, LinkedIn (the campaign), Pinterest, X (the line item name), OpenAI and Reddit; platforms without a rename return 501. The new name is stored right away, so GET /v1/ads/ad-sets and GET /v1/ads/tree return it without a sync. At least one of budget/status/bidStrategy/name is required.

Lengthlength <= 255
bidStrategy?string

Ad-set-level bid strategy. Overrides the campaign-level default. Supported on Meta (facebook, instagram), TikTok, and OpenAI. On TikTok the Meta-style enum is mapped to bid_type / bid_price / deep_bid_type automatically. On OpenAI, LOWEST_COST_WITH_BID_CAP and COST_CAP both map to the ad group's bidding_config.max_bid_micros (one knob covers both); LOWEST_COST_WITH_MIN_ROAS is rejected with 422 (OpenAI has no ROAS-based bidding). On X it writes the line item's bid_strategy: LOWEST_COST_WITHOUT_CAP = AUTO, LOWEST_COST_WITH_BID_CAP = MAX and COST_CAP = TARGET, with bidAmount as bid_amount_local_micro; LOWEST_COST_WITH_MIN_ROAS is rejected with 422. X decides which strategy the line item's objective allows (TARGET only on REACH, FOLLOWERS and WEBSITE_CLICKS, MAX not on REACH or FOLLOWERS). On Reddit, see the mapping in the description above (LOWEST_COST_WITH_MIN_ROAS returns 422). Other platforms (linkedin, pinterest, google) return 501 Not Implemented when bidStrategy is set.

Value in

  • "LOWEST_COST_WITHOUT_CAP"
  • "LOWEST_COST_WITH_BID_CAP"
  • "COST_CAP"
  • "LOWEST_COST_WITH_MIN_ROAS"
smartTargeting?

TikTok only (a 400 elsewhere). TikTok Smart Targeting on the ad group: audience is TikTok's smart_audience_enabled, interestsBehaviors its smart_interest_behavior_enabled. When on, TikTok may deliver beyond the selected audiences or interests. Available on Video views, Traffic, Lead generation, App install, Web conversion and Community interaction. Only the flags you send are written; an unwritten flag reads back null in nativeSettings, so send false explicitly to be able to verify it is off. Applied with TikTok's adgroup/update; read it back with GET /v1/ads/ad-sets?adSetId=...&live=true.

placements?|

Meta only (400 elsewhere). Manual placements, same object and enums as placements on POST /v1/ads/create. Sending an object REPLACES the ad set's current placement set (publisher_platforms, every *_positions list and device_platforms); a position list you leave out is removed. null removes every placement key so Meta returns to automatic (Advantage+) placements. Omit to leave placements untouched. Meta enforces co-selection rules (e.g. a position needs its publisher platform) and its error is returned as is. Meta may also reject null or a narrower set when an ad's creative uses per-placement asset customization (placementAssets). An object with no non-empty list is a 400 (send null instead). Cannot be combined with targeting.placements (400).

targeting?

Meta only (400 elsewhere). Targeting fields to change, same shape as the targeting object on POST /v1/ads/create. Only the keys you send change: Zernio reads the ad set's live targeting from Meta, merges these keys over it and writes the full spec back, so everything you do not send (custom audiences, geo, age, interest groups, targeting_automation) is kept. Setting any location replaces every location list. An empty list or gender: all clears that key. incomeTier is resolved to Meta's income segment first (422 when Meta has none). Fields Meta cannot target (LinkedIn B2B, Google devices, Reddit communities and keywords) return 400 with param: targeting.<field>. An empty object is a 400, and so is a targeting.placements object with no non-empty list (param: targeting.placements). When the live targeting cannot be read the request returns 502 and nothing is written.

bidAmount?number

Bid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP. Internally converted to Meta's smallest-denomination integer, or (on OpenAI and X) to micros (× 1,000,000). Meta only: may be sent alone, WITHOUT bidStrategy, to update the cap amount on an ad set whose parent campaign is COST_CAP or LOWEST_COST_WITH_BID_CAP (the strategy is inherited from the campaign and is left untouched).

roasAverageFloor?number

Minimum ROAS as a decimal multiplier (2.0 = 2.0x). Required when bidStrategy is LOWEST_COST_WITH_MIN_ROAS. Sent to Meta as bid_constraints.roas_average_floor × 10000. Meta only: may be sent alone, WITHOUT bidStrategy, to update the floor on an ad set whose strategy (its own, or the campaign's under CBO) is LOWEST_COST_WITH_MIN_ROAS. Not supported on OpenAI (422).

valueRuleSetId?string

Meta only (other platforms return 501). Value rule set to attach to this ad set, from /v1/ads/value-rule-sets. Sending a different id replaces the current association. To DETACH, send valueRulesApplied: false and omit this field.

Match^\d+$
valueRulesApplied?boolean

Meta only (other platforms return 501). false DETACHES the ad set's value rule set and must be sent WITHOUT valueRuleSetId; the combination returns 400. true is optional when attaching, since attachment is driven by valueRuleSetId, and requires it to be present.

platformSpecificData?

Platform-specific post-launch delivery settings. The platform is implied by the platform body param. Meta only; other platforms return 400. Unknown keys are rejected.