Synchronous requests

cloro API monitoring endpoints share a mostly consistent request and response structure. See Making requests for an overview of both request modes.

Request structure

Each provider has its own endpoint (/v1/monitor/chatgpt, /v1/monitor/google, and so on; see Providers). There is no single /v1/monitor path and no model field in the body.

{
  "prompt": "Your query here (1-10,000 characters)",
  "country": "US", // Required, ISO 3166-1 alpha-2 (uppercase)
  "include": {
    // Optional, varies by endpoint
    "markdown": false,
    "html": false
  }
}

Common parameters

Most monitoring endpoints share these core parameters:

Parameter	Type	Required	Description
`prompt`	string	Yes	The query to send to the AI provider (1-10,000 characters)
`country`	string	Yes	Uppercase ISO 3166-1 alpha-2 country code for localized results, e.g. `"US"`. There is no default, and a missing or lowercase code returns a validation error. On Google Search, AI Mode and Google News you can send `gl` (either case) instead. Supported countries vary by provider: see the Countries endpoint
`state`	string	No	US state code for state-level geo-targeting (e.g., `"CA"`), only with `country: "US"`. See state-level targeting for supported providers and cost
`include`	object	No	Optional flags. Most endpoints accept `html` and `markdown` (boolean, default `false`), described in Output formats. Each endpoint page lists its own flags, and Providers lists which ones cost credits

Google Search endpoint exceptionThe Google Search endpoint uses query instead of prompt as the required parameter, since it’s designed for search queries rather than AI prompts. See the Google Search endpoint documentation for details.

Response structure

All successful responses follow this base structure:

{
  "success": true,
  "result": {
    "text": "AI response text",
    "sources": [...],
    "html": "https://cdn.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html",  // only when include.html is true
    // Additional fields vary by endpoint
  }
}

Common response fields

Field	Type	Description
`success`	boolean	Always `true` for successful responses
`result.text`	string	The AI provider’s response text
`result.sources`	array	Array of sources referenced in the response
`result.html`	string \| array	A URL to the full HTML of the response, when `include.html` is `true`. It expires after 24 hours. On Google Search and Google News this is an array of URLs, one per scraped page; on every other endpoint it is a single URL string

Response headers

Every response includes an X-Request-ID header. Store it — our support team uses it to locate your request.

X-Request-ID: b0864943-5d45-4796-bc64-f052661256f0

For rate limit, concurrency, and credit headers, see Rate & concurrency limits.

Sources array structure

{
  "position": 1,
  "url": "https://example.com/article",
  "label": "Article Title Here",
  "description": "A snippet or summary of the source content..."
}

Field	Type	Description
`position`	number	The position index of the source
`url`	string	The URL of the source
`label`	string	The article title of the source
`description`	string	A snippet or summary of the source content

Some endpoints include additional source fields. See individual endpoint documentation for endpoint-specific source fields.

Request examples

curl -X POST "https://api.cloro.dev/v1/monitor/chatgpt" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What do you know about Acme Corp?",
    "country": "US",
    "include": {
      "markdown": true,
      "html": true
    }
  }'

import requests

response = requests.post(
    "https://api.cloro.dev/v1/monitor/chatgpt",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "What do you know about Acme Corp?",
        "country": "US",
        "include": {"markdown": True, "html": True}
    }
)

result = response.json()
print(result['result']['text'])
print(result['result']['sources'])
if 'html' in result['result']:
    print(result['result']['html'])
if 'markdown' in result['result']:
    print(result['result']['markdown'])

const response = await fetch("https://api.cloro.dev/v1/monitor/chatgpt", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "What do you know about Acme Corp?",
    country: "US",
    include: { markdown: true, html: true },
  }),
});

const data = await response.json();
console.log(data.result.text);
console.log(data.result.sources);
if (data.result.html) {
  console.log(data.result.html);
}
if (data.result.markdown) {
  console.log(data.result.markdown);
}

Introduction

Guides

Integrations

Synchronous requests

Request structure

Common parameters

Response structure

Common response fields

Response headers

Sources array structure

Request examples

​Request structure

​Common parameters

​Response structure

​Common response fields

​Response headers

​Sources array structure

​Request examples

Request structure

Common parameters

Response structure

Common response fields

Response headers

Sources array structure

Request examples