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": <value>} 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": {"<dim>": {"<value>": <float>, "default": <float>}}}
                    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": "<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": "<id>", "taiwan_universal_payer": "<id>"}
    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)