Ad Groups

List ad groups

List ad groups for a campaign.

GET /ad_groups

curl -X GET "https://api.ads.openai.com/v1/ad_groups?campaign_id=cmpn_101&limit=10" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "adgrp_301",
      "created_at": 1735689700,
      "updated_at": 1735776100,
      "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
      }
    }
  ],
  "first_id": "adgrp_301",
  "last_id": "adgrp_301",
  "has_more": false
}

Create an ad group

Create an ad group for a campaign.

POST /ad_groups

Field notes

Product-set filters support title, body, item_id, offer_id, price, target_url, image_url, product_category, brand, seller_name, external_seller_id, star_rating, condition, and age_group. Use gt, gte, lt, and lte only with price or star_rating.

Context hints provide extra information on when you think your ads might be useful, and help guide when they appear. Provide a list of descriptions or keywords for when the product or service might be useful to show.

Micros are millionths of the main currency unit (e.g., Dollars). The max_bid field is per event, so a $60CPM ($0.06 per impression) is passed as 60,000 to the API. Note that currency fields respect your ad account’s default currency.

For a conversion-optimized campaign (oCPC), set bidding_config.billing_event_type to click. max_bid_micros is the CPA bid even though the billing event is a click. For example, 100000000 is a $100.00 CPA bid for a USD account. For a beta-enabled product-feed oCPC campaign, use the same POST /ad_groups endpoint. The ad group automatically inherits the campaign’s product feed. Include product_set only when you want to specify product filters; its product_feed_id must match the campaign’s feed. For the full setup and reporting workflow, see Conversion-optimized campaigns and Product feeds.

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
    }
  }'

Retrieve an ad group

Fetch one ad group by ID.

GET /ad_groups/{ad_group_id}

curl -X GET "https://api.ads.openai.com/v1/ad_groups/adgrp_301" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY"

Update an ad group

Update an ad group with POST.

POST /ad_groups/{ad_group_id}

All fields are optional on update. description can be set to null to clear it. If you include bidding_config, send the full object. status accepts active, paused, or archived. For a product-feed campaign, include the full product_set object to change the feed or its filters. Retrieve the ad group after the update if you need the resulting product_set; the immediate update response can omit it.

curl -X POST "https://api.ads.openai.com/v1/ad_groups/adgrp_301" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context_hints": ["productivity", "workflow automation"],
    "status": "paused",
    "bidding_config": {
      "billing_event_type": "impression",
      "max_bid_micros": 75000
    }
  }'

Change state with dedicated actions

The Ads API also exposes explicit state transitions. Paused ad groups won’t deliver ads to customers. Only archive objects you have no further use for, as archiving isn’t reversible.

• POST /ad_groups/{ad_group_id}/activate
• POST /ad_groups/{ad_group_id}/pause
• POST /ad_groups/{ad_group_id}/archive

curl -X POST "https://api.ads.openai.com/v1/ad_groups/adgrp_301/archive" \
  -H "Authorization: Bearer $OPENAI_ADS_API_KEY"

{
  "id": "adgrp_301",
  "created_at": 1735689700,
  "updated_at": 1735948800,
  "name": "US English",
  "description": "Primary English-speaking audience.",
  "context_hints": ["productivity", "team collaboration"],
  "status": "archived",
  "bidding_config": {
    "billing_event_type": "impression",
    "max_bid_micros": 60000
  }
}