Chapter 16 — Ad Groups

Ad groups sit inside a campaign and define bidding and contextual targeting hints.

Endpoints

Method	Path	Purpose
GET	/ad_groups?campaign_id=...	List ad groups for a campaign.
POST	/ad_groups	Create.
GET	/ad_groups/{id}	Retrieve one.
POST	/ad_groups/{id}	Update.
POST	/ad_groups/{id}/activate	Activate.
POST	/ad_groups/{id}/pause	Pause.
POST	/ad_groups/{id}/archive	Archive (irreversible).
GET	/ad_groups/{id}/insights	Performance at ad-group scope.

Create-ad-group fields

Field	Type	Required	Notes
campaign_id	string	Yes	Parent campaign.
name	string	Yes	3–1000 chars, non-space required.
description	string	No	—
context_hints	string[]	No	Free-form keywords or descriptions of when the ad should appear.
status	string	Yes	active or paused.
bidding_config.billing_event_type	string	Yes	Currently only impression.
bidding_config.max_bid_micros	integer	Yes	1 to 100,000,000.

Context hints

Free-form hints describe when the product or service might be relevant. The example in OpenAI’s docs is ["productivity", "team collaboration"]. These are soft signals that guide placement, not hard-keyword matches like Google Ads keywords.

For a Shopify brand selling running shoes, useful hints might be:

["running", "marathon training", "trail running shoes", "athletic footwear"]

Treat them as a way to bias relevance, not as a substitute for a strong contextually-relevant landing page. The CRS Encyclopedia covers the landing-page side; this field is the ad-group hook.

Micros explained

Currency fields use micros — millionths of the main currency unit. To bid a $60 CPM ($0.06 per impression in a USD account), pass 60000 (60,000 millionths of a dollar). The example max_bid_micros: 60000 in OpenAI’s quickstart corresponds to a $60 CPM target.

You want	Pass as
$0.01 per impression ($10 CPM)	10000
$0.06 per impression ($60 CPM)	60000
$0.10 per impression ($100 CPM)	100000
$1.00 per impression ($1,000 CPM)	1000000

Note: this is not the same convention as amount on conversion events (Chapter 11). Conversion events use integers in lowest currency denomination ($129.99 → 12999). The Advertiser API uses micros for bids and budgets ($1.00 → 1000000). Two conventions, two contexts.

Update behaviour

All fields are optional on update. description accepts null to clear. If bidding_config is included, send the full object. status accepts active, paused, or archived.

Example: create an ad group

curl -X POST "https://api.ads.openai.com/v1/ad_groups" 
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "campaign_id": "cmpn_101",
    "name": "US English",
    "description": "Primary English-speaking audience.",
    "context_hints": ["productivity", "team collaboration"],
    "status": "active",
    "bidding_config": {
      "billing_event_type": "impression",
      "max_bid_micros": 60000
    }
  }'

Bidding semantics

Currently the only billing_event_type is impression. You bid a maximum cost per impression; OpenAI’s auction decides what you actually pay. The trade-press CPC band reported around the May 5 launch is roughly $3–$5 per click, which corresponds to wide ranges in CPM depending on CTR — there is no fixed conversion. The advertiser-controlled lever is max_bid_micros. Use the Insights endpoint (Chapter 19) to read back actual cpc and cpm once delivery starts.