Skip to main content
POST
/
v1
/
monitor
/
aimode
Monitor AI Mode Responses
curl --request POST \
  --url https://api.cloro.dev/v1/monitor/aimode \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "What are the best laptops for programming?",
  "country": "US",
  "location": "New York,New York,United States",
  "uule": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5",
  "device": "desktop",
  "include": {
    "html": false,
    "markdown": false
  }
}
'
{
  "success": true,
  "result": {
    "text": "Here are some excellent laptop recommendations for programming...",
    "html": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html",
    "sources": [
      {
        "position": 1,
        "url": "https://example.com/ai-recommendations",
        "label": "AI Source",
        "description": "AI-curated laptop recommendations"
      }
    ],
    "markdown": "Here are some excellent laptop recommendations for programming...",
    "places": [
      {
        "title": "Gion District",
        "link": "https://www.google.com/viewer/place?mid=/g/11bw3yq9kp",
        "place_id": "/g/11bw3yq9kp",
        "index": 0,
        "thumbnail": "https://lh5.googleusercontent.com/p/example",
        "rating": 4.5,
        "reviews": 2900,
        "type": "Tourist attraction",
        "price_level": "$$",
        "address": "Gionmachi, Higashiyama Ward, Kyoto",
        "status": "Open now"
      }
    ],
    "shopping_cards": [
      {
        "title": "Wireless Headphones",
        "price": {
          "value": 99.99,
          "currency": "$"
        },
        "store": "Amazon",
        "rating": 4.2,
        "reviews": "2.3k",
        "thumbnail": "https://example.com/product.jpg",
        "product_link": "https://www.google.com/example",
        "old_price": {
          "value": 129.99,
          "currency": "$"
        },
        "snippet": "Noise-canceling wireless headphones with 30-hour battery life",
        "snippet_links": [
          {
            "text": "noise canceling",
            "link": "https://www.google.com/search?q=noise+canceling"
          }
        ]
      }
    ],
    "ads": {
      "title": "Here are some 3D printers to consider",
      "ads": [
        {
          "title": "Bambu Lab X2D",
          "url": "https://www.google.com/aclk?sa=L&ai=abc",
          "position": 1,
          "price": {
            "value": 899,
            "currency": "$"
          },
          "store": "Bambu Lab US",
          "rating": 4.7,
          "reviews": "584"
        }
      ]
    },
    "inline_products": [
      {
        "title": "Sony WH-1000XM5",
        "price": {
          "value": 298,
          "currency": "$"
        },
        "old_price": {
          "value": 399.99,
          "currency": "$"
        },
        "store": "Amazon",
        "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=example",
        "product_link": "https://www.google.com/shopping/product/example"
      }
    ],
    "videos": [
      {
        "title": "The BEST 3D Printer for YOU - Don't Buy the Wrong One!",
        "link": "https://www.youtube.com/watch?v=g0DZnQdI-xQ",
        "platform": "YouTube",
        "channel": "3D Print Dood",
        "duration": "08:49",
        "thumbnail": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcS5Bntg3F0Y7P3YgTPgdyillyeCguV_YQJ99KFUmNYxmQtVt1f2"
      }
    ],
    "map": [
      {
        "title": "Central Park Cafe",
        "link": "https://www.google.com/viewer/place?mid=/g/11bw3yq9kp",
        "place_id": "/g/11bw3yq9kp",
        "index": 0,
        "gps_coordinates": {
          "latitude": 40.7831,
          "longitude": -73.9712
        },
        "thumbnail": "https://lh5.googleusercontent.com/p/example",
        "rating": 4.5,
        "reviews": 1234,
        "type": "Coffee shop",
        "address": "123 Broadway, New York",
        "status": "Open now"
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.cloro.dev/llms.txt

Use this file to discover all available pages before exploring further.

Overview

The Google AI Mode endpoint extracts structured data from Google AI Mode with automatic detection of places, shopping cards, ads, inline products, videos, and map entries.
Web search enabledThis endpoint uses AI Mode’s default interface, which combines web search results with AI-generated responses.

Request parameters

Required parameters:
  • prompt (string): The query to send to AI Mode (1-10,000 characters)
Optional parameters:
  • country (string): ISO 3166-1 alpha-2 country code for localized results. Defaults to US
  • location (string): Google canonical location name for geo-targeted results (e.g., New York,New York,United States). See Google’s geo target list for all ~100,000 supported locations. Mutually exclusive with uule
  • uule (string): Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with location
  • device (string): Device type for search results. Options: desktop (default), mobile
  • include.markdown (boolean): Include markdown-formatted response. Defaults to false
  • include.html (boolean): Include raw HTML response. Defaults to false

Response objects

The response includes the following sections. See each subpage for the full schema and examples.
SectionDescription
SourcesSource citations referenced in the response
PlacesInline place cards when location intent is detected
Shopping cardsProduct carousel when shopping intent is detected
AdsSponsored ad section when commercial intent is detected
Inline productsIndividual product references embedded in the response text
VideosInline video cards (currently YouTube) embedded in the response
MapGPS-enriched location data when map-aware results are surfaced

Response schema

Includes common response fields plus:

Core response fields

FieldTypeDescription
result.textstringAI Mode’s response text
result.markdownstringResponse formatted in Markdown (included when include.markdown is true)
result.sourcesarrayArray of sources referenced in the response
result.placesarrayArray of places (when location intent detected)
result.shopping_cardsarrayArray of shopping cards (when shopping intent detected)
result.adsobjectAd section wrapper with title and ads array (when commercial intent detected)
result.inline_productsarrayArray of inline products found within the response text
result.videosarrayArray of videos embedded in the response (currently YouTube)
result.maparrayArray of map entries with GPS coordinates (when map-aware results surfaced)

Usage examples

City-level geo-targeting

Use location with country to get AI Mode results targeted to a specific city or region. The location parameter accepts Google canonical location names:
{
  "prompt": "best restaurants nearby",
  "country": "US",
  "location": "New York,New York,United States"
}

UULE geo-targeting

For advanced geo-targeting, use uule with a pre-encoded Google UULE string instead of location. This is useful when you generate your own UULE values for precise location control:
{
  "prompt": "best restaurants nearby",
  "country": "US",
  "uule": "w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5"
}
location and uule are mutually exclusive: provide one or the other, not both. Use location for city-level targeting with canonical names, and uule when you need to supply a pre-encoded UULE string.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request parameters for monitoring AI Mode responses

prompt
string
required

The prompt to send to AI Mode

Required string length: 1 - 10000
Example:

"What are the best laptops for programming?"

country
string
default:US

Country/region code for localized response

Example:

"US"

location
string

Google canonical location name for geo-targeted results, in comma-separated format: 'City,Region,Country' (see https://developers.google.com/google-ads/api/reference/data/geotargets for all ~100,000 supported locations). Use alongside 'country' for city-level precision. Mutually exclusive with 'uule' — provide one or the other, not both.

Example:

"New York,New York,United States"

uule
string

Pre-encoded Google UULE string for precise geo-targeting. Use this when you have a pre-built UULE value instead of a location name. Mutually exclusive with 'location' — provide one or the other, not both.

Example:

"w+CAIQICIeV2VzdCBOZXcgWW9yayxOZXcgSmVyc2V5"

device
enum<string>
default:desktop

Device type for search results

Available options:
desktop,
mobile
Example:

"desktop"

include
object

Optional flags for including additional response formats

Response

successful AI Mode monitoring response

success
boolean
required
Example:

true

result
object
required

AI Mode response data