> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Ad Group

> Creates an X (Twitter) Ads ad group (line item) in a campaign: objective, placements, schedule, bidding strategy and goal, budgets, frequency caps, and app identifiers

Creates an X (Twitter) Ads ad group (line item) in a campaign: objective, placements, schedule, bidding strategy and goal, budgets, frequency caps, and app identifiers. Ad groups are created PAUSED by default; add targeting with x\_ads\_set\_targeting and ads with x\_ads\_create\_ad.

| | |
| - | - |
| **App** | X Ads |
| **Operation ID** | `x_ads_create_ad_group` |
| **Type** | Action |
| **Connection** | `x_ads` (required) |
| **Credits per run** | 1 |
| **Agent / MCP tool** | Yes |
| **Requires approval** | Yes (write operation) |

## Inputs

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `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. |

### SelectItem

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `value` | string | Yes | - | The value of the selectable item. |
| `label` | string | Yes | - | The label of the selectable item, used for display purposes. If not provided, defaults to the value. |

### SelectableOption

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `value` | string | Yes | - | |
| `label` | string | Yes | - | |

## Output

**Type**: `Dict`

Returns the created ad group with full details.

**Fields**: dynamic (depend on the inputs)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.