create_adset

Create a new ad set in a Meta Ads account.

Args: account_id: Meta Ads account ID (format: act_XXXXXXXXX) campaign_id: Meta Ads campaign ID this ad set belongs to name: Ad set name optimization_goal: Conversion optimization goal. Valid values depend on the campaign objective and destination_type. OUTCOME_ENGAGEMENT + destination_type=WEBSITE: OFFSITE_CONVERSIONS, LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH. OUTCOME_ENGAGEMENT + On Post (destination_type=ON_POST): POST_ENGAGEMENT, IMPRESSIONS, REACH. Also set promoted_object={page_id} at creation (immutable; without it create_ad fails with subcode 1885154). Do NOT use ON_AD here — ON_AD is the OUTCOME_LEADS instant-form destination and Meta rejects it for OUTCOME_ENGAGEMENT (subcode 1815715). OUTCOME_ENGAGEMENT + On Video (destination_type=ON_VIDEO): THRUPLAY, TWO_SECOND_CONTINUOUS_VIDEO_VIEWS. OUTCOME_ENGAGEMENT + On Event (destination_type=ON_EVENT): EVENT_RESPONSES, IMPRESSIONS, POST_ENGAGEMENT, REACH. OUTCOME_ENGAGEMENT + On Page (destination_type=ON_PAGE): PAGE_LIKES. OUTCOME_ENGAGEMENT + Messaging (MESSENGER/WHATSAPP/INSTAGRAM_DIRECT): CONVERSATIONS, LINK_CLICKS. OUTCOME_ENGAGEMENT "Profile and Page visits" (PROFILE_AND_PAGE_ENGAGEMENT with destination_type INSTAGRAM_PROFILE / FACEBOOK_PAGE / INSTAGRAM_PROFILE_AND_FACEBOOK_PAGE) is shown in Ads Manager but NOT supported via the Marketing API — Meta rejects every variant (code 100). Closest API-supported option is POST_ENGAGEMENT + ON_POST. OUTCOME_TRAFFIC + WEBSITE: LANDING_PAGE_VIEWS, LINK_CLICKS, IMPRESSIONS, REACH. OUTCOME_AWARENESS: REACH, IMPRESSIONS, AD_RECALL_LIFT, THRUPLAY. OUTCOME_LEADS: LEAD_GENERATION, QUALITY_LEAD (forms), QUALITY_CALL (calls), OFFSITE_CONVERSIONS, LINK_CLICKS (website). OUTCOME_SALES: OFFSITE_CONVERSIONS, VALUE, CONVERSATIONS, LINK_CLICKS, IMPRESSIONS, REACH. OUTCOME_APP_PROMOTION: APP_INSTALLS, APP_INSTALLS_AND_OFFSITE_CONVERSIONS, VALUE. billing_event: How you're charged (e.g., 'IMPRESSIONS', 'LINK_CLICKS') status: Initial ad set status (default: PAUSED) daily_budget: Daily budget in account currency (in cents) as a string. CBO NOTE: Do NOT set this if the parent campaign already has a budget (Campaign Budget Optimization / CBO mode). Meta only allows budgets at one level: either the campaign OR the ad set, not both. If the campaign has a daily_budget or lifetime_budget, omit this field — the ad set will automatically use the campaign budget. lifetime_budget: Lifetime budget in account currency (in cents) as a string. CBO NOTE: Do NOT set this if the parent campaign already has a budget (Campaign Budget Optimization / CBO mode). Omit this field when the campaign uses CBO — the ad set inherits the campaign budget automatically. targeting: Targeting specs (age, location, interests, etc). targeting_automation.advantage_audience defaults to 0 if not set (Meta API v24+ requirement). Set to 1 to enable Advantage+ Audience (requires age_max>=65). Use search_interests for interest IDs. bid_amount: Bid amount in account currency (in cents). REQUIRED for: LOWEST_COST_WITH_BID_CAP, COST_CAP, TARGET_COST. NOT USED by: LOWEST_COST_WITH_MIN_ROAS (uses bid_constraints instead). May also be required if the parent campaign's bid strategy requires it. bid_strategy: Bid strategy. Valid values: - 'LOWEST_COST_WITHOUT_CAP' (recommended) - no bid_amount required - 'LOWEST_COST_WITH_BID_CAP' - REQUIRES bid_amount - 'COST_CAP' - REQUIRES bid_amount - 'LOWEST_COST_WITH_MIN_ROAS' - REQUIRES bid_constraints with roas_average_floor, and optimization_goal='VALUE'. Does NOT use bid_amount. Note: 'LOWEST_COST' is NOT valid - use 'LOWEST_COST_WITHOUT_CAP'. Campaign-level bid strategy may constrain ad set choices. bid_constraints: Bid constraints dict. Required for LOWEST_COST_WITH_MIN_ROAS. Use {"roas_average_floor": } where value = target ROAS * 10000. Example: 2.0x ROAS -> {"roas_average_floor": 20000} bid_adjustments: Bid multipliers per targeting dimension. Pass-through to Meta. Shape: {"user_groups": {"": {"": , "default": }}} Dims: age, gender, user_os, device_platform, position_type, publisher_platform, user_bucket, home_location, locale, etc. Multipliers are floats, typically 0.0-1.0. Example: {"user_groups": {"user_os": {"iOS": 0.9, "Android": 0.7, "default": 1.0}}} NOTE: Writing bid_adjustments requires a Meta app capability that must be allowlisted. Apps without it get OAuthException (#3). start_time: Start time in ISO 8601 format (e.g., '2023-12-01T12:00:00-0800'). To schedule future delivery: set start_time to a future date and status=ACTIVE. Meta will show effective_status as SCHEDULED and automatically begin delivery at start_time. NOTE: Only ad set start_time controls delivery scheduling. Campaigns do not support start_time. end_time: End time in ISO 8601 format. Required when lifetime_budget is specified. dsa_beneficiary: DSA beneficiary for European compliance (person/org that benefits from ads). Required for EU-targeted ad sets along with dsa_payor. dsa_payor: DSA payor for European compliance (person/org paying for the ads). Required for EU-targeted ad sets along with dsa_beneficiary. promoted_object: For APP_INSTALLS: app config, required application_id + object_store_url. For OUTCOME_ENGAGEMENT On-Post (destination_type=ON_POST): set {"page_id": ""} at creation — required for ads (else create_ad fails with subcode 1885154) and immutable afterward (cannot be added via update_adset). destination_type: Conversion location / where users go. Pass-through to Meta (no client-side validation). Common values: 'WEBSITE', 'WHATSAPP', 'MESSENGER', 'INSTAGRAM_DIRECT', 'APP', 'FACEBOOK', 'SHOP_AUTOMATIC'. OUTCOME_ENGAGEMENT on-asset locations: 'ON_POST' (post engagement; needs promoted_object={page_id}), 'ON_PAGE' (PAGE_LIKES), 'ON_EVENT', 'ON_VIDEO'. 'ON_AD' is the OUTCOME_LEADS instant-form destination — do NOT use it for OUTCOME_ENGAGEMENT (Meta rejects it with subcode 1815715). Also supports multi-channel combos like 'MESSAGING_MESSENGER_WHATSAPP'. is_dynamic_creative: Enable Dynamic Creative for this ad set. frequency_control_specs: Frequency cap specs. MUST be set at creation time — Meta makes this field immutable after the ad set is created (error 1815198). Only works with OUTCOME_AWARENESS campaigns + optimization_goal REACH or THRUPLAY. Example: [{"event": "IMPRESSIONS", "interval_days": 7, "max_frequency": 1}] multi_advertiser_ads: Set to 0 to opt out of Multi-Advertiser Ads, 1 to opt in. This is a TOP-LEVEL ad set parameter — do NOT put it inside the targeting object. regional_regulated_categories: List of regional regulated categories for the ad set. Required for ads targeting regulated regions (Taiwan, Australia, etc.). Valid values: TAIWAN_FINSERV, TAIWAN_UNIVERSAL, AUSTRALIA_FINSERV, INDIA_FINSERV, SINGAPORE_UNIVERSAL, THAILAND_UNIVERSAL. Example: ["TAIWAN_UNIVERSAL"] or ["TAIWAN_FINSERV", "TAIWAN_UNIVERSAL"] regional_regulation_identities: Dict of verified identity IDs for regional transparency compliance. Required when regional_regulated_categories is set. The identity IDs come from completing advertiser verification in Meta Business Settings. Keys depend on the categories declared: - TAIWAN_UNIVERSAL: taiwan_universal_beneficiary, taiwan_universal_payer - TAIWAN_FINSERV: taiwan_finserv_beneficiary, taiwan_finserv_payer - AUSTRALIA_FINSERV: australia_finserv_beneficiary, australia_finserv_payer - SINGAPORE_UNIVERSAL: singapore_universal_beneficiary, singapore_universal_payer Example: {"taiwan_universal_beneficiary": "", "taiwan_universal_payer": ""} attribution_spec: Attribution window specification for the ad set. Controls how conversions are attributed to ads. Default is 7-day click if not specified. Example for 1-day click: [{"event_type": "CLICK_THROUGH", "window_days": 1}] Example for 1-day click + 1-day view: [{"event_type": "CLICK_THROUGH", "window_days": 1}, {"event_type": "VIEW_THROUGH", "window_days": 1}] Valid event_type values: CLICK_THROUGH, VIEW_THROUGH. Valid window_days values: 1, 7, 28 (depends on event_type and optimization_goal). access_token: Meta API access token (optional - will use cached token if not provided)