Skip to main content
POST
/
v1
/
monitor
/
aioverview
Monitor AI Overview Responses
curl --request POST \
  --url https://api.cloro.dev/v1/monitor/aioverview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "What are the best laptops for programming?",
  "country": "US",
  "include": {
    "markdown": false
  }
}'
{
  "success": true,
  "result": {
    "text": "Based on current information, here are some excellent laptop options for programming...",
    "html": "<div class=\"ai-overview\"><p>Based on current information, here are some excellent laptop options...</p></div>",
    "sources": [
      {
        "position": 1,
        "url": "https://example.com/laptops",
        "label": "Tech Reviews",
        "description": "Comprehensive laptop guide for developers"
      }
    ],
    "markdown": "Based on current information, here are some excellent laptop options for programming..."
  }
}

​
Overview

The Google AI Overview endpoint allows you to extract structured data from Google’s AI Overview about your brand, products, or any topic across various regions. This endpoint processes your prompts through Google AI Overview and returns parsed responses with sources & citations.

​
Request Parameters

​
Required Parameters

  • prompt (string): The prompt to send to Google AI Overview (1-10,000 characters)

​
Optional Parameters

  • country (string): Optional country/region code for localized data extraction. Defaults to "US"
  • include (object): Optional flags for including additional response formats
    • markdown (boolean): Include markdown-formatted response in the result. Defaults to false

​
Response Format Options

By default, all responses include both text and HTML formats. You can optionally include markdown:
ParameterDefaultDescriptionUse casesCost
include.markdownfalseInclude markdown-formatted response in the resultDocumentation, content integration4 credits

​
Example Usage

​
Basic Request

{
  "prompt": "What are the best laptops for programming?"
}

​
Request with Markdown Format

{
  "prompt": "What are the best cloud hosting providers for startups?",
  "country": "US",
  "include": {
    "markdown": true
  }
}

​
Response Schema

All successful responses include these fields:
FieldTypeDescription
successbooleanAlways true for successful responses
result.textstringGoogle AI Overview’s response text
result.sourcesarrayArray of sources referenced in the response
result.htmlstringGoogle AI Overview’s response formatted in HTML (always included)
result.markdownstringGoogle AI Overview’s response formatted in Markdown (included when include.markdown is true)

​
Error Responses

The API returns standard HTTP status codes to indicate the success or failure of requests. All error responses follow a consistent format with an error object containing a code, message, details, and timestamp.

​
Status Codes

  • 200 - Success
  • 400 - Bad Request (validation error)
  • 401 - Unauthorized (authentication error)
  • 403 - Forbidden (insufficient permissions or credits)
  • 404 - Not Found (route not found)
  • 409 - Conflict (resource conflict)
  • 429 - Too Many Requests
  • 499 - Client Closed Request (request was canceled)
  • 500 - Internal Server Error
  • 502 - Bad Gateway (external service error)

​
Validation Errors

FieldErrorDescription
prompt”Prompt cannot be empty”Must be 1-10,000 characters
prompt”Prompt is too long”Exceeds 10,000 character limit
country”Invalid country code”Must be valid ISO 3166-1 alpha-2 code
include.markdown”Expected boolean”Must be true or false

​
Concurrency Information

Concurrency information is included in response headers:
  • X-Concurrent-Limit: Maximum number of concurrent requests allowed
  • X-Concurrent-Current: Current number of concurrent requests
  • X-Concurrent-Remaining: Number of remaining concurrent slots available

​
Credits System

This endpoint uses a credit-based billing system:
  • Base cost: 4 credits per request
  • Additional costs: +0 credits (markdown format is included at no extra charge)
Credit information is included in response headers:
  • X-Credits-Remaining: Number of credits remaining in your account
  • X-Credits-Charged: Number of credits charged for this request

​
Supported Country Codes

The API accepts ISO 3166-1 alpha-2 country codes for the country parameter to extract data from different regions. For a complete list of supported country codes, see the Countries endpoint. Common Examples:
  • US - United States
  • GB - United Kingdom
  • CA - Canada
  • AU - Australia
  • DE - Germany
  • FR - France
  • JP - Japan
  • CN - China
  • IN - India
  • BR - Brazil

​
Best Practices

​
Prompt Guidelines

  1. Be Specific: Include specific topics, brands, or questions for more accurate AI Overview responses
  2. Use Clear Questions: Frame prompts as clear questions to get better structured responses
  3. Include Context: Add relevant context when asking about specific industries or use cases

​
Implementation Guidelines

  1. Handle Source Data: Process the sources array to provide citations and reference links
  2. Use Markdown: Enable markdown format when you need to integrate responses into documentation systems
  3. Error Handling: Implement robust error handling for failed extraction requests
  4. Rate Limiting: Respect concurrency limits and implement proper retry logic
  5. Data Validation: Validate source URLs and content before using them in your application

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 Overview responses

​
prompt
string
required

The prompt to send to AI Overview

Required string length: 1 - 10000
Example:

"What are the best laptops for programming?"

​
country
string
default:US

Optional country/region code for localized monitoring

Example:

"US"

​
include
object

Optional flags for including additional response formats

Response

successful AI Overview monitoring response

​
success
boolean
required
Example:

true

​
result
object
required

AI Overview response data