account | DynamicAccount | Yes | - | Select the X Ads account to create the ad group in. |
campaign_id | string or SelectItem | Yes | - | Campaign to create the ad group (line item) under. All ad groups in a campaign must share the same objective and product type. |
objective | enum (APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS) | Yes | - | Campaign objective: APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, or WEBSITE_CLICKS. Website conversion campaigns use WEBSITE_CLICKS with goal WEBSITE_CONVERSIONS. |
product_type | enum (PROMOTED_TWEETS, PROMOTED_ACCOUNT, MEDIA) | No | - | What the ad group promotes. Defaults to PROMOTED_TWEETS, except FOLLOWERS ad groups, which X only accepts as PROMOTED_ACCOUNT. Set MEDIA only when promoting media directly. |
placements | array of string or SelectableOption | No | [{'value': 'ALL_ON_TWITTER', 'label': 'All on X'}] | Where ads serve: ALL_ON_TWITTER (default), TWITTER_TIMELINE, TWITTER_SEARCH, TWITTER_PROFILE, TWITTER_REPLIES, PUBLISHER_NETWORK, or the TAP_* X Audience Platform placements. TWITTER_PROFILE cannot be the only placement; REACH must include TWITTER_TIMELINE; TWITTER_SEARCH requires keyword targeting; PUBLISHER_NETWORK requires categories and advertiser_domain. |
start_time | string | No | - | When the ad group starts delivering: ISO 8601 (YYYY-MM-DD or full timestamp) or a Unix timestamp. Defaults to now, so delivery can begin as soon as the ad group is activated. |
end_time | string | No | - | When the ad group stops delivering: ISO 8601 or a Unix timestamp. Runs indefinitely when omitted. |
name | string | No | - | Ad group name, up to 255 characters. |
entity_status | enum (ACTIVE, PAUSED, DRAFT) | No | PAUSED | Status to create the ad group with: ACTIVE, PAUSED (default), or DRAFT. |
bid_strategy | enum (AUTO, MAX, TARGET) | No | - | Bidding strategy: AUTO (default, optimizes from budget), MAX (not available for REACH or FOLLOWERS), or TARGET (averages within 20% of the bid). MAX and TARGET require bid_amount. |
bid_amount | number | No | - | Bid in the ad account’s currency (for example 2.5 for $2.50), converted to X micro-currency automatically. Required when bid_strategy is MAX or TARGET; ignored for AUTO. |
goal | enum (APP_CLICKS, APP_INSTALLS, APP_PURCHASES, ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, …) | No | - | Optimization goal; X picks a default per objective when omitted. Notable pairings: SITE_VISITS and WEBSITE_CONVERSIONS belong to WEBSITE_CLICKS (WEBSITE_CONVERSIONS also requires primary_web_event_tag), APP_CLICKS / APP_INSTALLS / APP_PURCHASES belong to the app objectives. |
pay_by | enum (APP_CLICK, IMPRESSION, LINK_CLICK) | No | - | What you pay for; X sets the default per goal and it is only modifiable for the APP_INSTALLS objective. |
daily_budget | number | No | - | Ad group daily budget in the ad account’s currency, converted to micro-currency automatically. Must not exceed the total budget when both are set. |
total_budget | number | No | - | Ad group total budget in the ad account’s currency, converted to micro-currency automatically. |
standard_delivery | boolean | No | - | true spends the budget evenly over time (default); false delivers as fast as possible. |
frequency_cap | integer | No | - | Maximum times an ad can be delivered to one user within duration_in_days. Only supported for REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS. |
duration_in_days | enum (1, 7, 30) | No | - | Window the frequency_cap applies over: 1, 7, or 30 days. |
audience_expansion | enum (BROAD, DEFINED, EXPANDED) | No | - | Expand the targeted audience to reach similar users: DEFINED (targeting as is), EXPANDED, or BROAD. No expansion is applied when omitted. |
categories | string or array of string | No | - | IAB content categories describing the advertiser (list or comma-separated ids, from X’s iab_categories endpoint). Required when placements include PUBLISHER_NETWORK. |
advertiser_domain | string | No | - | The advertiser’s website domain without protocol (example.com). Required when placements include PUBLISHER_NETWORK. |
android_app_store_identifier | string | No | - | Google Play package name (e.g. com.example.app). APP_INSTALLS and APP_ENGAGEMENTS require at least one app store identifier; setting one also auto-adds matching PLATFORM targeting. |
ios_app_store_identifier | string | No | - | Numeric portion of the App Store id (e.g. 333903271). APP_INSTALLS and APP_ENGAGEMENTS require at least one app store identifier. |
primary_web_event_tag | string | No | - | Website tag id whose conversions define success. Required when goal is WEBSITE_CONVERSIONS. |
advertiser_user_id | string | No | - | User id of the handle promoting a PREROLL_VIEWS ad. Restricted to certain client applications per X. |
