> ## Documentation Index
> Fetch the complete documentation index at: https://cloro.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Extract ChatGPT
> Extract structured data from ChatGPT about your any topic
## Overview
The ChatGPT endpoint extracts structured data from ChatGPT with features including shopping cards, brand entities, map entries, raw response data, and query fan-out. Useful for e-commerce tracking, local business monitoring, and detailed analysis.
**Web search enabled**
This endpoint automatically enables ChatGPT's web search mode for all requests, so responses include current information from the web with source citations.
## Unique features
* **[Sources](/api-reference/endpoint/chatgpt/sources)**: Sources include publication dates and footnote indicators for distinguishing primary from secondary references
* **[Shopping cards](/api-reference/endpoint/chatgpt/shopping-cards)**: Extracts structured product information with pricing, ratings, offers, and commercial details
* **[Inline products](/api-reference/endpoint/chatgpt/inline-products)**: Individual product references with pricing, offers, and rendering hints for inline display
* **[Entity extraction](/api-reference/endpoint/chatgpt/entities)**: Identifies and extracts named entities like products, brands, and concepts mentioned in responses
* **[Map entries](/api-reference/endpoint/chatgpt/map)**: Extracts business and place information including ratings, reviews, contact details, and location data
* **[Citation pills](/api-reference/endpoint/chatgpt/citation-pills)**: Captures inline citations with metadata including labels, descriptions, domains, and publication dates
* **[Ads](/api-reference/endpoint/chatgpt/ads)**: Extracts structured ad information including advertiser branding and product carousel cards
* **Raw response access**: Includes the full streaming response payload for debugging
* **Query fan-out insights**: Reveals the query fan-out ChatGPT used to generate responses
## Request parameters
Uses [common parameters](/guides/making-requests/sync#common-parameters). All ChatGPT-specific `include.*` flags are listed in the auto-generated request schema below.
**Additional credit cost**
Enabling any of `include.rawResponse`, `include.searchQueries`, `include.ads`, or `include.shopping` (or any combination) adds +2 credits to the base cost.
## Response objects
The response includes the following sections. See each subpage for the full schema and examples.
| Section | Description |
| ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| [Sources](/api-reference/endpoint/chatgpt/sources) | Source citations with publication dates and footnote indicators |
| [Shopping cards](/api-reference/endpoint/chatgpt/shopping-cards) | Structured product information with pricing, ratings, and offers |
| [Inline products](/api-reference/endpoint/chatgpt/inline-products) | Individual product references with rationale and themed reviews |
| [Entities](/api-reference/endpoint/chatgpt/entities) | Named entities like products, brands, and concepts |
| [Map entries](/api-reference/endpoint/chatgpt/map) | Business and place information from Yelp and Google |
| [Citation pills](/api-reference/endpoint/chatgpt/citation-pills) | Inline citations with rich metadata |
| [Ads](/api-reference/endpoint/chatgpt/ads) | Advertiser branding and product carousel cards |
## Response schema
Includes [common response fields](/guides/making-requests/sync#common-response-fields) plus:
| Field | Type | Description |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `result.rawResponse` | array | Array of ChatGPT's streamed response events. When `include.shopping` is also true, this additionally includes the `product_update` SSE events fetched for each inline product / shopping-card product (included when `include.rawResponse` is true) |
| `result.searchQueries` | array | Array of search model queries (fan-out queries) ChatGPT used internally to gather information (included when `include.searchQueries` is true) |
| `result.ads` | array | Array of [ads](/api-reference/endpoint/chatgpt/ads) displayed in ChatGPT response (included when `include.ads` is true) |
| `result.shoppingCards` | array | Array of [shopping/product cards](/api-reference/endpoint/chatgpt/shopping-cards) extracted from response (included when `include.shopping` is true) |
| `result.inlineProducts` | array | Array of [inline products](/api-reference/endpoint/chatgpt/inline-products) with pricing and offers (included when `include.shopping` is true) |
| `result.entities` | array | Array of [entities](/api-reference/endpoint/chatgpt/entities) extracted from response (when available) |
| `result.map` | array | Array of [business/place map entries](/api-reference/endpoint/chatgpt/map) extracted from response (when available) |
| `result.citationPills` | array | Array of [inline citation pills](/api-reference/endpoint/chatgpt/citation-pills) extracted from response (when available) |
| `result.sources` | array | Array of [sources](/api-reference/endpoint/chatgpt/sources) referenced in the response. See [Sources](/api-reference/endpoint/chatgpt/sources) for ChatGPT-specific fields |
| `result.model` | string | The ChatGPT model used to generate the response |
## Common questions
### Can I get the search queries that ChatGPT uses?
Yes, you can get the actual search queries (fan-out queries) that ChatGPT uses internally by setting `include.searchQueries: true` in your ChatGPT requests.
### Are query fan-outs available for all ChatGPT responses?
ChatGPT uses `gpt-5-3` and `gpt-5-3-mini` that include fan-out queries; newer models may not include explicit fan-outs. ChatGPT automatically selects which model to use for each request, so we cannot control the presence of query fan-outs.
### Are query fan-outs available for other providers?
For a complete comparison of query fan-out support across all providers, see the [Providers & pricing guide](/guides/providers#query-fan-out-support).
### Why is a fan-out query a single long string instead of separated keywords?
This is expected behaviour. ChatGPT's search model decides the shape of each fan-out query, and it often emits a single long natural-language query rather than a comma-separated keyword list. The length and structure vary between runs, even for the same prompt, and cloro returns the queries exactly as ChatGPT generates them without reformatting. Community write-ups such as [this LinkedIn post by Stefan Landwehr](https://www.linkedin.com/posts/landwehr_i-recently-wrote-about-how-chatgpt-fanout-activity-7421889498805891072-Ap9Q/) document the same behaviour.
### Why aren't shopping cards appearing in my responses?
Shopping cards only appear when the prompt is related to products or shopping:
```bash theme={null}
# ✅ Good - shopping related
"best laptops under $1000"
"compare iPhone vs Samsung"
"top rated headphones 2026"
# ❌ Bad - not shopping related
"what is the capital of France"
"how does photosynthesis work"
```
Not all shopping queries will return shopping cards. It depends on what ChatGPT finds and how it formats the response.
### Which providers support shopping cards?
For a complete comparison of shopping card support across all providers, see the [Providers & pricing guide](/guides/providers#shopping-cards-support).
### My non-English prompts are returning English fan-out queries. Is that expected?
Yes. When you submit a non-English prompt, ChatGPT may still generate some or all of its internal search queries (`result.searchQueries`) in English. A roughly 50/50 English/local-language split has been observed for non-English prompts. This is upstream ChatGPT behavior — cloro returns the queries exactly as ChatGPT generates them. If you're using fan-out for multilingual GEO monitoring, filter or group by query language as needed.
### What's the difference between shopping cards and inline products?
Shopping cards are grouped collections of products displayed together (like a carousel):
* Contain multiple products
* Include category tags
* For browsing multiple options
Inline products are individual product references:
* Single product per entry
* Include pricing, offers, images, and ratings
* Can be embedded inline in text, comparison tables, or featured displays
* Have rendering hints (inline, hero, block)
Both are extracted only when `include.shopping: true` is set in the request.
## OpenAPI
````yaml api-reference/openapi.json POST /v1/monitor/chatgpt
openapi: 3.1.0
info:
title: cloro
description: API for monitoring AI responses across different providers and regions
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.cloro.dev
description: Production server
security:
- bearerAuth: []
paths:
/v1/monitor/chatgpt:
post:
summary: Monitor ChatGPT Responses
description: Extract structured data from ChatGPT about your any topic
operationId: monitorChatgpt
requestBody:
description: Request parameters for monitoring ChatGPT responses
content:
application/json:
schema:
$ref: '#/components/schemas/ChatGPTMonitorRequest'
required: true
responses:
'200':
description: successful ChatGPT monitoring response
headers:
X-Concurrent-Limit:
description: Maximum number of concurrent requests allowed
schema:
type: integer
example: 10
X-Concurrent-Current:
description: Current number of concurrent requests
schema:
type: integer
example: 3
X-Concurrent-Remaining:
description: Number of remaining concurrent slots available
schema:
type: integer
example: 7
X-Credits-Remaining:
description: Number of credits remaining in user account
schema:
type: integer
example: 4
X-Credits-Charged:
description: Number of credits charged for this request
schema:
type: integer
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ChatGPTMonitorResponse'
'400':
description: Bad Request - Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'401':
description: Unauthorized - Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationError'
'403':
description: Forbidden - Insufficient permissions or credits
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Not Found - Route not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'409':
description: Conflict - Resource conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictError'
'429':
description: Too Many Requests
headers:
X-Concurrent-Limit:
description: Maximum number of concurrent requests allowed
schema:
type: integer
example: 10
X-Concurrent-Current:
description: Current number of concurrent requests
schema:
type: integer
example: 11
X-Concurrent-Remaining:
description: Number of remaining concurrent slots available
schema:
type: integer
example: 0
X-Credits-Remaining:
description: Number of credits remaining in user account
schema:
type: integer
example: 4
X-Credits-Charged:
description: Number of credits charged for this request
schema:
type: integer
example: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ConcurrentLimitError'
'499':
description: Client Closed Request - Request was canceled
content:
application/json:
schema:
$ref: '#/components/schemas/CanceledError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalError'
'502':
description: Bad Gateway - External service error
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalServiceError'
components:
schemas:
ChatGPTMonitorRequest:
required:
- prompt
- country
type: object
properties:
prompt:
description: The prompt to send to ChatGPT
type: string
minLength: 1
maxLength: 10000
example: What do you know about Acme Corp?
country:
description: Country/region code for localized response
type: string
example: US
include:
description: Optional flags for including additional response formats
type: object
default:
html: false
markdown: false
rawResponse: false
searchQueries: false
ads: false
shopping: false
properties:
html:
description: Include a URL to the full HTML of the response
type: boolean
default: false
example: true
markdown:
description: Include markdown-formatted response in the result
type: boolean
default: false
example: true
rawResponse:
description: Include ChatGPT's raw response payload
type: boolean
default: false
example: true
searchQueries:
description: Include the query fan-out ChatGPT used to generate the response
type: boolean
default: false
example: true
ads:
description: Include ads displayed in ChatGPT response
type: boolean
default: false
example: true
shopping:
description: >-
Include shopping cards and inline products with pricing and
offers. Adds +2 credits to the base cost (shared with
rawResponse, searchQueries, and ads — enabling any one or any
combination adds the same +2).
type: boolean
default: false
example: true
required: []
example:
html: true
markdown: true
rawResponse: true
searchQueries: true
ads: true
shopping: true
additionalProperties: false
state:
$ref: '#/components/schemas/StateParameter'
additionalProperties: false
ChatGPTMonitorResponse:
required:
- success
- result
type: object
properties:
success:
type: boolean
example: true
result:
description: ChatGPT's response data
type: object
properties:
text:
type: string
description: ChatGPT's response text
example: >-
The name "Acme Corporation" is used in various contexts, both
fictional and real. Here's an overview:
🐾 Acme Corporation in Fiction
The Acme Corporation is a fictional company featured prominently
in Warner Bros. cartoons, particularly the Road Runner/Wile E.
Coyote series.
sources:
type: array
description: >-
Array of sources referenced in the response. Returns empty array
when no sources are available.
items:
type: object
properties:
position:
type: number
description: The position index of the source in the response
example: 1
url:
type: string
description: The URL of the source
example: >-
https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com
label:
type: string
description: The article title of the source
example: 12 Best AI Recruiting Tools For HR in 2025
description:
type: string
description: A snippet or summary of the source content
example: >-
Discover the top AI recruiting tools that can help HR
professionals streamline their hiring process...
footnote:
type: boolean
description: >-
Whether this source appears as a footnote (in a subsequent
list in the sources modal)
example: false
datePublished:
type: string
description: >-
The publication date of the source. Omitted from the
response when the source has no publish date — never
emitted as `null`.
example: May 22, 2025
example:
- position: 1
url: >-
https://www.rippling.com/blog/ai-recruiting?utm_source=chatgpt.com
label: 12 Best AI Recruiting Tools For HR in 2025
description: >-
Discover the top AI recruiting tools that can help HR
professionals streamline their hiring process...
footnote: false
datePublished: May 22, 2025
- position: 2
url: >-
https://www.index.dev/blog/ai-recruiting-software-hiring-managers?utm_source=chatgpt.com
label: 7 Best AI Recruiting Software for Hiring Managers in 2025
description: >-
A comprehensive guide to the best AI recruiting software
options available for hiring managers...
footnote: false
datePublished: April 10, 2025
- position: 3
url: >-
https://www.selectsoftwarereviews.com/buyer-guide/ai-recruiting?utm_source=chatgpt.com
label: >-
10+ Best AI Recruiting Software for 2025: Expert Reviews +
Pricing
description: >-
Expert reviews and pricing information for the best AI
recruiting software solutions...
footnote: true
html:
type: string
format: uri
description: >-
A URL to the full HTML of the response (included when
include.html is true)
example: >-
https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html
markdown:
type: string
description: >-
ChatGPT's response formatted in Markdown (included when
include.markdown is true)
example: >-
The name "Acme Corporation" is used in various contexts, both
fictional and real. Here's an overview:
🐾 Acme Corporation in Fiction
The Acme Corporation is a fictional company featured prominently
in Warner Bros. cartoons, particularly the Road Runner/Wile E.
Coyote series.
rawResponse:
type: array
description: >-
Array of streaming events returned by ChatGPT (included when
include.rawResponse is true)
items:
type: object
properties:
type:
type: string
description: Event type identifier
token:
type: string
description: Resume token used to continue the ChatGPT conversation
conversation_id:
type: string
description: ChatGPT conversation identifier
message:
type: object
description: Event payload describing the assistant message
properties:
id:
type: string
role:
type: string
model:
type: string
delta:
type: object
description: Streaming delta payload from ChatGPT
properties:
content:
type: array
items:
type: object
properties:
type:
type: string
text_delta:
type: string
reason:
type: string
description: Why ChatGPT stopped streaming
example:
- type: resume_conversation_token
token: eyJhbGciOiJFUzI1Ni...WaVoqQ
conversation_id: 68efc64b-2d74-8012-b87d-28e59f3b8a49
- type: message_start
message:
id: msg_01JD6Q7H1ZKWM9GD34V5ZW1TYM
role: assistant
model: gpt-5
- type: message_delta
delta:
content:
- type: output_text_delta
text_delta: >-
The name "Acme Corporation" is used in various
contexts...
- type: message_stop
reason: end_turn
searchQueries:
type: array
description: >-
Array of query fan-out ChatGPT used to generate the response
(included when include.searchQueries is true)
items:
type: string
example:
- What is Acme Corporation?
- Acme Corp company overview
- Acme Corporation products and services
model:
type: string
description: The ChatGPT model used to generate the response
example: gpt-5
shoppingCards:
type: array
description: >-
Array of shopping/product cards extracted from the response. The
field is omitted entirely from `result` when `include.shopping`
is `false` or unset — clients should treat it as optional rather
than expecting an empty array.
items:
type: object
properties:
tags:
type: array
description: Category tags for the shopping card
items:
type: string
example:
- stylish casual leather sneaker
- heritage retro leather sneaker
products:
type: array
description: Array of product information
items:
type: object
properties:
title:
type: string
description: Product name
example: Adidas VL Court 3.0
position:
type: integer
description: >-
1-indexed rank across all products in all shopping
cards in the response (flat, not reset per card).
example: 1
url:
type: string
description: Product page URL with ChatGPT attribution
example: >-
https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com
price:
type: string
description: Current price
example: $57.00
featured_tag:
type: string
description: Product category or style tag
example: stylish casual leather sneaker
merchant:
type: string
description: Merchant information
example: adidas + others
image_urls:
type: array
description: Array of product image URLs
items:
type: string
example:
- https://images.openai.com/static-rsc-1/example.jpg
rating:
type: number
description: Product rating (0-5 scale)
example: 4.7
num_reviews:
type: integer
description: Number of reviews
example: 10394
id:
type: string
description: Unique product identifier
example: '3250714974047560249'
offers:
type: array
description: Array of shopping offers from different merchants
items:
type: object
properties:
merchant_name:
type: string
description: Merchant name
example: adidas
product_name:
type: string
description: Product name as listed by merchant
example: Adidas Women's VL Court 3.0
url:
type: string
description: Offer URL with ChatGPT attribution
example: >-
https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com
price:
type: string
description: Offer price
example: $57.00
details:
type: string
description: Stock and delivery information
example: >-
In stock online and nearby, Delivery between
Sat - Mon $4.99
available:
type: boolean
description: Offer availability status
example: true
checkoutable:
type: boolean
description: Whether offer can be checked out directly
example: false
price_details:
type: object
description: Detailed price breakdown
properties:
base:
type: string
description: Base product price
example: $57.00
total:
type: string
description: Total price including any additional costs
example: $57.00
tag:
type: object
description: Promotional tag
properties:
text:
type: string
description: Tag text
example: Best price
rating_grouped_citation:
type: object
description: Rating source information
properties:
title:
type: string
description: Source title
example: Adidas Women's VL Court 3.0
url:
type: string
description: Source URL
example: >-
https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html
supporting_websites:
type: array
description: Array of supporting website references
items:
type: object
properties:
title:
type: string
description: Website title
example: Adidas Women's VL Court 3.0
url:
type: string
description: Website URL
example: >-
https://www.macys.com/shop/product/adidas-womens-vl-court-3.0-casual-sneakers-from-finish-line?ID=21107988&pla_country=US&CAGPSPN=pla
example:
- tags:
- stylish casual leather sneaker
- heritage retro leather sneaker
products:
- title: Adidas VL Court 3.0
url: >-
https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com
price: $57.00
featured_tag: stylish casual leather sneaker
merchant: adidas + others
image_urls:
- https://images.openai.com/static-rsc-1/example.jpg
rating: 4.7
num_reviews: 10394
id: '3250714974047560249'
offers:
- merchant_name: adidas
product_name: Adidas Women's VL Court 3.0
url: >-
https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html?utm_source=chatgpt.com
price: $57.00
details: >-
In stock online and nearby, Delivery between Sat -
Mon $4.99
available: true
checkoutable: false
price_details:
base: $57.00
total: $57.00
tag:
text: Best price
rating_grouped_citation:
title: Adidas Women's VL Court 3.0
url: >-
https://www.adidas.com/us/vl-court-3.0-shoes/ID8797.html
supporting_websites:
- title: Adidas Women's VL Court 3.0
url: >-
https://www.macys.com/shop/product/adidas-womens-vl-court-3.0-casual-sneakers-from-finish-line?ID=21107988&pla_country=US&CAGPSPN=pla
inlineProducts:
type: array
description: >-
Array of inline products with pricing and offers. The field is
omitted entirely from `result` when `include.shopping` is
`false` or unset — clients should treat it as optional rather
than expecting an empty array.
items:
$ref: '#/components/schemas/InlineProduct'
entities:
type: array
description: Array of entities extracted from the response (when available)
items:
type: object
properties:
type:
type: string
description: Entity type identifier
example: product
name:
type: string
description: Entity name
example: adidas Grand Court Lo
required:
- type
- name
example:
- type: product
name: adidas Grand Court Lo
- type: product
name: Reebok Club C 85 Vintage
- type: product
name: Nike Dunk Low Retro SE
map:
type: array
description: >-
Array of business/place map entries extracted from the response
(when available). Items come from ChatGPT's enriched providers
(Yelp, Google Business) and use camelCase field names. The full
field set is documented at /api-reference/endpoint/chatgpt/map;
only the most commonly populated fields are listed here.
items:
type: object
properties:
id:
type: string
description: Business ID (Yelp ID or Google Place ID)
example: rVKID2OBQMyVpraqSjz9sg
provider:
type: string
description: 'Data provider: "yelp", "b1"/"b3" (Google), or "yelp-feed"'
example: yelp
name:
type: string
description: Business name
example: Blue Bottle Coffee
position:
type: integer
description: Position/ranking in results (added by parser)
example: 1
address:
type: string
description: Full street address
example: 66 Mint St, San Francisco, CA 94103
latitude:
type: number
description: GPS latitude coordinate
example: 37.7811
longitude:
type: number
description: GPS longitude coordinate
example: -122.4076
categories:
type: array
description: Business categories
items:
type: string
example:
- Coffee shop
rating:
type: number
description: Business rating (0-5 scale)
example: 4.5
reviewCount:
type: integer
description: Number of reviews
example: 1234
description:
type: string
description: Business description
example: >-
Specialty coffee roaster known for their meticulous
pour-over preparations
phone:
type: string
description: Contact phone number
example: +1-415-555-0123
websiteUrl:
type: string
format: uri
description: Business website URL
example: https://bluebottlecoffee.com
example:
- id: rVKID2OBQMyVpraqSjz9sg
provider: yelp
name: Blue Bottle Coffee
position: 1
address: 66 Mint St, San Francisco, CA 94103
latitude: 37.7811
longitude: -122.4076
categories:
- Coffee shop
rating: 4.5
reviewCount: 1234
description: >-
Specialty coffee roaster known for their meticulous
pour-over preparations
phone: +1-415-555-0123
websiteUrl: https://bluebottlecoffee.com
citationPills:
type: array
description: >-
Array of inline citation pills extracted from the response (when
available). These are citations that appear inline within the
text. Each entry is one (pill, source) pair; group by
`citationPillId` to recover pill-level structure.
items:
type: object
required:
- label
- citationPillId
- url
- domain
- type
- position
properties:
url:
type: string
format: uri
description: The URL of the citation
example: https://example.com/article
label:
type: string
description: >-
Per-source title of the citation. Always present; may be
an empty string when the citation event ships no title —
read `domain` / `url` for source identity in that case.
example: Example Article Title
description:
type: string
description: >-
Description of the citation content. Omitted when the
citation event carries no snippet (e.g. grouped-webpage
title-only cards).
example: A detailed description of the cited content
domain:
type: string
description: Domain of the citation source
example: example.com
datePublished:
type: string
description: >-
ISO 8601 date string of when the source was published.
Omitted when the citation event carries no publication
date.
example: '2025-01-01'
citationPillId:
type: integer
description: >-
0-based identifier shared by all entries from the same
chip. Group by `citationPillId` to recover the pill-level
structure. **Note:** unlike the other providers (Google
AIO, AI Mode, Copilot, Perplexity, Gemini) which use
1-based `citationPillId`, ChatGPT's IDs start at 0 for
historical reasons.
example: 0
type:
type: string
enum:
- searchResult
- groupedWebpage
description: >-
Discriminator for the underlying citation event:
`searchResult` for inline search citations,
`groupedWebpage` for grouped-webpage cards.
example: searchResult
position:
type: integer
description: >-
1-based position of this source in the sibling
`result.sources` array.
example: 1
example:
- url: https://example.com/article
label: Example Article Title
description: A detailed description of the cited content
domain: example.com
datePublished: '2025-01-01'
citationPillId: 0
type: searchResult
position: 1
ads:
type: array
description: >-
Array of ads displayed in ChatGPT response (included when
include.ads is true)
items:
type: object
properties:
brand:
type: object
description: Advertiser brand information
properties:
name:
type: string
description: Advertiser brand name
example: Acme Shoes
url:
type: string
format: uri
description: Advertiser brand URL
example: https://www.acmeshoes.com?utm_source=chatgpt.com
favicon:
type: string
format: uri
description: Advertiser brand favicon URL
example: https://images.openai.com/favicon.ico
required:
- name
- url
cards:
type: array
description: Array of carousel cards in the ad
items:
type: object
properties:
title:
type: string
description: Card title
example: Premium Running Shoes
body:
type: string
description: Card description text
example: >-
Lightweight performance running shoes with advanced
cushioning technology
url:
type: string
format: uri
description: Card destination URL
example: >-
https://www.acmeshoes.com/running?utm_source=chatgpt.com
image:
type: string
format: uri
description: Card image URL
example: https://images.openai.com/product.jpg
required:
- title
- body
- url
required:
- brand
- cards
example:
- 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 performance running shoes with advanced
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
superior grip
url: https://www.acmeshoes.com/trail?utm_source=chatgpt.com
image: https://images.openai.com/product2.jpg
ValidationError:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Request validation failed
details:
type: array
items:
type: object
properties:
field:
type: string
example: prompt
message:
type: string
example: Prompt cannot be empty
AuthenticationError:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- MISSING_API_KEY
- INVALID_API_KEY_FORMAT
- INVALID_OR_EXPIRED_API_KEY
example: MISSING_API_KEY
message:
type: string
example: Missing or invalid API key
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
ForbiddenError:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- INSUFFICIENT_PERMISSIONS
- INSUFFICIENT_CREDITS
example: INSUFFICIENT_PERMISSIONS
message:
type: string
example: Insufficient permissions
details:
type: object
properties:
requiredScopes:
type: array
items:
type: string
example:
- read:monitor
- write:monitor
required: []
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
NotFoundError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: RESOURCE_NOT_FOUND
message:
type: string
example: Route not found
details:
type: object
properties:
id:
type: string
example: /v1/invalid-endpoint
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
ConflictError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: RESOURCE_CONFLICT
message:
type: string
example: Resource conflict
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
ConcurrentLimitError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: CONCURRENT_LIMIT_EXCEEDED
message:
type: string
example: Concurrent limit exceeded
details:
type: object
properties:
limit:
type: number
example: 10
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
CanceledError:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Request was canceled
InternalError:
type: object
oneOf:
- properties:
success:
type: boolean
example: false
error:
type: string
example: Maximum retries exceeded
- properties:
error:
type: object
properties:
code:
type: string
example: INTERNAL_SERVER_ERROR
message:
type: string
example: Internal server error
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
ExternalServiceError:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: EXTERNAL_SERVICE_ERROR
message:
type: string
example: 'External service error: OpenAI'
details:
type: object
properties:
service:
type: string
example: OpenAI
timestamp:
type: string
format: date-time
example: '2025-01-15T12:00:00.000Z'
StateParameter:
description: >-
State code for sub-country geo-targeting (e.g., "CA"). Only valid with
country "US".
type: string
example: CA
minLength: 2
maxLength: 2
pattern: ^[A-Z]{2}$
InlineProduct:
type: object
description: >-
Inline product reference that appeared in the response text, including
pricing and offers
properties:
product:
$ref: '#/components/schemas/ShoppingProduct'
render_as:
type: string
description: How the product is rendered in the response
enum:
- inline
- hero
- block
example: hero
details:
type: object
description: Product rationale and reviews fetched from sidebar API
properties:
rationale:
type: object
properties:
rationale:
type: string
description: AI-generated rationale for recommending this product
citations:
type: array
description: Citations supporting the rationale
items:
type: object
reviews:
type: object
properties:
summary:
type: string
description: Summary of product reviews
reviews:
type: array
items:
$ref: '#/components/schemas/ProductReview'
ShoppingProduct:
type: object
description: Individual product information
properties:
title:
type: string
description: Product name
example: Nike Court Vision Low Next Nature Shoes
position:
type: integer
description: >-
1-indexed rank across all products in all shopping cards in the
response (flat, not reset per card).
example: 1
url:
type: string
description: Product page URL
example: >-
https://www.amazon.in/Nike-Court-Vision-Shoes/dp/B098F6QPLK?utm_source=chatgpt.com
description:
type: string
description: Product description
example: Classic sneaker with modern comfort features
price:
type: string
description: Current price
example: $79.99
featured_tag:
type: string
description: Product category or style tag
example: stylish casual leather sneaker
rating:
type: number
description: Product rating (0-5)
example: 4.5
num_reviews:
type: integer
description: Number of reviews
example: 8703
image_urls:
type: array
description: Product image URLs
items:
type: string
id:
type: string
description: Product identifier
example: prod_12345
variants:
description: Product variants (size, color, etc.)
offers:
type: array
description: Shopping offers with pricing details from different merchants
items:
$ref: '#/components/schemas/ShoppingOffer'
rating_grouped_citation:
$ref: '#/components/schemas/RatingGroupedCitation'
provider:
type: string
description: Data provider identifier
example: deprecated
providers:
type: array
description: List of data providers
items:
type: string
example:
- product_info
product_lookup_key:
type: object
description: Key used to look up product updates
properties:
data:
type: string
description: JSON-encoded product lookup data
product_lookup_data:
type: object
description: Structured product lookup query data
properties:
request_query:
type: string
description: Search query used for this product
all_ids:
type: object
description: Provider-to-ID mapping
additionalProperties:
type: array
items:
type: string
metadata_sources:
type: array
items:
type: string
showcase_metadata:
$ref: '#/components/schemas/ShowcaseMetadata'
show_price_disclosure:
type: boolean
description: Whether to show price disclosure
example: false
analytics_meta:
type: object
description: Analytics metadata
properties:
product_event_uuid:
type: string
description: UUID for product analytics event
metadata_sources:
type: array
description: Sources of product metadata
items:
type: string
example:
- p2
product_event_uuid:
type: string
description: UUID for product event tracking
generatedProductQuery:
type: string
description: >-
Broad shopping query ChatGPT generated for this product (extracted
from product_lookup_key.data). Useful for understanding the search
intent behind the recommendation.
example: best microwaves uk 2026 countertop inverter combi microwave
ProductReview:
type: object
description: Individual product review extracted from sources
properties:
source:
type: string
description: Review source
example: Amazon
theme:
type: string
description: Review theme or aspect
example: Ease of Use
summary:
type: string
description: Review summary text
sentiment:
type: string
description: Review sentiment
enum:
- positive
- neutral
- negative
cite:
type: string
description: Citation reference
nullable: true
rating:
type: number
description: Source rating
nullable: true
num_reviews:
type: integer
description: Number of reviews at source
nullable: true
cite_url:
type: string
description: Citation URL
nullable: true
ShoppingOffer:
type: object
description: Shopping offer with pricing details from a specific merchant
properties:
merchant_name:
type: string
description: Merchant name
example: Amazon.in
merchant_subtitle:
type: string
description: Merchant subtitle or additional info
nullable: true
product_name:
type: string
description: Product name as listed by merchant
example: Nike Men's Court Vision Low Next Nature Shoes
url:
type: string
description: Offer URL with attribution
example: https://www.amazon.in/dp/B098F6QPLK?utm_source=chatgpt.com
price:
type: string
description: Offer price
example: $79.99
details:
type: string
description: Stock and delivery information
example: In stock online, Free delivery
original_price:
type: string
description: Original price before discount
nullable: true
available:
type: boolean
description: Whether the product is available
example: true
checkoutable:
type: boolean
description: Whether the product can be checked out directly
example: false
is_digital:
type: boolean
description: Whether this is a digital product
nullable: true
checkout_payload:
type: string
description: Checkout payload data
nullable: true
checkout_image_urls:
type: array
description: Image URLs for checkout display
items:
type: string
nullable: true
shop_id:
type: string
description: Shop identifier
nullable: true
provider:
type: string
description: Data provider identifier
example: p2
price_details:
$ref: '#/components/schemas/PriceDetails'
tag:
$ref: '#/components/schemas/OfferTag'
RatingGroupedCitation:
type: object
description: Rating source information with supporting websites
properties:
title:
type: string
description: Source title
example: Nike Men's Court Vision Low Next Nature Shoes
url:
type: string
description: Source URL
example: https://www.amazon.in/dp/B098F6QPLK
supporting_websites:
type: array
description: Array of supporting website references
items:
type: object
ShowcaseMetadata:
type: object
description: >-
Visual showcase metadata attached to a shopping product (image,
background, and per-slot placement).
properties:
image:
$ref: '#/components/schemas/ShowcaseImage'
background:
$ref: '#/components/schemas/ShowcaseBackground'
slots:
type: object
description: Slot map keyed by slot identifier
additionalProperties:
$ref: '#/components/schemas/ShowcaseSlot'
debug:
type: object
description: Free-form debug metadata; opaque to clients
additionalProperties: true
PriceDetails:
type: object
description: Detailed price breakdown for an offer
properties:
display_price:
type: string
description: Formatted display price
nullable: true
base:
type: string
description: Base product price
example: $79.99
shipping:
type: string
description: Shipping cost
nullable: true
tax:
type: string
description: Tax amount
nullable: true
total:
type: string
description: Total price
example: $79.99
OfferTag:
type: object
description: Promotional tag on an offer
properties:
text:
type: string
description: Tag text
example: Best price
tooltip:
type: string
description: Tag tooltip text
nullable: true
ShowcaseImage:
type: object
description: Image rendered as the hero of a product showcase
properties:
url:
type: string
width:
type: number
height:
type: number
required:
- url
ShowcaseBackground:
type: object
description: Background styling for a product showcase
properties:
type:
type: string
primary:
type: string
secondary:
type: string
ShowcaseSlot:
type: object
description: Single visual slot inside a product showcase
properties:
fit:
type: string
position:
$ref: '#/components/schemas/ImagePosition'
zoom:
type: number
placement:
$ref: '#/components/schemas/SlotPlacement'
imageBlendMode:
type: string
ImagePosition:
type: object
description: Pixel offset for image positioning within a slot
properties:
x:
type: number
'y':
type: number
required:
- x
- 'y'
SlotPlacement:
type: object
description: Percent-based placement of a showcase slot within its container
properties:
leftPercent:
type: number
topPercent:
type: number
widthPercent:
type: number
heightPercent:
type: number
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````