--- title: "Track ChatGPT answers" method: POST path: "/v1/monitor/chatgpt" --- # Track ChatGPT answers `POST /v1/monitor/chatgpt` ## Request - Base URL: `https://api.answerline.dev` - URL: `https://api.answerline.dev/v1/monitor/chatgpt` - Auth: HTTP bearer Get structured output from ChatGPT for any prompt in supported regions: the answer, its cited sources, ads, shopping cards and brand entities ## Request body - ChatGPTMonitorRequest - `prompt` string, required: Prompt submitted to ChatGPT. ChatGPT takes up to 2,000 characters; a longer prompt is refused with a 400. - `country` string, required: Code of the country or region used to localize the response - `include` object: Flags that add extra output formats to the response (optional) - `html` boolean: Not available for ChatGPT, so `true` is refused with a validation error. - `markdown` boolean: Add a markdown version of the response to the result - `rawResponse` boolean: Return the answer as normalized stream events. For the engine's answer as received, use `include.rawWire`. - `searchQueries` boolean: Return the fan-out queries ChatGPT issued while producing the response (empty on the answers served today) - `ads` boolean: Return ads that ChatGPT shows in its response (empty on the answers served today) - `shopping` boolean: Return shopping cards plus products shown inline, with their prices and offers. Free. On the answers served today `shoppingCards` is empty and `inlineProducts` holds the products from ChatGPT's shopping search. - `rawWire` boolean: Return the engine's upstream answer as received in result.rawWire: the answer stream, or the provider's answer record, without the provider's billing data and account traces. Free. See https://answerline.dev/docs/output-formats#raw-wire - `legacy` boolean: Accepted for compatibility with clients that ask for ChatGPT's older desktop interface. Not served yet: the answer arrives in the same shape whatever its value. Default: false. - `disableWebSearch` boolean: Accepted for compatibility. On every answer served today ChatGPT decides by itself whether to search the web, whatever this value, and `result.provenance.searchMode` records `engine-default`. Default: false. - `state` string: State code for targeting below the country level (e.g., "CA"; "DC" included). Allowed only when country is "US". Served for Gemini; on a model that cannot place a state yet, a request that includes it is rejected as a validation error and is not charged. ## Response `200` ChatGPT monitoring result (success) - ChatGPTMonitorResponse - `success` boolean, required - `result` object, required: Data from ChatGPT's reply - `text` string: Text of ChatGPT's reply - `sources` object[]: Sources the response cites; an empty array if there are none. - `position` number: Where the source sits in the response, as an index - `url` string: Link to the source - `label` string: Title of the source article - `description` string: Excerpt or short summary taken from the source - `footnote` boolean: True if the source is shown as a footnote, i.e. in a later list inside the sources modal - `datePublished` string: Date the source was published. If the source has no such date, the field is left out entirely rather than set to `null`. - `html` string, uri: Link to the response's complete HTML (present when include.html is true) - `markdown` string: ChatGPT's reply as Markdown; returned only if include.markdown is true - `rawResponse` object[]: Raw ChatGPT response chunks exactly as received, without processing (returned only if include.rawResponse is true) - `type` string: Identifier of the event's type - `token` string: Token for picking the ChatGPT conversation back up - `conversation_id` string: Identifier of the ChatGPT conversation - `message` object: Payload of the event that describes the assistant's message - `id` string - `role` string - `model` string - `delta` object: Delta payload streamed by ChatGPT - `content` object[] - `type` string - `text_delta` string - `reason` string: Reason ChatGPT ended the stream - `searchQueries` string[]: The fan-out queries ChatGPT issued while producing the response (present when include.searchQueries is true) - `model` string, nullable: ChatGPT model that produced the answer. Empty when the response came through OpenAI's mobile-web format. - `shoppingCards` object[]: Shopping/product cards parsed from the response. When `include.shopping` is `false` or not set, `result` does not contain this field at all, so treat it as optional instead of relying on an empty array. - `tags` string[]: Tags naming the shopping card's categories - `products` object[]: List of product details - `title` string: Product name - `position` integer: Rank starting at 1, counted over every product in every shopping card of the response (one continuous sequence that does not restart for each card). - `url` string: Product page link carrying ChatGPT attribution - `price` string: Current price - `featured_tag` string: Style or category tag for the product - `merchant` string: Merchant information - `image_urls` string[]: URLs of the product's images - `rating` number: Rating of the product, on a 0-5 scale - `num_reviews` integer: Review count - `id` string: Identifier unique to the product - `offers` object[]: Offers for the product from various merchants - `merchant_name` string: Merchant name - `product_name` string: Product title as the merchant lists it - `url` string: Offer link carrying ChatGPT attribution - `price` string: Offer price - `details` string: Availability and delivery details - `available` boolean: Stock/availability status of the offer - `checkoutable` boolean: True if the offer supports direct checkout - `price_details` object: Itemized breakdown of the price - `base` string: Base price of the product - `total` string: Overall price with all extra charges added - `tag` object: Promotional tag - `text` string: Tag text - `rating_grouped_citation` object: Details about where the rating comes from - `title` string: Source title - `url` string: Source URL - `supporting_websites` object[]: Websites cited in support - `title` string: Website title - `url` string: Website URL - `inlineProducts` InlineProduct[]: Products shown inline, with their prices and offers. When `include.shopping` is `false` or not set, `result` does not contain this field at all, so treat it as optional instead of relying on an empty array. - `product` ShoppingProduct: Details for a single product - `title` string: Product name - `position` integer: Rank starting at 1, counted over every product in every shopping card of the response (one continuous sequence that does not restart for each card). - `url` string: URL of the product page - `description` string: Product description - `price` string: Current price - `featured_tag` string: Style or category tag for the product - `rating` number: Rating of the product (0-5) - `num_reviews` integer: Review count - `image_urls` string[]: URLs of the product images - `id` string: Product identifier - `variants` unknown - `offers` ShoppingOffer[]: Offers from several merchants, each with price details - `merchant_name` string: Merchant name - `merchant_subtitle` string, nullable: Subtitle or extra details for the merchant - `product_name` string: Product title as the merchant lists it - `url` string: Offer link carrying attribution - `price` string: Offer price - `details` string: Availability and delivery details - `original_price` string, nullable: Pre-discount price - `available` boolean: Product availability flag - `checkoutable` boolean: True if the product supports direct checkout - `is_digital` boolean, nullable: True for digital goods - `checkout_payload` string, nullable: Data carried in the checkout payload - `checkout_image_urls` string[], nullable: URLs of images shown at checkout - `shop_id` string, nullable: Shop identifier - `provider` string: Identifier of the data provider - `price_details` PriceDetails: Itemized breakdown of an offer's price - `display_price` string, nullable: Price formatted for display - `base` string: Base price of the product - `shipping` string, nullable: Shipping cost - `tax` string, nullable: Tax amount - `total` string: Total price - `tag` OfferTag, nullable: Promotion label attached to an offer - `text` string: Tag text - `tooltip` string: Text of the tag's tooltip - `rating_grouped_citation` RatingGroupedCitation: Details about where the rating comes from, including supporting websites - `title` string: Source title - `url` string: Source URL - `supporting_websites` object[]: Websites cited in support - `provider` string: Identifier of the data provider - `providers` string[]: Array of data providers - `product_lookup_key` object: Lookup key for fetching product updates - `data` string: Product lookup data, encoded as JSON - `product_lookup_data` object: Query data for a structured product lookup - `request_query` string: Query used to search for this product - `all_ids` object: Provider-to-ID mapping - `metadata_sources` string[] - `showcase_metadata` ShowcaseMetadata: Metadata for the visual display of a shopping product: its image, background, and placement in each slot. - `image` ShowcaseImage: Main image displayed at the top of a product showcase - `url` string, required - `width` number - `height` number - `background` ShowcaseBackground: Background style applied to a product showcase - `type` string - `primary` string - `secondary` string - `slots` object: Map of slots, keyed by slot ID - `debug` object: Unstructured debug metadata; clients should not parse it - `show_price_disclosure` boolean: Indicates if a price disclosure should be displayed - `analytics_meta` object: Analytics metadata - `product_event_uuid` string: Product analytics event UUID - `metadata_sources` string[]: Where the product metadata comes from - `product_event_uuid` string: UUID used to track product events - `generatedProductQuery` string: General shopping query that ChatGPT created for this product (taken from product_lookup_key.data). Shows the search intent that led to the recommendation. - `render_as` 'inline' | 'hero' | 'block': Way the product is displayed in the response - `details` object: Product reasoning and reviews loaded from the sidebar API - `rationale` object - `rationale` string: Explanation the AI gave for suggesting this product - `citations` object[]: Sources cited in support of the rationale - `reviews` object - `summary` string: Overview of what product reviews say - `reviews` ProductReview[] - `source` string: Review source - `theme` string: Aspect or theme the review covers - `summary` string: Text summarizing the reviews - `sentiment` 'positive' | 'neutral' | 'negative': Review sentiment - `cite` string, nullable: Citation reference - `rating` number, nullable: Source rating - `num_reviews` integer, nullable: Review count reported by the source - `cite_url` string, nullable: Citation URL - `entities` object[]: Entities parsed from the response (if any) - `type` string, required: Identifier of the entity's type - `name` string, required: Entity name - `map` object[]: Map entries for businesses or places parsed from the response (if any). Entries originate from the enrichment providers ChatGPT uses (Yelp, Google Business), with field names in camelCase. Only the fields filled in most often appear here; see the [API reference](/docs/reference) for every field. - `id` string: Identifier of the business (a Yelp ID or a Google Place ID) - `provider` string: Source of the data: "yelp", "b1" or "b3" (Google), or "yelp-feed" - `name` string: Business name - `position` integer: Rank/position in the results (set by the parser) - `address` string: Complete street address - `latitude` number: Latitude from GPS - `longitude` number: Longitude from GPS - `categories` string[]: Business categories - `rating` number: Rating of the business (scale of 0-5) - `reviewCount` integer: Review count - `description` string: Business description - `phone` string: Phone number for contact - `websiteUrl` string, uri: URL of the business's website - `citationPills` object[]: Inline citation pills parsed from the response (if any), i.e. citations shown in the body of the text. Every entry represents a single (pill, source) pair; grouping on `citationPillId` rebuilds each pill. - `url` string, uri, required: URL the citation points to - `label` string, required: Title of this individual cited source. Never missing, but can be an empty string if the citation event carries no title — then identify the source by `domain` / `url`. - `description` string: Text describing what the citation contains; left out if the citation event has no snippet, as with grouped-webpage cards that show only a title. - `domain` string, required: Domain the cited source belongs to - `datePublished` string: Publication date of the source as an ISO 8601 date string. Left out when the citation event has no publication date. - `citationPillId` integer, required: Zero-based ID common to every entry that comes from one chip; grouping on `citationPillId` rebuilds each pill. **Note:** ChatGPT numbers these from 0 for legacy reasons, whereas every other provider (Google AIO, AI Mode, Copilot, Perplexity, Gemini) numbers `citationPillId` from 1. - `type` 'searchResult' | 'groupedWebpage', required: Indicates which kind of citation event this came from: `searchResult` means an inline search citation, `groupedWebpage` a grouped-webpage card. - `position` integer, required: Index of this source within the sibling `result.sources` array, starting at 1. - `ads` object[]: Ads delivered with the ChatGPT response (present when include.ads is true). Several candidate ads are sent by OpenAI, yet the interface displays one at most; check `rendered` to see which ones were really displayed. - `brand` object, required: Details about the advertiser's brand - `name` string, required: Name of the advertiser's brand - `url` string, uri, required: URL of the advertiser's brand - `favicon` string, uri: Favicon URL of the advertiser's brand - `cards` object[], required: Carousel cards contained in the ad - `title` string, required: Card title - `body` string, required: Text describing the card - `url` string, uri, required: URL the card links to - `image` string, uri: URL of the card's image - `visibility` string, required: Whether OpenAI served the ad. `allowed`: the ad qualified to be shown; `hidden`: OpenAI suppressed it (an integrity check, for instance). - `adsResponseIndex` integer, required: Position of the ad's slot in the ad response OpenAI served. It reflects the order ads were served in, not what was displayed; use `rendered` for real exposure. - `rendered` boolean, required: Indicates if the ad was rendered on screen as a card within the response. ChatGPT returns multiple candidate ads, yet the UI displays one at most; an ad with `rendered: false` was delivered but never shown. ## Other responses - `400`: Bad Request - the request failed validation - `401`: Unauthorized - authentication failed - `403`: Forbidden - missing permissions or not enough balance - `404`: Not Found - No such route - `409`: Conflict - the resource is in a conflicting state - `429`: Too Many Requests - the request went over a rate limit or concurrency limit, or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers - `499`: Client Closed Request - the client cancelled the request - `500`: Internal Server Error - `502`: Bad Gateway - an upstream service failed --- [API](https://skmtc.dev/answerline/apis/answerline-api.md) · [All operations](https://skmtc.dev/answerline/apis/answerline-api/llms.txt) · [OpenAPI document](https://skmtc.dev/answerline/apis/answerline-api/revisions/a9dc35794662?raw)