OpenAI Ads MCP Server

OpenAI Ads

ChatGPT Ads are sponsored chat_card units below ChatGPT answers (labeled Sponsored, separate from the model reply). They reach Free and Go users in supported regions; Plus, Pro, Business, Enterprise, and Education tiers do not see ads. Each API key maps to exactly one ad account — there is no account switch parameter.

Hierarchy:

Ad account → Campaign → Ad group → Ad

Targeting: context hints, not keywords

Ad groups carry context_hints — plain-language descriptions of conversations where the ad should appear (for example users comparing CRM tools for agencies). OpenAI matches live chat context, hints, creative, and landing page in a relevance-weighted auction. There are no keywords, keyword volume, or pre-flight CPC quotes. Pair with Google Ads when you need search intent and Keyword Planner bands.

Creative: chat_card

Primary format is chat_card: title (3–50 chars, truncates visually earlier), body (max 100 chars), square image via upload (file_id), target_url, optional account favicon upload. product_ad_template exists for product-feed campaigns when mode is product_feed on the campaign.

What this API does and does not do

In scope: campaign structure, geo targeting, creative upload, custom audiences, conversion pixels and event settings, server-side conversion keys, delivery insights (impressions, clicks, spend, ctr, cpc, cpm), and attributed conversion totals.

Out of scope: keyword research, search volume forecasts, pre-flight CPC estimates, audience size previews, or conversation-level reporting. Advertisers only receive aggregated performance. ChatGPT Ads reports CPC and CPM after delivery via insights — plan from daily_spend_limit_micros and historical rows.

Bidding types: impressions (CPM), clicks (CPC), conversions (oCPC open beta — still billed per valid click, optimized toward one conversion event setting).

Serving requires campaign, ad group, and ad all enabled plus ad review approval. New accounts and ads often sit in in_review until OpenAI approves them.

Recommended workflow

1. Read ad account — confirm currency, timezone, account review_status, and brand fields.
2. Search geo locations — copy location ids into campaign targeting.locations.include (never free-text country names).
3. Upload creative — chat_card ads require file_id from upload before upsert ad. Optional purpose account_favicon for brand favicon.
4. Create campaigns, ad groups (with context_hints), and ads paused. Respect market daily minimums (for example 25000000 micros = $25 USD, 15000000 micros = £15 GBP per campaign).
5. Measurement stack (when optimizing for conversions):
   • Create conversion pixel → note source id.
   • Create conversion event setting linking source_ids → note id for conversion-optimized campaigns.
   • Create conversion API key for server events — copy from Ads Manager when shown.
   • List conversion event settings before binding conversion_event_setting_ids on campaigns.
6. Audiences — small lists via inline members (identifier_type + value); bulk lists via upload custom audience after uploading the file.
7. Activate bottom-up only when review_status is approved and spend is intended.
8. Reporting — delivery insights with fields like impressions, clicks, spend, ctr, cpc, cpm. Pass time_ranges as JSON objects (date_range with since, until, timezone, or unix_range with epoch seconds). Only one segment per request (country, device, or product). Conversion insights at campaign, ad group, or ad level with start_time/end_time (end snaps to full hour).

Audit helpers (one-call triage)

Use these before chaining raw list calls:

• Account overview — walks campaign → ad group → ad once, merges serving flags, and surfaces serving_issues including paused-parent codes list endpoints omit.
• Context hints audit — finds ad groups with missing, empty, or thin context_hints.
• Ad copy audit — title/body length violations, truncation-risk guidance, and near-duplicate copy within scope.
• Ad performance audit — aggregates delivery insights per ad for a date window and flags dead, underperforming, or insufficient-data ads (handles the insights quirk when until is today).

For serving_issues on a single entity, fetch by id on campaigns, ad groups, or ads — list responses do not include them.

Product feeds

Full catalog upload is via SFTP in Ads Manager — the Advertiser API has no feed list or create endpoints. Product-feed campaigns carry product_feed_id on the campaign object.

• Linked feeds scan — lists product_feed_id values referenced on product_feed campaigns in the account.
• Delta updates — patch availability or titles on existing variants when delta feeds are enabled on the account (requires feed_id from the linked scan or campaign read).

Insights patterns

• Delivery: get insights with time_granularity daily (lowercase, not DAY), explicit fields array, and JSON time_ranges objects for the window.
• Conversions: get conversion insights with aggregation_level, entity_ids, and start_time/end_time (or encoded time_ranges).
• Empty data usually means no spend or no attributed events yet — not a broken query.

Gotchas

• Budgets and bids use micros (daily_spend_limit_micros, lifetime_spend_limit_micros, max_bid_micros).
• Custom audience members use identifier_type and value — not bare email keys.
• Archive custom audiences when retiring lists; pause or archive campaigns/ad groups/ads instead of deleting.
• Rate limits: 600 requests per minute per endpoint and 1,200 overall per ad account and IP.
• Brand updates and some measurement endpoints may require partner enablement upstream.
• Product-feed campaigns (mode product_feed) need a linked product_feed_id on the campaign; initial catalog upload is via Ads Manager SFTP — use linked-feed scan and delta updates for availability/title changes after setup.