account | DynamicAccount | Yes | - | Ad account to use. Accepts account ID or option object; value may be with or without ‘act_’ prefix (for example ‘act_1234567890’ or ‘1234567890’) |
campaign_id | string or SelectItem | Yes | - | Campaign ID where the ad set will be created |
adset_name | string | Yes | - | Ad set name shown in Ads Manager. Maximum 400 characters |
status | string or SelectableOption | No | - | Initial delivery status after creation. If omitted, runner defaults to PAUSED |
destination_type | string or SelectableOption | Yes | - | ODAX destination type. Must be compatible with optimization_goal and promoted_object fields |
optimization_goal | string or SelectableOption | Yes | - | Optimization goal used for delivery and learning. Must align with destination_type and billing_event |
billing_event | string or SelectableOption | Yes | - | Billing event used by Meta for charging/optimization. Must be valid for the selected goal |
bid_strategy | string or SelectableOption | No | - | Bid strategy. If omitted, runner defaults to LOWEST_COST_WITHOUT_CAP |
bid_amount | number | No | - | Bid amount as an actual dollar value in the account currency, NOT in cents (e.g. pass 2.5 for $2.50). Do not multiply by 100 — the backend converts to cents automatically. Required when bid_strategy is COST_CAP or LOWEST_COST_WITH_BID_CAP. |
budget_type | string or SelectableOption | No | - | Budget mode: CAMPAIGN (use campaign budget), DAILY, or LIFETIME |
budget_value | number | No | - | Budget amount as an actual dollar value in the account currency, NOT in cents (e.g. pass 25 for 25,12.5for12.50). Do not multiply by 100 — the backend converts to cents automatically. Required for DAILY and LIFETIME; ignored for CAMPAIGN. |
attribution_setting | string or SelectableOption | No | - | Optional conversion attribution setting for optimization. Don’t set this unless you know you need it; Meta’s default attribution setting is typically recommended and sufficient for most use cases. If set, must be compatible with the selected optimization_goal. |
is_incremental_attribution_enabled | boolean | No | - | Optional incremental attribution optimization flag. Omit this to let Meta use the standard attribution optimization behavior. If enabled, meta will ignore any attribution_setting provided |
start_time | integer | No | - | Optional start date/time as Unix timestamp in seconds (UTC), for example 1735689600 |
end_time | integer | No | - | Optional end date/time as Unix timestamp in seconds (UTC). Required when budget_type is LIFETIME |
promoted_object | object or string | No | - | The object this ad set promotes, as a Meta promoted_object JSON object. Required for certain objectives (for example website/app conversions, page likes, product sales). Pass only the Meta fields you need; do not wrap them in any discriminator. Common keys: pixel_id, custom_event_type, custom_event_str, page_id, application_id, object_store_url, product_set_id, product_catalog_id, offline_conversion_data_set_id, event_id. custom_event_type must be a valid Meta CustomEventType value, for example PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART, INITIATED_CHECKOUT, CONTENT_VIEW, SUBSCRIBE, or OTHER (use OTHER with custom_event_str for a custom event). Example: {“pixel_id”: “1234567890”, “custom_event_type”: “PURCHASE”} |
targeting | object or string | Yes | - | The Meta targeting spec for this ad set, as a JSON object sent to Meta as-is. Only geo_locations is required. Every other key below is optional: omit any you don’t explicitly need and Meta applies its own defaults (for example broad age range, all genders, automatic placements). Do not send keys just to restate Meta’s defaults. Use the keys below as needed: - geo_locations (required): object with any of countries (ISO 3166-1 alpha-2, e.g. [‘US’,‘GB’]), regions ([{key}]), cities ([{key, radius, distance_unit}]), zips ([{key}]), custom_locations ([{latitude, longitude, radius, distance_unit}]), geo_markets ([{key, name}]). location_types (e.g. [‘home’,‘recent’]). - excluded_geo_locations: same shape as geo_locations, to exclude areas. - age_min (13-65), age_max (13-65), omit for meta’s default of 18-65+ - genders: [1] for male, [2] for female, omit for all. - locales: list of Meta locale IDs (languages). - interests / behaviors: lists of {id, name} from Meta’s targeting search. - flexible_spec: list of AND-grouped objects, each with interests/behaviors/demographics arrays (OR within each); used for detailed targeting. - exclusions: object with interests/behaviors to exclude. - custom_audiences / excluded_custom_audiences: lists of {id} for saved, lookalike, or retargeting audiences. - publisher_platforms: subset of [‘facebook’,‘instagram’,‘messenger’,‘audience_network’,‘threads’]; omit for automatic (Advantage+) placements. - device_platforms: [‘mobile’,‘desktop’]. - facebook_positions / instagram_positions / messenger_positions / audience_network_positions / threads_positions: per-platform placement lists; only valid when the matching publisher platform is set. - targeting_automation: object such as {“advantage_audience”: 1} to enable Advantage+ audience. Example: {“geo_locations”: {“countries”: [“US”]}, “age_min”: 25, “age_max”: 45, “genders”: [2], “interests”: [{“id”: “6003107902433”, “name”: “Yoga”}]} |
dsa_beneficiary | string | No | - | Optional DSA beneficiary text for EU ad transparency requirements |
dsa_payor | string | No | - | Optional DSA payor text for EU ad transparency requirements |
