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",
  "include": {
    "markdown": false
  }
}'
{
  "success": true,
  "result": {
    "text": "Here are some excellent laptop recommendations for programming...",
    "html": "<div class=\"ai-mode-response\"><p>Here are some excellent laptop recommendations...</p></div>",
    "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..."
  }
}

​
Overview

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

​
Request Parameters

​
Required Parameters

  • prompt (string): The prompt to send to Google AI Mode (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 emerging trends in artificial intelligence?"
}

​
Request with Markdown Format

{
  "prompt": "How can I improve my software development workflow?",
  "country": "US",
  "include": {
    "markdown": true
  }
}

​
Response Schema

All successful responses include these fields:
FieldTypeDescription
successbooleanAlways true for successful responses
result.textstringGoogle AI Mode’s response text
result.sourcesarrayArray of sources referenced in the response
result.htmlstringGoogle AI Mode’s response formatted in HTML (always included)
result.markdownstringGoogle AI Mode’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. General Questions: AI Mode works well with general knowledge and advice questions
  2. Workflow Optimization: Ask about improving processes, productivity, or best practices
  3. Technical Guidance: Frame prompts around technical guidance and recommendations

​
Implementation Guidelines

  1. Handle AI Sources: Process sources array to provide AI-curated references
  2. Use Markdown: Enable markdown format for better content integration
  3. Error Handling: Implement robust error handling for failed extraction requests
  4. Rate Limiting: Respect concurrency limits and implement proper retry logic
  5. Content Validation: Validate AI-generated content before using it 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 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

Optional country/region code for localized monitoring

Example:

"US"

​
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