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

{
  "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	ISO 3166-1 alpha-2 country code (uppercase) for localized results. There is no default — requests without `country` return a validation error
`state`	string	No	Sub-country state or region code for state-level geo-targeting (e.g., `"CA"`). Currently only supported for `country: "US"`. Supported on ChatGPT, Copilot, Perplexity, and Gemini.
`include`	object	No	Optional flags for additional response formats

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.

Country codes must be uppercase ("US", "GB", "DK") — lowercase values return a validation error. For the full list of supported countries per provider, see the Countries endpoint.

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 included when "include.html": true, expires after 24 hours
    // 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 (included when `include.html` is `true`, 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.

Optional response formats

Most endpoints support additional response formats through the include parameter:

HTML format

Parameter: include.html
Type: boolean
Default: false
Description: Request a URL to the full HTML of the response — an array of URLs, one per page, on Google Search and Google News. URLs expire after 24 hours, so download the HTML if you need it long-term.
Cost: no extra charge

Markdown format

Parameter: include.markdown
Type: boolean
Default: false
Description: Include response formatted in Markdown
Cost: no extra charge

Individual endpoints offer their own formats and features — see the endpoint documentation for each, and Providers for endpoint costs and credit information.

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

Optional response formats

HTML format

Markdown format

Request examples

​Request structure

​Common parameters

​Response structure

​Common response fields

​Response headers

​Sources array structure

​Optional response formats

​HTML format

​Markdown format

​Request examples

Request structure

Common parameters

Response structure

Common response fields

Response headers

Sources array structure

Optional response formats

HTML format

Markdown format

Request examples