> ## 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.
# Changelog
> Stay up to date with the latest cloro API product updates, new features, enhancements, bug fixes, and announcements about our monitoring endpoints.
Get live updates of our changelog on your [Slack](https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack) with our RSS feed.
**Czech Republic (CZ) targeting disabled in ChatGPT**
We've removed `country: "CZ"` support for the ChatGPT endpoint. ChatGPT no longer allows anonymous access from Czech IPs — every request is met with a login wall, which scrapers cannot pass through. Requests with `country: "CZ"` to `/v1/chatgpt` will now return an unsupported-country error instead of silently failing.
If you target CZ on other scrapers, double-check the results you're getting back. Some providers fall back to proxies in neighboring countries when CZ-resident proxies are unavailable, which can skew localized answers.
**Google Knowledge Graph panel now extracted**
The Google Search endpoint now returns a `knowledgeGraph` object when a Knowledge Graph panel appears on the SERP. The panel covers people, places, organizations, films, local businesses, and other well-known entities — surfacing structured data like entity type, description, attributes, profiles, ratings, and panel-type-specific fields (streaming options, admission prices, social posts, and more).
No request changes needed — the field is included automatically when a panel is present, and omitted from `result` when it is not.
```json theme={null}
{
"result": {
"knowledgeGraph": {
"title": "Eminem",
"type": "American rapper",
"description": "Marshall Bruce Mathers III, known professionally as Eminem...",
"website": "https://www.eminem.com",
"attributes": [
{ "key": "Born", "value": "October 17, 1972" },
{ "key": "Genre", "value": "Hip hop" }
]
}
}
}
```
See the [Knowledge Graph reference](/api-reference/endpoint/google/knowledge-graph) for the full schema.
**State-level geo-targeting for AI endpoints**
You can now target a specific US state when querying ChatGPT, Copilot, Perplexity, Gemini, or Grok. Pass the USPS two-letter code as the `state` parameter alongside `country: "US"` and cloro routes the request through a proxy in that state — giving you localized results at the sub-country level.
```json theme={null}
{
"prompt": "best electricians near me",
"country": "US",
"state": "TX"
}
```
State targeting costs **+2 credits** on top of the base cost and any other add-ons. Use [`GET /v1/states?country=US`](/api-reference/endpoint/states) to retrieve the full list of supported state codes. Google Search and AI Mode are not affected — those endpoints continue to use `location` / `uule` for sub-country targeting.
**Rate limits are now per endpoint**
The API rate limit of 1,000 requests per second now applies independently to each endpoint (`/v1/*`) per API key. Previously, all endpoints shared a single bucket, meaning a burst on one endpoint could exhaust the limit for others. Each endpoint now has its own independent bucket, so high-traffic calls to one endpoint no longer affect the rate limit for any other.
No action required — existing integrations are unaffected. The `X-RateLimit-Limit` and `X-RateLimit-Remaining` response headers continue to reflect the limit and remaining requests for the specific endpoint called.
**Ask the docs — AI assistant now available**
You can now ask questions about cloro directly from the docs. The assistant is trained on all published documentation and answers in natural language, with citations linking back to the relevant pages.
Look for the **Ask Assistant** button in the navigation bar or the search bar. It works across all pages — API reference, guides, and the changelog.
**Webhook signing — verify deliveries came from cloro**
Enable webhook signing from the [dashboard](https://dashboard.cloro.dev/webhooks) and every async-task delivery will carry an `X-Cloro-Signature` header (HMAC-SHA256 over `.`) plus `X-Cloro-Timestamp` and `X-Cloro-Webhook-Id`. Your endpoint can confirm the payload's origin and integrity, and reject anything signed more than a few minutes ago to protect against replay.
The new [Webhooks guide](/guides/webhooks) is the single home for everything that happens at your endpoint — payload shape, retry behavior, signature verification (with copy-pasteable Node.js, Python, and Go examples), and troubleshooting. Opt-in per organization.
**Copilot now returns `searchQueries` (query fan-out)**
[`/v1/monitor/copilot`](/api-reference/endpoint/monitor-copilot) responses now include `result.searchQueries` — the web search queries Copilot ran while generating its answer. Always-on, no `include` flag, no surcharge.
```json theme={null}
"searchQueries": [
"best laptops for programming 2026",
"developer laptop reviews"
]
```
**Structured `citationPills` now on Perplexity, Copilot, and Gemini**
All three endpoints now emit an additive `citationPills` array alongside the answer text and sources. Combined with the May 21st rollout to Google AI Overview and AI Mode, cross-provider iteration over AI citation pills now works the same way on six endpoints (ChatGPT, Google AI Overview, AI Mode, Perplexity, Copilot, Gemini).
Each entry is one (pill, source) pair carrying a per-source `label` (the source's own page title), a `citationPillId` that groups entries from the same chip, and per-source `url`/`domain`/`description`/`position`.
```json theme={null}
"citationPills": [
{
"label": "Best Programming Laptops 2026 — TechCrunch",
"citationPillId": 1,
"url": "https://techcrunch.com/laptops",
"domain": "techcrunch.com",
"description": "Latest laptop reviews and recommendations",
"position": 1
},
{
"label": "Wired Laptop Buyer's Guide",
"citationPillId": 1,
"url": "https://wired.com/programming-laptops",
"domain": "wired.com",
"description": "Programming laptop buyer's guide",
"position": 3
}
]
```
All six providers share a common base shape (`label`, `citationPillId`, `url`, `domain`, `description?`, `position`). ChatGPT carries two additional fields (`datePublished?`, `type`) that the other surfaces do not emit. Consumers writing cross-provider citation-pill iteration should treat `datePublished` and `type` as ChatGPT-only, and use `citationPillId` for chip grouping.
Additive change — existing consumers are unaffected. The field is omitted from `result` when the answer carries no pills. Learn more in the per-endpoint citation pills documentation: [Perplexity](/api-reference/endpoint/perplexity/citation-pills), [Copilot](/api-reference/endpoint/copilot/citation-pills), [Gemini](/api-reference/endpoint/gemini/citation-pills).
**Structured `citationPills` array on Google AI Overview and AI Mode**
Both Google AI surfaces now emit an additive `citationPills` array alongside the answer text and sources. Each entry is one (pill, source) pair carrying a per-source `label` (the source's own page title from the sources rail), a `citationPillId` that groups entries from the same chip, and per-source `url`/`domain`/`description`/`position`. Cross-provider iteration over AI surface citation pills now uses one shape.
```json theme={null}
"citationPills": [
{
"label": "Best laptops for programmers in 2026",
"citationPillId": 1,
"url": "https://example.com/best-laptops-2026",
"domain": "example.com",
"description": "A guide to the top laptops for software development this year.",
"position": 1
},
{
"label": "MacBook Pro for developers",
"citationPillId": 1,
"url": "https://example.com/macbook-pro-review",
"domain": "example.com",
"description": "Why the MacBook Pro is a popular pick for developers.",
"position": 3
}
]
```
When a pill cites N sources, the array contains N entries sharing the same `citationPillId` but carrying distinct per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure.
Markdown rendering is unchanged — inline `[anchor](url)` links remain the canonical in-text citation form. The `citationPills` array gives type-aware consumers per-source access without re-parsing markdown.
Additive change — existing consumers are unaffected. Learn more in the [AI Overview citation pills](/api-reference/endpoint/google/ai-overview#citation-pills) and [AI Mode citation pills](/api-reference/endpoint/aimode/citation-pills) documentation.
**AI Overview ads now carry a `type` discriminator**
Every entry in `aioverview.ads[]` on the Google Search endpoint now carries an explicit `type` field. Mirrors the same convention already in place for top-level `ads[]` (added 13th May), so callers can route ads to per-sub-type rendering without re-implementing the price/store presence heuristic.
* **`type: "TEXT"`** — text/lead-gen ads. Carry `domain` + `description` (+ shared `position` / `title` / `url` / `image`).
* **`type: "SHOPPING"`** — shopping/product ads. Carry `price` + `store` (+ optional `old_price`, + shared fields).
Each ad is exactly one sub-type — the two sub-schemas are disjoint. Sub-type-exclusive fields are only present when they apply to that ad, matching what the Google SERP actually renders. `image` is the one field that appears in either sub-type (product photo on shopping cards, hero image on text ads), so consumers should treat it as optional regardless of `type`.
```json theme={null}
"ads": [
{ "position": 1, "type": "TEXT", "title": "...", "url": "...", "domain": "dell.com", "description": "..." },
{ "position": 2, "type": "SHOPPING", "title": "...", "url": "...", "price": { "value": 1499, "currency": "$" }, "store": "Best Buy" }
]
```
Additive change — existing consumers ignoring the new field are unaffected. No opt-in, no extra credit charge. Learn more in the [AI Overview ads documentation](/api-reference/endpoint/google/ai-overview#ads).
**AI Overview and AI Mode markdown citations now match ChatGPT**
When you opt into markdown output, in-text citations from Google AI Overview and Google AI Mode are now rendered as **standard inline `[anchor](url)` links** in the `markdown` field — the same shape ChatGPT already uses.
```text theme={null}
... the iPhone 17 is the best choice for most people.[CNET](https://www.cnet.com/tech/mobile/best-iphone/)[The best iPhone to buy!!](https://www.youtube.com/shorts/z1aZ3CYcaRE)
```
Anchor text resolves via a deterministic fallback chain: matched source title → Google's pill-chip label → URL host. Multi-source pills (Google's `+N` chips) expand to N adjacent stacked links at the citation point. `result.markdown` is now fully self-contained — no parallel index resolution needed to render citations.
Learn more in the [AI Overview](/api-reference/endpoint/google/ai-overview#markdown-citations) and [AI Mode](/api-reference/endpoint/aimode/sources#markdown-citations) documentation.
**AI Overview videos now carry full metadata**
`aioverview.videos[]` entries on the Google Search endpoint now populate `title`, `source`, `platform`, `date`, `thumbnail`, and `duration` whenever Google renders them. Previous responses returned only `url` for the vast majority of video cards because the extractor was matching stale Google class names.
`url` remains the only guaranteed field. `title`, `source`, `platform`, and `date` are present on roughly 98% of videos; `thumbnail` (\~60%) and `duration` (\~15%) appear only when Google renders the rich carousel preview. Check for field presence before reading.
No schema change, no opt-in, no extra credit charge — existing requests start receiving the richer payload automatically. Learn more in the [AI Overview documentation](/api-reference/endpoint/google/ai-overview#videos).
**Google Search now returns sponsored shopping-card ads**
The Google Search endpoint now extracts every sponsored shopping surface Google renders on the SERP, alongside the existing text ads. Each entry in `ads[]` carries a new `type` discriminator:
* **`type: "RESULT"`** — classic text ads at the top or bottom of the page (unchanged).
* **`type: "SHOPPING_CARD"`** — shopping-style sponsored cards from the right-hand-side carousel (`blockPosition: "rhs"`) and the top-of-page carousels (`blockPosition: "top"`). Categories observed include `"Sponsored products"`, `"Sponsored vehicles"`, and `"Sponsored hotels"`.
`SHOPPING_CARD` ads include `category` (the carousel header label), `price`, optional `oldPrice` (MSRP / sale), `store`, and `imageUrl`. For shopping-card ads, the existing `description` field carries category-specific subtitle fragments joined with `·` (e.g. `Used - 94k miles · Greeley` on a vehicle card).
The `ads[]` `blockPosition` enum widens to `"top" | "bottom" | "middle" | "rhs"`. The new fields are emitted whenever the SERP renders the corresponding surface — no opt-in, no additional credit charge.
In the organic `shoppingCards[]` field, the `product_link` and `old_price` keys are now emitted as camelCase `productLink` and `oldPrice` to match the rest of the Google response.
Learn more in the [sponsored ads documentation](/api-reference/endpoint/google/sponsored-ads).
**Google Search and Google News multi-page pricing is now linear**
Multi-page requests are now billed at **+2 credits per additional page** instead of the previous tiered structure. Single-page requests are unchanged.
| Request | Old cost | New cost |
| ---------------------- | --------- | --------------------- |
| 1 page | 3 credits | 3 credits (unchanged) |
| 1 page + AI Overview | 5 credits | 5 credits (unchanged) |
| 3 pages | 4 credits | 7 credits |
| 3 pages + AI Overview | 6 credits | 9 credits |
| 10 pages | 5 credits | 21 credits |
| 10 pages + AI Overview | 7 credits | 23 credits |
The same per-page rate applies to [Google News](/api-reference/endpoint/monitor-google-news). See [providers](/guides/providers#google-search-multi-page-pricing) for the full pricing breakdown.
**Why the change.** Pages 2-10 are materially harder to serve than page 1: the failure rate climbs as Google ramps up scrutiny on deep pagination. In our infrastructure, fetching pages 1-10 of a single query costs roughly **6× more** than fetching 10× page 1 alone — the per-page cost scales near-exponentially with depth. The old tiered pricing absorbed that cost and under-charged deep-pagination requests; the new per-page rate aligns billing with the actual cost of serving each page and keeps single-page Google requests — the dominant use case — unchanged.
**Grok pricing increases to 4 credits per request**
Grok's anti-bot defenses have grown materially more complex over recent weeks, raising the proxy, fingerprinting, and retry cost of every successful extraction. To keep base pricing aligned with the underlying infrastructure cost, the [Grok endpoint](/api-reference/endpoint/monitor-grok) now costs **4 credits per request** (previously 3). All other provider prices, addons, and the sync surcharge are unchanged. See the full [providers pricing table](/guides/providers) for context.
**Google Search now returns shopping cards and "people are saying" cards**
The Google Search endpoint now extracts two additional SERP modules:
* **Shopping cards**: product cards from the organic shopping grids ("Popular products" and "More products") in a new optional `shoppingCards` array. Learn more in the [shopping cards documentation](/api-reference/endpoint/google/shopping-cards).
* **People are saying**: community-thread cards from Google's "What people are saying" / "Trending posts and discussions" module in a new optional `peopleAreSaying` array. Learn more in the [people are saying documentation](/api-reference/endpoint/google/people-are-saying).
Both fields are omitted from `result` when their corresponding module is absent — treat them as optional. No additional credit charge.
**Gemini sources no longer include `confidence_level`**
Google Gemini stopped returning a confidence score on source citations. The `confidence_level` field has been removed from the [Gemini endpoint](/api-reference/endpoint/monitor-gemini) response schema. All other source fields (`position`, `url`, `label`, `description`) are unchanged.
**More Google AI Mode fields**
The AI Mode endpoint now returns more structured data:
* **Map**: GPS-enriched location results with `gps_coordinates` (latitude/longitude), `type`, `thumbnail`, and a position `index`
* **Places**: Inline place cards with `rating`, `reviews`, `type`, `price_level`, `address`, and `status`
* **Shopping cards**: Shopping cards now include `old_price` for discount comparison, `snippet` for product descriptions, and `snippet_links` for related links within snippets
* **Ads**: Sponsored ad sections are now parsed into a structured `ads` object with individual ad details including title, URL, position, price, store, rating, and reviews
* **Inline products**: Product cards embedded within the AI response text are now extracted as `inline_products`, separate from shopping card carousels
**Breaking change**: The `price` and `description` fields have been removed from the places object. The `link` field now points to Google's viewer URL format instead of the previous search URL format.
All new data is included at no additional credit charge. Learn more in the [AI Mode endpoint documentation](/api-reference/endpoint/monitor-aimode).
**Inline products now return offers correctly for ChatGPT**
We fixed a bug where ChatGPT inline products were missing pricing and merchant data. Inline products now include the full offer payload (current price, multi-merchant offers from retailers like Amazon and John Lewis, product images, and aggregated ratings) fetched from ChatGPT's product update API.
Alongside this fix, shopping cards and inline products move to an opt-in model on the ChatGPT endpoint. Set `include.shopping: true` to include them in your response:
* **Pricing and offers**: Current price and multi-merchant offers with availability
* **Product images**: Image URLs for product display
* **Ratings**: Aggregated rating scores and review counts
**Opt-in with additional credit cost**
Shopping cards and inline products are disabled by default. Set `include.shopping: true` to enable them. Enabling `shopping`, `rawResponse`, `searchQueries`, or `ads` (or any combination) adds +2 credits to the base cost.
The credit surcharge reflects increased extraction complexity. OpenAI now serves product pricing, offers, and merchant data through a separate endpoint, so cloro performs additional fetches per product to enrich the response.
**Migration deadline: 8th May 2026**
During the migration window, ChatGPT responses still return `shoppingCards` and `inlineProducts` by default. **Starting 8th May 2026**, requests without `include.shopping: true` will no longer receive these fields. Update your integrations before that date to avoid silent data loss.
**Breaking change**: Shopping cards and inline products were previously included automatically in ChatGPT responses. They now require `include.shopping: true` in your request. The `details` object on inline products (rationale and themed reviews) is no longer returned.
Learn more in our [ChatGPT shopping cards documentation](/api-reference/endpoint/chatgpt/shopping-cards) and [inline products documentation](/api-reference/endpoint/chatgpt/inline-products).
**Hyperlocal-targeting for AI Mode with UULE**
The AI Mode endpoint now supports two parameters for precise geo-targeting of results:
* **`location`**: City-level targeting using [Google canonical location names](https://developers.google.com/google-ads/api/reference/data/geotargets) (e.g., `New York,New York,United States`). Choose from \~100,000 supported locations worldwide
* **`uule`**: Advanced targeting using pre-encoded Google UULE strings for users who generate their own UULE values
Both parameters work alongside `country` for precise localization. They are mutually exclusive: provide one or the other, not both. No additional credits required.
Learn more in our [AI Mode documentation](/api-reference/endpoint/monitor-aimode#usage-examples).
**Copilot pricing update**
The Copilot endpoint base cost has been updated to 5 credits per request, to reflect the added complexity to ensure sources in 95%+ of cases.
**Sync request surcharge**
All sync monitor requests (`/v1/monitor/*`) now include a **+2 credit surcharge** on top of the base cost and any feature add-ons. This reflects the higher operational cost of real-time synchronous requests.
Async and batch requests (`/v1/async/*`) are **not** affected by this surcharge.
Existing customers who used sync endpoints in the 30 days before this change have been granted a grace period. If you have questions about your account, contact [support](mailto:support@cloro.dev).
Learn more in our [provider pricing documentation](/guides/providers#sync-request-surcharge).
**Geo-targeting for Google Search**
The Google Search endpoint now supports two parameters for precise geo-targeting of search results:
* **`location`**: City-level targeting using [Google canonical location names](https://developers.google.com/google-ads/api/reference/data/geotargets) (e.g., `New York,New York,United States`). Choose from \~100,000 supported locations worldwide
* **`uule`**: Advanced targeting using pre-encoded Google UULE strings for users who generate their own UULE values
Both parameters work alongside `country` for precise localization. They are mutually exclusive -- provide one or the other, not both. No additional credits required.
Learn more in our [Google Search documentation](/api-reference/endpoint/monitor-google#uule-geo-targeting).
**Sponsored ad extraction for AI Overview**
Google AI Overview responses now include structured sponsored ad data when Google injects advertising inside the AI Overview. Ads are exposed as a new `ads` array alongside the existing `text`, `sources`, and `videos` fields.
Each ad includes:
* **Ad details**: Title, destination URL, domain, and description
* **Position tracking**: Position index within the AI Overview ad block
Ads also remain visible in `text` and `markdown` output for full transparency. No additional parameters required -- ads are automatically included when present.
Learn more in our [AI Overview documentation](/api-reference/endpoint/google/ai-overview).
**Map entries for Copilot**
The Copilot endpoint now automatically extracts business and place data when Copilot returns local entity information. Map entries include location coordinates, reviews, photos, open/closed status, and Google Place IDs. No additional parameters required.
**Features**:
* **Automatic extraction**: Map entries are included by default when available, just like shopping cards
* **Native structure**: Preserves Copilot's entity format with nested `location`, `reviews`, and `photos` objects
* **Google Places integration**: Each entry includes a `placeId` for direct Google Maps lookups
* **Live status**: `openState` field shows current business hours (e.g. "Open · Closes 9 PM")
* **No extra cost**: Map entries are included at no additional credit charge
Learn more in the [Copilot endpoint documentation](/api-reference/endpoint/copilot/map-entries).
**Batch task creation**
You can now submit up to 500 async tasks in a single API request using the new batch endpoint. This reduces HTTP overhead for high-volume workloads and simplifies bulk monitoring workflows.
**Features**:
* **Up to 500 tasks per request**: Submit tasks to any combination of providers in one call
* **Partial success**: Each task is validated independently. One invalid task doesn't block the rest
* **Per-task error reporting**: Failed tasks include detailed error codes (`VALIDATION_ERROR`, `RESOURCE_ALREADY_EXISTS`, `INSUFFICIENT_CREDITS`) with field-level details
* **Per-task credits**: Each task's result includes its own credit information
* **Full feature support**: Each task in a batch supports priority, idempotency keys, and webhooks
Learn more in the [batch task creation documentation](/api-reference/endpoint/create-batch-tasks).
**Priority support for async tasks**
You can now assign a priority to async tasks so that time-sensitive work is processed first. Set the `priority` field (1-10) when creating a task. Higher numbers mean higher urgency.
**Features**:
* **Priority range**: Integer from 1 (lowest, default) to 10 (highest)
* **Smart ordering**: Higher-priority tasks are processed before lower-priority ones within your queue. Same-priority tasks are processed in FIFO order
* **Priority breakdown**: The [async status endpoint](/api-reference/endpoint/get-async-status) now shows queued task counts per priority level
* **Backward compatible**: Tasks without a priority default to 1, so existing integrations are unaffected
Learn more in our [async requests documentation](/guides/making-requests/async#request-prioritization).
**More business data in ChatGPT map entries**
ChatGPT map entries now return mapped business data from providers (Yelp, Google Business) with 47 structured fields, replacing the previous 10-field structure.
What changed:
* **Mapped data**: Map entries now include all available business fields from ChatGPT's providers (Yelp, Google Business, Yelp-feed)
* **47 mapped fields**: Access to detailed location data, operating hours, attributes, reviews, images, and provider-specific metadata
* **Structured schema**: Properly typed fields with consistent camelCase naming conventions
* **Field name updates**: `phone_number` → `phone`, `country` → `countryCode`, `review_count` → `reviewCount`
* **Null-safe**: All fields except `name` and `position` are optional
Key improvements:
* **More location data**: Full address breakdown with coordinates (`latitude`/`longitude`), distance from user (`distanceMeters`), and human-readable location strings
* **Hours**: Weekly schedule with next opening times (`nextOpenHour`) and special hours (`specialHours`)
* **Attributes**: Provider-specific details like parking options, WiFi availability, accepted payment methods, and accessibility features
* **Images**: Multiple image URLs (`imageUrls`) with provider-hosted images (`providerImages`)
* **Metadata**: Business claimed status (`isClaimed`), opening/closing dates (`dateOpened`/`dateClosed`), popularity scores (`popularityScore`), and cache indicators (`fromCache`)
**Breaking change**: Field names have changed to camelCase. Examples: `review_count` → `reviewCount`, `country_code` → `countryCode`, `is_open` → `isOpen`. All fields except `name` and `position` are now optional.
Learn more in our [ChatGPT map documentation](/api-reference/endpoint/chatgpt/map).
**Ad extraction for ChatGPT**
ChatGPT responses now support structured ad extraction when advertising content is displayed. This opt-in feature lets you monitor ads shown in ChatGPT responses.
**Opt-in feature with additional cost**
Ad extraction is disabled by default. Set `include.ads: true` to extract ads from ChatGPT responses. Enabling `ads`, `rawResponse`, or `searchQueries` (or any combination) adds +2 credits to the base cost.
**Features**:
* **Brand information**: Advertiser brand name, URL, and favicon
* **Carousel cards**: Multiple promotional cards with titles, descriptions, images, and destination URLs
* **Attribution tracking**: All URLs include ChatGPT attribution parameters
* **Structured data**: JSON structure
Learn more in our [ChatGPT documentation](/api-reference/endpoint/chatgpt/ads).
**Google News endpoint**
We've added a new endpoint for extracting structured news articles from Google News (`/v1/monitor/google/news`).
**Features**:
* **News article extraction**: Titles, links, snippets, sources, and publication dates
* **Multi-page scraping**: Scrape up to 10 pages of news results per request
* **Country-specific results**: Localized news from 250 countries worldwide
* **Device targeting**: Desktop or mobile news results
* **Thumbnail images**: Article thumbnails when available
* **Raw HTML access**: Optional full page HTML for custom parsing
Learn more in our [Google News documentation](/api-reference/endpoint/monitor-google-news).
**Inline products for ChatGPT**
ChatGPT responses now include inline products: individual product references that appear embedded in the response text, separate from shopping cards. This feature supports OpenAI's new [product discovery capabilities](https://openai.com/index/powering-product-discovery-in-chatgpt/) announced in ChatGPT.
**Model availability**: Inline products currently appear when ChatGPT uses the `gpt-5-3` model. ChatGPT automatically selects which model to use for each request.
What's new:
* Inline product extraction: Individual products referenced in comparison tables, featured recommendations, or inline mentions
* Rendering hints: Display guidance with `render_as` field ("inline", "hero", or "block")
* Cite references: Each product includes a unique cite ID for cross-referencing with text
Learn more in our [ChatGPT inline products documentation](/api-reference/endpoint/chatgpt/inline-products).
**Async queue monitoring and visibility**
New [`GET /v1/async/status`](/api-reference/endpoint/get-async-status) endpoint provides real-time visibility into your async queue health, including queued tasks, processing tasks, and concurrency usage.
**Use cases**:
* Monitor queue health and processing capacity
* Decide on plan upgrades based on actual concurrency usage
* Debug task delays by identifying queue bottlenecks
* Throttle task submission based on current queue size
Learn more in our [async status documentation](/api-reference/endpoint/get-async-status).
**Shopping cards for Copilot**
Copilot responses now automatically include structured shopping cards when product information is detected:
* **Product identifiers**: Unique product ID, group ID, and brand group ID for precise tracking
* **Product details**: Name, description, brand, and seller information
* **Specifications**: Configurable product attributes like Color, Size with available values
* **Images**: Multiple product images with titles
* **Pricing**: Structured price data with amount, currency, and symbol
* **Ratings**: Product ratings with review counts
* **Price tracking**: Flag indicating if price tracking is available
No additional parameters are required. Shopping cards are automatically detected and included when Copilot returns product information.
Learn more in our [Copilot documentation](/api-reference/endpoint/copilot/shopping-cards).
**Raw response now available for all event stream engines**
The `rawResponse` field is now available for Copilot, Grok, Gemini, and Perplexity endpoints at no additional cost.
**Example usage:**
```json theme={null}
{
"prompt": "Your query here",
"model": "GROK",
"include": {
"rawResponse": true
}
}
```
Raw response data provides full streaming event payloads, so you can see how these AI models generate their responses.
**Global coverage milestone: 250 countries supported**
cloro now supports **250 countries worldwide** across all endpoints.
Our geographical infrastructure spans from major markets to remote territories, so you can monitor AI responses and search results from almost anywhere in the world. This includes territories like Antarctica (AQ), remote islands like Bouvet Island (BV), and regions like the British Indian Ocean Territory (IO).
**Total coverage**:
* **250 countries**: Complete ISO 3166-1 alpha-2 country code coverage
* **All endpoints supported**: Geographical availability across ChatGPT, Perplexity, Grok, Gemini, Copilot, AI Mode, AI Overview, and Google Search
* **Model-specific availability**: Each model has its own country support based on provider restrictions
The [countries endpoint](/api-reference/endpoint/countries) remains the authoritative source for current country availability. Always query with your target model to verify supported locations.
**Massive geographical expansion for Perplexity, Copilot, Gemini, and Grok**
We've expanded country coverage for Perplexity, Copilot, Gemini, and Grok to match the availability of ChatGPT.
**Country coverage by model**:
* **ChatGPT**: 196 countries (unchanged)
* **Perplexity**: 196 countries (expanded from 74)
* **Grok**: 195 countries (expanded from 74)
* **Gemini**: 195 countries (expanded from 73)
* **Copilot**: 193 countries (expanded from 71)
* **AI Mode**: 211 countries (unchanged)
* **AI Overview**: 230 countries (unchanged)
* **Google Search**: 250 countries (unchanged)
The [countries endpoint](/api-reference/endpoint/countries) remains the authoritative source for current country availability. Always query with your target model to verify supported locations before deploying.
**Grok search queries and model extraction**
Grok responses now include two new fields for better insight into how responses are generated:
* **`searchQueries`**: Array of search queries Grok used to gather information for the response
* **`model`**: The model identifier used to generate the response (e.g., "grok-3", "grok-4-auto")
**Example response**:
```json theme={null}
{
"result": {
"text": "Here are the best sneakers under $100...",
"searchQueries": [
"best sneakers under $100 2026",
"best budget sneakers under $100 2026"
],
"model": "grok-4-auto"
}
}
```
Learn more in our [Grok documentation](/api-reference/endpoint/monitor-grok).
**Copilot country restrictions**
Italy (IT) and Brazil (BR) have been disabled for the Copilot endpoint. Microsoft has placed these regions behind a login wall, making them unavailable for anonymous scraping.
Use the [countries endpoint](/api-reference/endpoint/countries) with `model=copilot` to verify current country availability before deploying.
**Improved ChatGPT source metadata**
ChatGPT sources now include enhanced metadata for better source attribution:
* **`datePublished`**: Publication date of the source article (e.g., "May 22, 2025")
* **`label`**: Now contains the article title instead of the domain name
* **`description`**: Now contains a content snippet instead of the combined date and title
Learn more in our [ChatGPT documentation](/api-reference/endpoint/chatgpt/sources).
**ChatGPT geographical expansion**
ChatGPT is now available in 200 countries worldwide.
The [countries endpoint](/api-reference/endpoint/countries) remains the authoritative source for current country availability. Always query with `model=chatgpt` to verify supported locations before deploying.
**Sponsored ad extraction for Google Search**
Google Search endpoint now automatically extracts sponsored ad results from search results pages.
**Features**:
* **Ad placement tracking**: Ads are extracted from both top and bottom of search results with `blockPosition` indicating placement
* **Complete ad details**: Title, URL, displayed URL, domain, description, and position within ad block
* **Ad sitelinks**: Extended ad sitelinks with titles, URLs, and descriptions when available
* **Multi-page support**: Ads are extracted across all requested pages
**Response structure**:
```json theme={null}
{
"result": {
"ads": [
{
"position": 1,
"blockPosition": "top",
"title": "Best Programming Laptops - Shop Now",
"url": "https://example.com/programming-laptops",
"page": 1,
"displayedUrl": "example.com/laptops",
"domain": "example.com",
"description": "Shop our selection of high-performance laptops...",
"sitelinks": [
{
"url": "https://example.com/gaming-laptops",
"title": "Gaming Laptops",
"description": "High-performance laptops for gaming"
}
]
}
]
}
}
```
No additional parameters required. Ads are automatically included when present on search results pages.
Learn more in our [Google Search documentation](/api-reference/endpoint/google/sponsored-ads).
**Isolation of ChatGPT citation data**
We've improved how source information is structured and exposed in ChatGPT responses:
**Citation pills**: Inline citations that appear within ChatGPT responses where specific sources are referenced. Each citation pill includes:
* **URL**: Direct link to the cited source
* **Label**: Title or label of the citation
* **Description**: Summary of the cited content
* **Domain**: Source domain (e.g., "example.com")
* **Date published**: ISO 8601 date string when the source was published
* **Citation pill ID**: Unique identifier for the citation
**Sources footnote field**: The `sources` array now includes a `footnote` boolean field that indicates whether a source appears in the main window footnote (i.e., the sources pill), to distinguish between primary and secondary sources.
Previously, the citation and source pill data was only accessible by parsing the markdown response. Now you can access it directly through structured JSON objects without needing to parse markdown links.
No additional parameters required. Citation pills and the footnote field are automatically included when available in ChatGPT responses.
Learn more in our [ChatGPT documentation](/api-reference/endpoint/chatgpt/citation-pills).
**Updated Google Search pricing structure**
We've updated the Google Search endpoint baseline pricing to a more predictable tiered structure for multi-page requests.
**What's changed:**
* **Multi-page pricing** is now tiered instead of per page:
* 2-3 pages: +1 credit (was +2-4 credits)
* 4-10 pages: +2 credits (was +6-18 credits)
* **Base cost and AI Overview** remain unchanged:
* Base request: 3 credits
* AI Overview addon: +2 credits
**New pricing examples:**
* 1 page, no AI Overview: **3 credits** (unchanged)
* 1 page, with AI Overview: **5 credits** (unchanged)
* 3 pages, with AI Overview: **6 credits** (was 9 credits)
* 10 pages, with AI Overview: **7 credits** (was 23 credits)
Costs are more predictable, with reduced pricing for bulk multi-page extraction.
**Map entries for ChatGPT**
ChatGPT responses now automatically include structured map entries when business or place information is detected. Use cases:
* **Local business monitoring**: Track restaurants, stores, and service providers
* **Location intelligence**: Extract ratings, reviews, and contact details
* **Competitive analysis**: Monitor local businesses across different regions
* **Directory building**: Create structured business listings
Map entries include business details:
* **Business information**: Name, category, description
* **Social proof**: Rating score, review count
* **Contact details**: Website URL, phone number
* **Location data**: Position/ranking in results
* **Navigation**: Directions URL (when available)
No additional parameters are required. Map entries are automatically detected and included when ChatGPT returns local business or place information.
Learn more in our [ChatGPT documentation](/api-reference/endpoint/chatgpt/map).
**Added 16 new countries**
We've expanded our geographical coverage with 16 new countries available for monitoring across all non-Google endpoints:
```
BG - Bulgaria
BY - Belarus
CY - Cyprus
EE - Estonia
GE - Georgia
KE - Kenya
KG - Kyrgyzstan
LT - Lithuania
LU - Luxembourg
LV - Latvia
MA - Morocco
MT - Malta
PE - Peru
TJ - Tajikistan
UZ - Uzbekistan
```
Remember to always check the [model-specific country list](/api-reference/endpoint/countries) before deploying to ensure availability for your target endpoint, as some models have country-specific restrictions.
**Google Search and AI Mode updates**
We've updated the Google Search and AI Mode endpoints:
**Removed parameters:**
* `city` parameter temporarily removed from Google Search and AI Mode endpoints
* No customers were using this parameter, and `country`-level localization was sufficient for all use cases
**New parameter:**
* `device` parameter added to AI Mode endpoint
* Options: `desktop` (default) or `mobile`
* Same device targeting available in Google Search
**Gemini geographical expansion**
Gemini now supports EU countries and additional regions, bringing geographical coverage to parity with Copilot, Perplexity, and Grok.
The [countries endpoint](/api-reference/endpoint/countries) remains the authoritative source for current country availability. Always query with `model=gemini` to verify supported locations before deploying:
```bash theme={null}
curl "https://api.cloro.dev/v1/countries?model=gemini" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Grok is now available**
Grok is now available as a new provider.
Key features:
* **Supported in most countries** (remember to check the [model-specific country list](/api-reference/endpoint/countries))
* **Source metadata** with preview text, search engine display text, site information, creator details, and image URLs
* **Real-time web integration** for current information and breaking news
* **Response formats**: text, HTML, and Markdown
Getting started:
```bash theme={null}
curl -X POST https://api.cloro.dev/v1/monitor/grok \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "What are the latest developments in quantum computing?",
"country": "US"
}'
```
See the [Grok API documentation](/api-reference/endpoint/monitor-grok) for full details and examples.
We've expanded our geographical coverage across all Google endpoints:
* **Google Search**: Now available in all 250 countries worldwide
* **AI Mode**: Expanded from 58 to 211 countries
* **AI Overview**: Expanded from 59 to 230 countries
Remember to check the [model-specific country list](/api-reference/endpoint/countries) before deploying to ensure availability for your target endpoint.
**Added 11 new countries**
Expanded our geographical coverage with 11 new countries available for monitoring:
```
BD - Bangladesh
CO - Colombia
EG - Egypt
FI - Finland
HK - Hong Kong
KZ - Kazakhstan
NG - Nigeria
PH - Philippines
PK - Pakistan
VE - Venezuela
VN - Vietnam
```
Most new locations start with low capacity, which will be increased based on demand. Remember to check the [model-specific country list](/api-reference/endpoint/countries) before deploying to ensure availability for your target endpoint.
**Defined async task retention policy**
`COMPLETED` and `FAILED` async tasks are stored for **24 hours** after completion.
HTML URLs also expire after 24 hours from generation (aligned with task retention).
**More fields extracted for AI Mode and AI Overview**
Google AI Mode and AI Overview endpoints now automatically extract rich structured data:
* **Places in AI Mode**: Location information with ratings, reviews, price levels, addresses, Google Places IDs, and operating status
* **Shopping cards in AI Mode**: Structured product data with currency-aware pricing, merchant details, ratings, and purchase links
* **Video content in AI Overview**: Videos with thumbnails, titles, duration, platform info, and source attribution
No additional parameters required. All structured data is automatically detected and included when available in responses.
Learn more in [AI Mode](/api-reference/endpoint/monitor-aimode) and [AI Overview](/api-reference/endpoint/google/ai-overview).
Since location availability depends on the model, we have enhanced the `/v1/countries` endpoint with model filtering:
* **Model-specific filtering** - Get countries available for specific AI providers using the `model` query parameter
* **Supported models** - Filter by: `aimode`, `aioverview`, `chatgpt`, `copilot`, `gemini`, `google`, or `perplexity`
**Usage examples**:
```bash theme={null}
# Get all countries
curl "https://api.cloro.dev/v1/countries"
# Get countries available for ChatGPT
curl "https://api.cloro.dev/v1/countries?model=chatgpt"
# Get countries available for Perplexity
curl "https://api.cloro.dev/v1/countries?model=perplexity"
```
Learn more in our [countries endpoint documentation](/api-reference/endpoint/countries).
We've added support for Google Gemini (`/v1/monitor/gemini`). You can now extract structured data from Gemini responses with source citations.
**Features**:
* **Text extraction** - Get the generated response text
* **Source citations** - Structured list of sources with URLs, snippets, and confidence levels
* **Markdown & HTML** - Optional output formats
**Usage example**:
```json theme={null}
{
"prompt": "Explain quantum computing",
"country": "US",
"include": {
"markdown": true
}
}
```
Learn more in our [Gemini documentation](/api-reference/endpoint/monitor-gemini).
The HTML code is now stored externally to avoid crowding the response payload.
**Changes**:
* HTML URLs now expire after 24 hours from generation
* Storage URLs updated to use `https://storage.cloro.dev/results/` format
**Important note**: If you need to preserve HTML content longer than 24 hours, download it promptly after receiving the response.
**Example response**:
```json theme={null}
{
"result": {
"html": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html"
}
}
```
Learn more in our [Making Requests documentation](/guides/making-requests).
**New Google Search endpoint**
We're excited to announce the launch of our Google Search endpoint (`/v1/monitor/google`) for extracting structured data from Google search results.
**Features**:
* **Organic results** - Extract titles, links, snippets, and positions from search results
* **People Also Ask** - Capture questions and answers with page tracking
* **Related searches** - Get related search query suggestions
* **AI Overview** - Extract Google's AI-generated summaries with source attribution (optional)
* **Multi-page scraping** - Scrape up to 10 pages per request with the `pages` parameter
* **Country-specific results** - Localized search results across many countries
* **Hyperlocal targeting** - City-specific search results using canonical city names with automatic UULE conversion
* **Raw HTML access** - Option to retrieve full page HTML for custom parsing
**Usage example**:
```json theme={null}
{
"query": "best laptops for programming",
"pages": 3,
"country": "US",
"include": {
"aioverview": {
"markdown": true
}
}
}
```
Learn more in our [Google search documentation](/api-reference/endpoint/monitor-google).
**Enhanced retry logic for synchronous requests**
We have the following changes in our internal retry mechanism:
* Increased retry attempts from 5 to 10 for synchronous requests
* Added 5-minute maximum duration timeout to prevent indefinite waiting
* Requests canceled by clients are charged for resources consumed (same behavior as before)
This automatic retry handling **removes the need for client-side timeout logic**. More details in the [Error handling](/guides/error-handling) section.
**Configurable HTML response for all parsers**
HTML content in parser responses is now optional and configurable across all monitoring endpoints.
**Changes**:
* Added `include.html` parameter to all parser endpoints (ChatGPT, Perplexity, Copilot, AI Mode, AI Overview)
* A URL to the HTML content is now only included when explicitly requested with `"include.html": true`
* Responses are smaller and faster when HTML is not needed
* Markdown conversion continues to work regardless of HTML inclusion
**Usage example**:
```json theme={null}
{
"prompt": "Your query here",
"include": {
"html": true,
"markdown": true
}
}
```
This reduces response size and improves performance when your application doesn't need the full HTML content.
**Asynchronous requests and webhooks**
You can now make asynchronous requests for async tasks. When you make an async request, you'll receive a `taskId`, the task will then be processed in the background.
You can retrieve the results in two ways:
* **Webhooks**: Provide a `webhook.url` in your request, and we'll send the results to your endpoint as soon as they're ready.
* **Polling**: Use the new [`GET /v1/async/task/{taskId}`](/api-reference/endpoint/get-task-status) endpoint to check the status of your task and retrieve the results when it's complete.
This works for serverless environments or applications that can't wait for a task to complete.
Learn more in our [Async Requests documentation](/guides/making-requests).
**More information in Perplexity response**
The Perplexity API endpoint has been expanded to reflect extra fields in the Perplexity response. The endpoint now automatically extracts structured data objects based on query intent:
**Shopping data extraction**:
* Product information with titles, descriptions, pricing, and ratings
* Multiple merchant offers and availability status
* Product variants, images, and specifications
* Shopping cards with promotional tags and categorization
**Media content extraction**:
* Video content with thumbnails, dimensions, and source attribution
* Image extraction with metadata and sizing information
* Support for YouTube, stock photos, and other media platforms
**Travel and location data**:
* Hotel listings with ratings, reviews, amenities, and pricing
* Place information with categories, coordinates, and contact details
* Address data, map URLs, and image galleries
**Search intelligence**:
* Related query suggestions for follow-up searches
* Internal search query tracking showing how responses are generated
* Citation processing and source attribution
The documentation now provides schema definitions for all response objects, including field types, descriptions, and examples. No API changes were required. These features were already available and are now documented.
Learn more in the updated [Perplexity API documentation](/api-reference/endpoint/monitor-perplexity).
**Entity extraction for ChatGPT**
ChatGPT responses now include automatic entity extraction when specific items, products, brands, or concepts are identified. Use cases:
* **Product recognition**: Identify and extract product mentions
* **Brand tracking**: Monitor brand references across ChatGPT responses
* **Concept analysis**: Extract named entities for semantic analysis
* **Content classification**: Categorize response content based on extracted entities
Each entity includes:
* **Type**: Entity type identifier (e.g., "product", "software")
* **Name**: Entity name or title (e.g., "adidas Grand Court Lo", "Nike Dunk Low Retro SE")
Entity extraction works alongside shopping cards. No additional parameters are required. Entities are automatically detected and included when available.
Learn more in our [ChatGPT documentation](/api-reference/endpoint/chatgpt/entities).
**Shopping cards for ChatGPT**
ChatGPT responses now automatically include structured shopping cards when product information is detected. Use cases:
* **Product monitoring**: Track prices, ratings, and availability over time
* **Price tracking**: Monitor price changes across different regions
* **Competitive intelligence**: Extract structured product data for analysis
* **Commerce integration**: Build price comparison and recommendation systems
Shopping cards include product details:
* **Product information**: Name, brand, description, specifications
* **Pricing data**: Current price, original price, discount information
* **Commercial details**: Multiple merchant offers, availability, checkout options
* **Media assets**: Product images, checkout-specific images
* **Ratings**: Ratings, review counts, rating citations with sources
* **Offer details**: Merchant-specific pricing, promotional tags, shipping costs
The shopping cards feature supports:
* **Multi-offer products**: Compare different merchants for the same product
* **Price breakdown**: Pricing including base, shipping, tax, and total
* **Promotional content**: Tags, tooltips, and special offers
* **Media**: Multiple product images and checkout assets
* **Availability tracking**: Real-time stock and checkout status
No additional parameters are required. Shopping cards are automatically detected and included when available.
Learn more in our [ChatGPT documentation](/api-reference/endpoint/chatgpt/shopping-cards).
**New dedicated endpoints**
Each AI model now has its own dedicated endpoint for better performance and clearer documentation:
* [Extract Google AI Overview](/api-reference/endpoint/google/ai-overview) (via `POST /v1/monitor/google` with `include.aioverview`)
* [Extract Microsoft Copilot](/api-reference/endpoint/monitor-copilot) (`POST /v1/monitor/copilot`)
* [Extract Perplexity](/api-reference/endpoint/monitor-perplexity) (`POST /v1/monitor/perplexity`)
* [Extract Google AI Mode](/api-reference/endpoint/monitor-aimode) (`POST /v1/monitor/aimode`)
* [Extract ChatGPT](/api-reference/endpoint/monitor-chatgpt) (`POST /v1/monitor/chatgpt`)
**Added Google AI Mode**
Google's AI Mode results are now supported. You can extract structured data from ChatGPT, Perplexity, Copilot, and AI Mode using the same unified interface.
To monitor AI Mode, set `"model": "AIMODE"` in your API requests:
```json theme={null}
{
"prompt": "What do you know about Acme Corp?",
"model": "AIMODE",
"country": "US"
}
```
All existing features work with AIMODE, including:
* Structured data extraction with sources & citations
* Localization across different countries
* Markdown format support
* Citation grouping and processing
Learn more in our [API Reference](/api-reference/endpoint/monitor-aimode).
**Added `include.rawResponse` parameter**
You can now access the underlying AI provider payload in monitoring responses (ChatGPT-only). Enable it with `"include.rawResponse": true` to receive the full provider response alongside cloro's structured output.
```json theme={null}
{
"prompt": "What do you know about Acme Corp?",
"model": "CHATGPT",
"include": {
"markdown": true,
"rawResponse": true
}
}
```
Learn more in our [API Reference](/api-reference/endpoint/monitor-chatgpt).
**Added Microsoft Copilot**
Microsoft Copilot (formerly Bing Chat) is now supported. You can now extract structured data from ChatGPT, Perplexity, and Copilot using the same unified interface.
To use Copilot, simply set `"model": "COPILOT"` in your API requests:
```json theme={null}
{
"prompt": "What do you know about Acme Corp?",
"model": "COPILOT",
"country": "US"
}
```
All existing features work with Copilot, including:
* Structured data extraction with sources & citations
* Localization across different countries
* Markdown format support
* Citation grouping and processing
Learn more in our [API Reference](/api-reference/endpoint/monitor-copilot).
**Added Perplexity**
Perplexity is now supported. You can now extract structured data from both ChatGPT and Perplexity models using the same unified interface.
To use Perplexity, simply set `"model": "PERPLEXITY"` in your API requests:
```json theme={null}
{
"prompt": "What do you know about Acme Corp?",
"model": "PERPLEXITY",
"country": "US"
}
```
All existing features work with Perplexity, including:
* Structured data extraction with sources & citations
* Localization across different countries
* Markdown format support
Learn more in our [API Reference](/api-reference/endpoint/monitor-aimode).
**Added `searchQueries` field to responses**
All AI monitoring responses now include a `searchQueries` field that shows the search terms used to generate the AI response.
```json theme={null}
{
"success": true,
"result": {
"text": "The name \"Acme Corporation\" is used in various contexts...",
"searchQueries": [
"What is Acme Corporation?",
"Acme Corp company overview",
"Acme Corporation products and services"
]
}
}
```
Learn more in our [API Reference](/api-reference/endpoint/monitor-aimode).
**Added `include.markdown` parameter**
You can now receive markdown-formatted content in AI monitoring responses. Perfect for documentation workflows and content management systems.
```json theme={null}
{
"prompt": "What do you know about Acme Corp?",
"model": "CHATGPT",
"include": {
"markdown": true
}
}
```
Learn more in our [API Reference](/api-reference/endpoint/monitor-aimode).
**cloro API launch**
The cloro AI monitoring API is live. Extract structured data from ChatGPT, Perplexity, Microsoft Copilot, Google AI Mode and other AI models about your brand or any topic across different regions.
Key features:
* AI response monitoring across different countries
* Structured data extraction with sources and citations
* Support for text and HTML formats
* Real-time AI model tracking
Get started with our [welcome guide](/) or explore the [API reference](/api-reference).