ChatGPT sponsored ads schema - cloro

ChatGPT Endpoint

The ChatGPT endpoint returns sponsored ads in result.ads when you opt in with include.ads: true — no separate API call. For use cases, pricing context, and copy-paste examples, see the ChatGPT ads scraper page on the product site.

Result Ads

result.ads lists every ad OpenAI serves for the prompt; the interface renders at most one of them, so use the rendered field to tell which ad was actually shown. See Served vs shown below.

Example Request

{
  "prompt": "What are the best running shoes?",
  "model": "CHATGPT",
  "country": "US",
  "include": {
    "ads": true
  }
}

Ad Structure

Field	Type	Description
`brand`	object	Advertiser brand information (name, url, favicon)
`cards`	array	Array of carousel cards promoting products/services
`visibility`	string	OpenAI serving status: `allowed`, or `hidden` when the ad was filtered (for example, an integrity check)
`adsResponseIndex`	integer	The ad’s slot position in OpenAI’s served ad response (served order, not a guarantee of what was shown)
`rendered`	boolean	Whether the ad was shown as a visible card; `false` means served but not displayed

Brand Structure

Field	Type	Description
`name`	string	Advertiser brand name
`url`	string	Advertiser brand URL with attribution
`favicon`	string	Advertiser brand favicon URL (optional)

Card Structure

Field	Type	Description
`title`	string	Card title/heading
`body`	string	Card description text
`url`	string	Card destination URL with attribution
`image`	string	Card image URL (optional)

Served vs Shown

The served list can include ads the user never saw. Three fields let you measure real exposure:

rendered — true only for the ad shown as a visible card. Count rendered: true for user-visible impressions rather than the length of ads.
visibility — allowed for eligible ads; hidden marks ads OpenAI filtered (for example, an integrity check). A hidden ad is never shown.
adsResponseIndex — the served slot position. It reflects the order OpenAI returned the ads, not which one was shown. It is usually zero-based, as in the example below, but not guaranteed — a lone ad can arrive at a higher index (for example 2) — so treat it as an opaque position rather than a dense sequence.

rendered is derived from the response DOM at capture time. It reliably flags served-but-not-shown ads, but treat it as a strong signal rather than a guarantee — a rare late-painting render can be missed.

Response Example

{
  "success": true,
  "result": {
    "text": "Here are several running shoes...",
    "ads": [
      {
        "brand": {
          "name": "Acme Shoes",
          "url": "https://www.acmeshoes.com?utm_source=chatgpt.com",
          "favicon": "https://images.openai.com/favicon.ico"
        },
        "cards": [
          {
            "title": "Premium Running Shoes",
            "body": "Lightweight running shoes with cushioning technology",
            "url": "https://www.acmeshoes.com/running?utm_source=chatgpt.com",
            "image": "https://images.openai.com/product.jpg"
          },
          {
            "title": "Trail Running Shoes",
            "body": "Durable shoes designed for off-road running with strong grip",
            "url": "https://www.acmeshoes.com/trail?utm_source=chatgpt.com",
            "image": "https://images.openai.com/product2.jpg"
          }
        ],
        "visibility": "allowed",
        "adsResponseIndex": 0,
        "rendered": true
      },
      {
        "brand": {
          "name": "Trailblaze Gear",
          "url": "https://www.trailblazegear.com?utm_source=chatgpt.com",
          "favicon": "https://images.openai.com/favicon.ico"
        },
        "cards": [
          {
            "title": "All-Terrain Running Shoes",
            "body": "Grippy outsole built for mixed trails",
            "url": "https://www.trailblazegear.com/shoes?utm_source=chatgpt.com",
            "image": "https://images.openai.com/product3.jpg"
          }
        ],
        "visibility": "allowed",
        "adsResponseIndex": 1,
        "rendered": false
      }
    ]
  }
}