Skip to main content
See Making requests for an overview of both request modes. cloro API monitoring endpoints follow a mostly consistent request and response structure, with the Google Search endpoint being the main exception.

​
Request structure

Most monitoring endpoints follow a consistent request structure: 
{
  "prompt": "Your query here (1-10,000 characters)",
  "country": "US", // Optional, defaults to "US"
  "include": {
    // Optional, varies by endpoint
    "markdown": false,
    "html": false
  }
}

​
Common parameters

Most monitoring endpoints share these core parameters:
ParameterTypeRequiredDescription
promptstringYesThe query to send to the AI provider (1-10,000 characters)
countrystringNoISO 3166-1 alpha-2 country code for localized results. Defaults to "US"
includeobjectNoOptional 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

The API supports country-specific monitoring. Common examples are US (United States) and GB (United Kingdom). For a complete list, see the Countries endpoint.

​
Response structure

All successful responses follow this base structure: 
{
  "success": true,
  "result": {
    "text": "AI response text",
    "sources": [...],
    "html": "https://storage.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

FieldTypeDescription
successbooleanAlways true for successful responses
result.textstringThe AI provider’s response text
result.sourcesarrayArray of sources referenced in the response
result.htmlstringA URL to the full HTML of the response. (included when include.html is true, expires after 24 hours)

​
Response headers

Every response includes an X-Request-Id header containing a unique identifier for the request. Store this value for debugging. It helps our support team locate your request if you need assistance. 
X-Request-Id: b0864943-5d45-4796-bc64-f052661256f0
For rate limit, concurrency, and credit headers, see Credits & limits.

​
Sources array structure

Each source in the sources array follows this format: 
{
  "position": 1,
  "url": "https://example.com/article",
  "label": "Article Title Here",
  "description": "A snippet or summary of the source content..."
}
FieldTypeDescription
positionnumberThe position index of the source
urlstringThe URL of the source
labelstringThe article title of the source
descriptionstringA 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. The URL expires after 24 hours.
  • Cost: no extra charge

​
Markdown format

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

​
Endpoint-specific formats

Different endpoints offer unique formats. See individual endpoint documentation for specific options and features available for each monitoring endpoint. See 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);
}
Remember: These examples use prompt, which is correct for most endpoints. For the Google Search endpoint, replace "prompt" with "query" in your requests.

​
Common questions

​
Can I get raw HTML responses instead of structured data?

Yes, all endpoints support returning HTML responses using the include.html request parameter. No additional credit cost for including HTML. The HTML is stored on our CDN for temporary access (expires after 24 hours). Download and store the HTML if you need it long-term.