System design · Platform introduction
How ChatGPT Ads works
What makes an ad fit a conversation, and what can you learn from the campaign report afterwards? Follow the path from what a person asks ChatGPT to what an advertiser can see and change.
On this page
Use this guide to
- Follow an ad from a conversation to the point where it might be shown.
- Find the settings and results available to advertisers.
- See how to collect and use campaign reports.
Access
No account or API key is needed for this guide.
The ad experience
OpenAI describes ChatGPT advertising around moments when people explore options, compare alternatives and make decisions in a conversation. That makes the surrounding task and context part of the starting point for understanding an ad’s relevance. ChatGPT advertiser overview
For an advertiser, the next questions are practical. Which settings can you change? Which actions can you measure? Which results can your software pull into a report?
Follow the path of an ad
This diagram shows how ChatGPT answers and how the ad system works alongside it. Solid boxes show steps OpenAI describes. Dashed boxes show how Harness proposes to collect and save reports. Sources reviewed 8 November 2026.
Stage 1 of 5
The ad can reach the chat screen in time. Count an impression once you know the ad was shown.
Scroll sideways to see the rest of the diagram →
- OpenAI · documentedOne exchange in chat
- OpenAI · documentedWrite the answer
- OpenAI · documentedChat screen
- OpenAI · documentedAd session tracks the chat
- OpenAI · documentedAd orchestrator
- OpenAI · documentedFind possible ads
- OpenAI · documentedCheck which ads qualify
- OpenAI · documentedScore possible ads
- OpenAI · documentedAd auction
- OpenAI · documentedAd blocked by check
- OpenAI · documentedFinal check for fit
- OpenAI · documentedAd and introduction
- OpenAI · documentedArrives too late to show
- OpenAI · documentedCheck arrival time
- OpenAI · documentedEvents and feedback
- OpenAI · documentedReporting API
- Harness · proposedSaved report data
- Harness · proposedReport collector
Arrows that point both ways show a request and its reply, or a tool the system can use again. The final check can stop an ad before it is sent. An ad that arrives late has already been sent and misses its chance to appear.
Example ad outcomes
- Eligible and on time. The ad can reach the chat screen in time. Count an impression once you know the ad was shown.
- Ad arrives too late. The ad system sends the ad, but it arrives too late for the chat to show it. No ad is shown in this exchange, so there is no impression to count. ChatGPT still answers.
- Final context check fails. The final check rejects the ad for this conversation before the system sends it to the chat screen. No ad appears, so there is no impression to count.
These examples use imagined situations to show how an ad can be chosen and still go unseen.
OpenAI documented · Simplified
1. How the answer and ad take separate paths
ChatGPT writes the answer separately from choosing an ad. The answer does not wait for an ad.
- What this means in practice
- If you add advertising to a product, keep the main feature usable even when the ad system is slow or unavailable.
- What to check
- Follow the top row from the conversation to the answer on screen.
OpenAI documented · Simplified
2. Find ads that could fit the conversation
The ad session keeps track of the conversation. An AI model called the orchestrator decides when to use tools that find, check and score possible ads. It can use a tool more than once.
- What this means in practice
- An ad can match what someone is looking for and still fail a check, for example if its campaign has run out of budget.
- What to check
- Follow the arrows between the orchestrator and the tools it can use.
OpenAI documented · Simplified
3. See when a selected ad appears
The auction chooses an ad and sets its price. A final check can stop it if it does not fit the conversation. An ad that passes the check can still arrive too late for the chat to show it.
- What this means in practice
- Keep separate records for when an ad is chosen, sent and shown. An impression counts an ad that was shown.
- What to check
- Try the example outcomes. Watch what happens to the ad while the answer carries on.
OpenAI documented · Simplified
4. Find the results advertisers can read
OpenAI describes recording events and collecting feedback. Its reporting API gives advertisers performance totals.
- What this means in practice
- Before using a report to make a decision, check which ads and dates it covers, what each number measures and when it was collected.
- What to check
- The diagram shows the event records and reporting API separately. The public description covers them as separate topics.
See what advertisers can do with the APIs
· How OpenAI records events and feedbackHarness proposal · Planned
5. See how you could collect reports
The dashed boxes show our plan for software that collects reports and saves the results, including which dates they cover and when they were collected.
- What this means in practice
- Decide how to split large requests, where to save the results and when to try again if a request fails.
- What to check
- Use the reporting case to see how your software can show which results are ready and which are missing.
What this diagram is based on
OpenAI describes what each part does. The diagram groups those parts to make the process easier to follow. The report collector and saved report data are part of a planned Harness build.
How ChatGPT looks for a relevant ad
The orchestrator is the AI model that decides which ad selection tools to use. Open each step to see what it starts with and what it produces. The model can go back to a tool when it needs to.
Source: OpenAI’s engineering account
The steps below describe work that happens inside OpenAI. Advertiser reports give you campaign results. See what advertisers can do with the APIs.
Work out what someone is looking for
Based on OpenAI’s description
Details from the conversationSearches for products or servicesThe orchestrator turns relevant details from the chat into searches for ads. It can revise those searches as the person’s goal becomes clearer.
- Harness example
- If someone asks for lightweight shoes for a rainy city break, the system might look for “water-resistant walking shoes” or “packable travel footwear”.
- What this means for advertisers
- Describe what your product actually helps people do. Test whether that message performs well. The system can look for related meanings as well as matching words.
Find ads with a similar meaning
Based on OpenAI’s description
Searches based on the chatPossible adsThe system turns the meaning of each search into a list of numbers called an embedding. It compares these numbers with those for ads in several searchable collections to find close matches quickly.
- Harness example
- In our example, one tool creates the numbers and another looks for matches. The numbers and search settings in the download are made up.
- What this means for advertisers
- Keep product details accurate and make sure the landing page matches the ad. The search that led to an individual ad stays inside the platform.
Check which ads qualify
Based on OpenAI’s description
Possible adsAds that pass the checksThe system can check whether the ad is active, fits the audience and placement, follows policy and has budget left. It can also spread spending over time (pacing) and remove repeated candidates.
- Harness example
- A walking shoe ad might fit a conversation about a trip, but the campaign might only run in France while the person is in Canada.
- What this means for advertisers
- If an ad rarely shows, check where it can run and whether the campaign has budget before rewriting the copy.
Score relevance and quality
Based on OpenAI’s description
Ads that qualifyAds with scoresThe system can score how well an ad fits the person’s goal, how likely people are to interact with it and how it performed before.
- Harness example
- Our example uses made-up scores between 0 and 1 so you can see what a scoring result might look like. OpenAI keeps its scoring rules and scores private.
- What this means for advertisers
- Compare versions of an ad with a test that you can explain. Click-through rate divides clicks by impressions and shows the result as a percentage. The platform’s own scores stay private.
Shortlist ads and run the auction
Based on OpenAI’s description
Ads that fit the chatAd choice and priceThe orchestrator shortlists ads. The auction decides which can compete, uses quality as part of the ranking, then picks the ad and sets the price.
- Harness example
- The download includes a made-up bid and price to show what an auction record could contain. Use OpenAI’s documentation for billing rules.
- What this means for advertisers
- Track what you bid and what you were charged separately. Use campaign results to assess performance. The reasons for an individual auction result stay private.
Check the fit and show the ad on time
Based on OpenAI’s description
Selected ad and current conversationAd blocked, sent or shownThe final check can stop an ad that feels out of place in the conversation. An ad can also pass the check and be sent, yet arrive too late to show.
- Harness example
- In our example, one record says whether the ad passed the final check. Another says whether it arrived late or was shown.
- What this means for advertisers
- Use impressions to count ads that were shown. Keep a timing problem separate from a decision to block an ad.
The conversation and the details of how individual ads were chosen stay inside the platform.
Ad system examples to download
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.
- Harness · example model · v1.0.0Example ad system rules · JSON Schema
Rules for the data in our example ad system. JSON Schema is a format for describing those rules. The tools, data fields and scoring examples are Harness design choices.
- Harness · made-up data · v1.0.0Example ad selection records · JSON
Made-up records show what could happen when ads are matched, auctioned, blocked or sent too late. Each record follows our example rules.
- 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.
What advertisers can set up and measure
- 01Configure campaigns & ads
- 02Show ads
- 03Record actions
- 04Review results
An ad account contains campaigns, campaigns contain ad groups, and ad groups contain ads. An API is how software sends a request to another system. The Advertiser API lets software manage campaigns and request reports. When you build a report, keep each campaign’s ID and settings alongside its results. Advertiser API and campaign structure
A measurement pixel is a small piece of website code that records actions. The Conversions API lets your server send records of actions such as purchases. Sending those records and requesting a campaign report are separate jobs. Measurement interfaces
An Ads API key is a secret your server uses to access a specific ad account. Using ChatGPT and getting advertiser API access are separate. Before connecting a live account, check that you have access and that the features you need are available. Advertiser API authentication
What the reports tell you
A report can show impressions, clicks and spend, for example by campaign and day. The reasons an ad was considered, scored or chosen for a particular conversation stay inside the platform.
Optimisation and evidence
Ask what the campaign aims to achieve, what you pay for and what the report measures. With conversion-optimised cost per click (CPC), the campaign aims for a chosen action, such as a purchase, and you pay for valid clicks. It requires an eligible ad account and conversion tracking. An order credited to an ad tells you how the platform counted it. To estimate how many extra sales the ad caused, you need a comparison. Conversion-optimised campaign requirements
Before changing a budget or ad, check what the report measures and whether more data may arrive. The measurement guides will look at how to use these results and how to estimate the extra sales a campaign caused, known as incrementality.
One platform across five tracks
The worked reporting case takes one request for daily campaign spend through the five tracks. It covers the contract, batch retrieval, recovery, interpretation, and how an agent can use the result.
Next · Worked example · Preview
How to collect ChatGPT Ads reports
Start with one reporting request and follow it across the five engineering tracks.
Read the reporting casePlatform sources
Official sources used in this guide. Check your own ad account for the features you can access.