The OpenAI Ads API is a REST API at https://api.ads.openai.com/v1 that lets you create and manage ChatGPT Ads campaigns, ad groups and ads, upload creative, and pull reporting with code instead of clicking through Ads Manager. You need an existing ChatGPT Ads account and an Advertiser API key, which you create on the Settings page in Ads Manager, and every request is authenticated with that key as a Bearer token.
This guide covers what the official OpenAI Ads API documentation says about access, authentication, the object model, endpoints, bidding fields, reporting and limits, plus which parts are still gated per account. If you are new to the channel, start with the complete ChatGPT Ads guide; if you are still deciding whether you need the API at all, read ChatGPT Ads Manager vs API first.
What the OpenAI Ads API is (and is not)
OpenAI publishes the Ads API documentation on developers.openai.com/ads, alongside guides for campaign management, conversion tracking, product feeds and conversion-optimized campaigns, and an OpenAPI specification. It is an advertiser-side management API: it controls the same account, campaign, ad group and ad objects you see in OpenAI Ads Manager.
It is not the regular OpenAI developer platform. Your platform.openai.com API key for GPT models does not work here, and the Ads API is not a way to put ads inside your own app. It is also separate from the Conversions API you use for server-side measurement, which, in OpenAI’s words, “uses a separate host and a CAPI key.”
Who can use the API and how to get access
The overview page states the requirements plainly: “You will need an ad account and an Advertiser API key.” The quickstart adds: “Issue an API key in the Settings tab of your Ads Manager account.” So the starting point is a working ChatGPT Ads account. If you do not have one yet, follow the steps in ChatGPT Ads account requirements and supported countries.
The documentation does not describe a separate signup or waitlist for the core API. Several features, however, are enabled per account, and the docs tell you to contact your OpenAI partner representative or account team when a call returns 403 or “Not found”:
- Conversion bidding (oCPC) returns “Conversion bidding is not enabled” when the account lacks it.
- Pixel management, Conversions API key creation and brand updates must be enabled for the account.
- Bulk API: “in limited preview and is enabled per ad account.”
- Delta Feeds API (price, title and availability updates for product feeds): enabled per ad account.
- Hotel property feeds: “available only to approved pilot advertisers. This is not an open beta.”
Agencies and technology partners have a separate API Partner Setup guide. That page tells partners to use the API key associated with the client ad account for each request.
Authentication: API keys and headers
Each Advertiser API key is tied to one ad account. Send it in the standard Bearer header and confirm it works by reading the account:
curl https://api.ads.openai.com/v1/ad_account \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY"
Store the key in an environment variable or secret manager, never in front-end code or a public repository. One point in the docs is inconsistent: the Bidding & Budgets page says that with a partner key you also include an OpenAI-Ad-Account header, while the Bulk API page says not to add that header when using an API key. If you work with a single advertiser key, leave the header off; if you are a partner with multi-account access, confirm with your OpenAI contact before relying on either reading.
Object model: account, campaign, ad group, ad
The API mirrors the Ads Manager structure: “Ad account → Campaign → Ad group → Ad.” OpenAI’s advice is to “use separate campaigns when you need separate budgets, objectives, or targeting.” The table below summarises the main fields documented for each level.
| Level | What it controls | Key documented fields |
|---|---|---|
| Ad account | Brand, currency, timezone, account-level spend limits | legal_name, account_name, brand_name; currency and timezone are set at creation and cannot be changed through branding |
| Campaign | Objective, budget, countries, audiences, platforms, schedule | bidding_type (impressions, clicks or conversions), daily_spend_limit_micros or lifetime_spend_limit_micros (one, not both), targeting.locations, targeting.custom_audiences, targeting.platforms, start_time, end_time |
| Ad group | Context and bid strategy | context_hints, bidding_config (billing_event_type, strategy, max_bid_micros), custom_audience_bid_multipliers |
| Ad | Creative shown in ChatGPT | creative type chat_card, title (3-50 characters), body (up to 100 characters), target_url, one image (file_id) or 4-6 square images (file_ids) |
Two rules catch people out. First, “You cannot change the campaign objective or selected conversion event after creation,” and a daily budget cannot be switched back to lifetime. Second, creating an ad submits it for review; it does not mean the ad has passed review or is ready to serve. Context hints are covered in more depth in how ChatGPT Ads targeting works.
Endpoints you will use most
All paths below are relative to https://api.ads.openai.com/v1. Updates to campaigns, ad groups and ads use POST on the object’s URL; product delta updates are the exception and use PATCH.
| Task | Method and path |
|---|---|
| Check the key and account | GET /ad_account |
| List or create campaigns | GET /campaigns, POST /campaigns |
| Read or update a campaign | GET /campaigns/{id}, POST /campaigns/{id} |
| Change status | POST /campaigns/{id}/activate, /pause or /archive (same pattern for ad groups and ads) |
| Ad groups | GET /ad_groups?campaign_id=…, POST /ad_groups, POST /ad_groups/{id} |
| Ads | GET /ads?ad_group_id=…, POST /ads, POST /ads/{id}, POST /ads/{id}/preview |
| Upload an image | POST /upload (image URL or multipart file) |
| Delivery reporting | GET /ad_account/insights, /campaigns/{id}/insights, /ad_groups/{id}/insights, /ads/{id}/insights |
| Conversion reporting | POST /conversions/insights |
| Measurement setup | POST /conversions/pixels, /conversions/event_settings, /conversions/api_keys |
| Product feeds | GET /feeds, POST /feeds, PATCH /feeds/{feed_id}/products (Delta Feeds, if enabled) |
| Change history | GET /audit_logs |
The full machine-readable list is in OpenAI’s OpenAPI file at developers.openai.com/ads/openapi.json. The Bulk API (POST /bulk_mutation_jobs) is not included in that spec and only works on accounts with the preview enabled.
Budgets and bids are sent in micros
Money fields use micros: “one major currency unit equals 1000000 micros.” A $50 daily budget is 50000000. For impression bidding the bid is stored per impression, so a $60 CPM is sent as 60000. The supported combinations are:
| Campaign bidding_type | Ad group billing_event_type | Allowed strategies |
|---|---|---|
| impressions | impression | fixed_bid |
| clicks | click | fixed_bid or maximize_clicks |
| conversions | click | fixed_bid (max_bid_micros is your CPA) or maximize_conversions |
Maximize strategies need a daily budget and no max_bid_micros, and the docs say an Idempotency-Key header is required when creating a Maximize Results ad group. Conversion bidding also needs an active, standard conversion event tied to an active pixel or server source. Before you pick bids, run your numbers through the CPM calculator and CPC calculator, and see ChatGPT Ads cost and pricing for minimums and reported bid levels.
Example: a campaign with bidding_type “clicks”, a daily budget of 40000000 ($40) and one ad group with strategy maximize_clicks. The ad group request omits max_bid_micros and carries an Idempotency-Key, and the ad then goes into review after you POST it to /ads.
Reporting with the insights endpoints
Delivery insights return impressions, clicks, spend, CTR, CPC and CPM. Conversion metrics documented include conversions, CPA, post-click conversion rate, attributed order sales and order ROAS, plus click-through and view-through conversions on the conversion endpoint. Practical details from the reporting docs:
- Granularity: time_granularity “daily” or “none”.
- Date ranges: either a date_range (since, until, timezone) or a unix_range (start, end). “The date_range.until date is inclusive; unix_range.end is exclusive.”
- Segments: examples show product and country segments; the conversion endpoint supports country and device breakdowns.
- History: non-hourly delivery data covers “the most recent 365 days”; hourly and product reporting cover approximately 30 days. Export regularly if you need long product-level history.
- Attribution: a September 30, 2026 changelog entry changed defaults to a 30-day click window and 1-day view window, which changed conversion totals but not impressions, clicks or spend.
If the API shows events but no conversions, the cause is usually in setup rather than the API; see ChatGPT Ads events received but no conversions.
Conversions API vs Ads API
The Ads API creates the pixel, event settings and Conversions API key (POST /conversions/pixels, /conversions/event_settings and /conversions/api_keys). Sending conversion events from your server is a different call on a different host with that CAPI key, and OpenAI warns not to expose the key in browser code. To avoid double counting when you send both pixel and server events, use the same event ID on both sides, as explained in ChatGPT Ads pixel and Conversions API deduplication. For testing, GET /conversions/events returns a sample of recent events from roughly the last 15 minutes; it is a debugging tool, not a report.
Rate limits, pagination, errors and retries
| Topic | What the docs say |
|---|---|
| Rate limits | 600 requests per minute per endpoint and 1,200 per minute overall, enforced per ad account and per IP; Bulk job creation 10 requests per 10 seconds |
| Pagination | Cursor based (after / before, has_more); list endpoints do not return a total count |
| Idempotency | Send an Idempotency-Key on supported create endpoints and reuse the same key and body on retry |
| 429 | Back off and retry |
| 503 | Retry, but the request may have succeeded, so read the object first |
| 403 / 404 | Often a feature not enabled for the account, not a bad request |
| Versioning | Only /v1 exists; changes are tracked in a dated changelog (latest entry seen: October 26, 2026) |
| Sandbox / SDKs | No sandbox or official SDK is documented; examples use curl. validate_only exists on Bulk jobs and Conversions API requests |
What is still unclear or limited
- There is no published statement that every Ads Manager feature is available through the API, and some setup flows (hosted-URL and browser-upload product feeds) are Ads Manager only.
- Hotel campaigns, Bulk API, Delta Feeds and conversion bidding depend on per-account enablement.
- Custom audiences need at least 25,000 matched users for inclusion and bid multipliers; exclusion audiences have no minimum.
- OpenAI has not published API pricing; the docs describe no separate fee for API access beyond ad spend.
- The partner header rule is worded inconsistently across pages, as noted above.
Verdict: should you build on the OpenAI Ads API?
Use the API if you manage several ChatGPT Ads accounts, run product-feed campaigns that need frequent price or stock updates, or want ChatGPT Ads spend and conversions in your own dashboards or warehouse. Stay in Ads Manager if you run one or two campaigns: the API exposes the same objects, still sends every ad through review, and adds key management and retry logic you would have to maintain. A sensible middle path is to build campaigns in Ads Manager and use the API only for reporting through the insights endpoints, which are read-only and low risk.
FAQ
Is there an official OpenAI Ads API?
Yes. OpenAI documents it at developers.openai.com/ads with an overview, quickstart, API reference and OpenAPI spec. The base URL is https://api.ads.openai.com/v1.
How do I get an OpenAI Ads API key?
Create an Advertiser API key on the Settings page of your ChatGPT Ads Manager account. You need an ad account first; each key works with one ad account.
Can I use my normal OpenAI platform API key?
No. The Ads API uses an Advertiser API key from Ads Manager, and server-side conversion events use a separate Conversions API key.
Does the API cost extra?
OpenAI has not published any separate API fee. You pay for ad delivery under the same CPM, CPC or conversion bidding as in Ads Manager.
Can I create ChatGPT ads through the API without review?
No. Creating an ad submits its creative for review, and OpenAI notes that creation does not mean the ad has passed review or is ready to serve. Activation also does not guarantee delivery.
Get help with your ChatGPT Ads setup
Want a second pair of eyes on your ChatGPT Ads account, API integration or conversion tracking? Contact Seolign for a ChatGPT Ads setup or audit.
More ChatGPT Ads guides
- ChatGPT Ads: the complete guide
- ChatGPT Ads Manager vs API: which workflow fits
- OpenAI Ads Manager setup guide
- ChatGPT Ads cost and pricing
- How ChatGPT Ads targeting works
- Pixel and Conversions API deduplication
Last checked against official OpenAI sources on 14 November 2026. Featured image: photo by Chris Ried on Unsplash.
Pingback: ChatGPT Advertising: How ChatGPT Ads Work & How to Launch