System design · Advertiser API guide
ChatGPT Ads APIs for advertisers
Use this map to find the tool for your task. An API is how your software asks a platform for data or sends it instructions. ChatGPT Ads has separate tools for changing ad settings, sending records of actions like purchases and reading campaign results.
On this page
Use this guide to
- Find the right API for the job you want to do.
- Check what data you can send or receive.
- See what access each tool requires.
Access
No account or API key is needed for this guide.
What advertisers can do
OpenAI advertiser APIs · Guide by Harness · Reviewed 2026-11-08
The arrows show where data goes. This map is based on OpenAI’s documentation. Live account checks are planned.
01 · Advertiser task
Set up campaigns and ads
Your software → Campaign settings
Change the settings the ad system uses to choose and show ads.
- API to use
Create, read, update or delete campaigns, ad groups and ads through api.ads.openai.com/v1
- Data available
- IDs, status, budgets and bids. Context hints (context_hints) describe situations where an ad may be relevant. Creative fields include the title, ad text and destination link (creative.title, creative.body and creative.target_url).
- What to watch for
- You can change advertiser settings. Conversation details, ranking scores and individual auction results stay inside the platform.
- Access
- Keep the Advertiser API key on your server. The key gives your software access to a specific ad account. Some features require separate access.
02 · Advertiser task
Send records of conversions
Your server → OpenAI’s measurement system
Send a record when someone takes an action you track, such as placing an order.
- API to use
POST https://bzr.openai.com/v1/events?pid=<PIXEL-ID>
- Data available
- Send an event ID, the type of action, the time in milliseconds (timestamp_ms), permitted details for matching and other information about the action. The API responds with information about the submission.
- What to watch for
- Accepting a record, giving an ad credit for the action and finding out whether the ad caused an extra sale are three separate things. To avoid counting an action twice when you send it from both your website and server, use the same event ID and Pixel ID.
- Access
- You need a Pixel ID, which identifies the measurement setup, and a Conversions API key. Get them through Ads Manager or an approved partner setup.
03 · Advertiser task
Get performance reports
OpenAI’s reporting API → Your software
Request totals such as impressions, clicks and spend for the account, campaigns or ads you choose.
- API to use
GET /ad_account/insightsGET /campaigns/{campaign_id}/insightsGET /ad_groups/{ad_group_id}/insightsGET /ads/{ad_id}/insightsPOST /conversions/insights
- Data available
- Results grouped by account, campaign, ad group or ad and by time period. Conversion reports have their own definitions and limits.
- What to watch for
- General Insights can send a report in batches. A conversion report that is too large needs smaller requests. The reporting example shows how to handle each.
- Access
- Keep the Advertiser API key on your server and check your account has the reporting features you need. Add the paths above to https://api.ads.openai.com/v1.
How to read the internal tools in our examples
OpenAI describes how its system finds, checks and ranks ads before an auction. The exact messages those parts exchange are private. Names like prepare_queries, embed and final_gate belong to our example of how a system like this might work. OpenAI engineering account
API documentation and downloads
Use OpenAI’s documentation for the exact requests your software can send. The Harness downloads use made-up examples to explain how you might model ad selection or collect reports.
- OpenAI · official · externalOpenAI Ads OpenAPI specification
OpenAI’s file listing the requests its advertiser API accepts and the data it returns. OpenAPI is the format used to describe those rules.
- Harness · guide · v1.0.0Advertiser API map · JSON
The map on this page in JSON, a text format software can read. It includes links to OpenAI’s documentation.
- Harness · reference · v1.0.0Agent reference notes
See where the files came from, how they fit together and how to use them with a coding agent.
Platform sources
Official sources used in this guide. Check your own ad account for the features you can access.