> ## 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 a new ad group under a campaign in the connected OpenAI Ads account

Creates a new ad group under a campaign in the connected OpenAI Ads account.

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

## Inputs

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `idempotency_key` | string | No | - | Optional reusable key for this create request. Reuse the same key and payload after an uncertain response to avoid duplicates; use a new key for a new resource. |
| `campaign_id` | string or SelectableOption | Yes | - | Parent campaign ID to create the ad group under (from openai\_ads\_list\_campaigns). |
| `name` | string | Yes | - | Ad group name (3-1000 characters). |
| `status` | string or SelectableOption | Yes | - | Ad group status: 'active' or 'paused'. |
| `billing_event_type` | string or SelectableOption | Yes | - | Bid / billing event type. Must match the parent campaign's objective: 'impression' (CPM) for an impressions campaign, 'click' (CPC) for both clicks and conversions campaigns. For a conversions (oCPC) campaign, use 'click' — the bid amount is then treated as the target CPA. |
| `strategy` | string or SelectableOption | No | - | Bidding strategy: 'fixed\_bid' (the default if omitted) bids the bid\_amount; 'maximize\_clicks' / 'maximize\_conversions' bid automatically, making bid\_amount optional. |
| `bid_amount` | number | No | - | Maximum bid in account currency (e.g. US dollars), i.e. 1.50 for $1.50. This value is converted to micros automatically before sending to the API. Required unless strategy is 'maximize_clicks' or 'maximize_conversions'. For a conversions (oCPC) campaign this is the target CPA per conversion, e.g. 100 for a $100 CPA, even though billing stays per click. |
| `custom_audience_bid_multipliers` | array of OpenAIAdsAudienceBidMultiplier | No | - | Audience bid adjustments as native objects or a JSON array, e.g. \[\{"custom\_audience\_id":"caud\_123","bid\_multiplier\_micros":1500000}]. Applies to eligible audiences and fixed bidding. |
| `context_hints` | string or array of string | No | - | Optional context hints — conversations, topics, or keywords where your products or services may be relevant. These guide matching but aren't exact-match targeting. Provide one hint per line, or as a list. |
| `product_feed_id` | string | No | - | Product feed ID, shown in the Feeds area of OpenAI Ads Manager or on the campaign's product\_feed\_id field. For ad groups under a product-feed campaign: omit it to inherit the campaign's feed, or set it (must match the campaign's feed) when using product\_filters. |
| `product_filters` | string or array of OpenAIAdsProductFilterItem | No | - | Optional filters narrowing which feed items this ad group advertises (e.g. only a brand, or price above a threshold). A JSON list of \{"field", "operator", "values"} objects, e.g. \[\{"field": "brand", "operator": "in", "values": \["Acme"]}, \{"field": "price", "operator": "gt", "values": \["25.00"]}]. Only valid together with product\_feed\_id; filters are ANDed. |
| `query_string_template` | string | No | - | Optional landing-page query string template appended to destination URLs for tracking, e.g. 'utm\_source=chatgpt\&utm\_campaign=\{campaign\_id}'. |
| `description` | string | No | - | Optional ad group description. |

### OpenAIAdsAudienceBidMultiplier

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `custom_audience_id` | string | Yes | - | |
| `bid_multiplier_micros` | integer | Yes | - | Multiplier in millionths: 1500000 is 1.5x. The API accepts 0.1x to 10x for eligible audiences. |

### OpenAIAdsProductFilterItem

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `field` | string or SelectableOption | Yes | - | Feed attribute to filter on, including provider-defined ads\_metadata fields such as ads\_metadata.custom\_label\_0. |
| `operator` | string or SelectableOption | Yes | - | 'in'/'not\_in' match any of the values; 'contains'/'not\_contains'/'starts\_with' are text matches; 'gt'/'gte'/'lt'/'lte' are numeric comparisons, allowed only on 'price' and 'star\_rating'. |
| `values` | string or array of string | No | - | Values to match — a list or a comma-separated string. Numbers are sent as strings (e.g. '25.00'). |
| `value` | string or array of string | No | - | |

### SelectableOption

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

## Output

**Type**: `Dict`

Returns the created ad group object exactly as returned by the OpenAI Ads API (id, name, status, bidding\_config, context\_hints, description, product\_set, campaign\_id, created\_at, updated\_at).

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

**Example**:

```json theme={"dark"}
{
  "id": "adgrp_...",
  "campaign_id": "cmpn_...",
  "name": "US English",
  "status": "active",
  "bidding_config": {
    "billing_event_type": "click",
    "max_bid_micros": 3500000
  },
  "context_hints": [
    "productivity"
  ]
}
```


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