Synchronous requests

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:

Parameter	Type	Required	Description
`prompt`	string	Yes	The query to send to the AI provider (1-10,000 characters)
`country`	string	No	ISO 3166-1 alpha-2 country code for localized results. Defaults to `"US"`
`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

The country field requires uppercase ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DK"). Lowercase values are not accepted and will 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://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

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	A 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 Rate & concurrency 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..."
}

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. 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.

Introduction

Guides

Integrations

Synchronous requests

Request structure

Common parameters

Country codes

Response structure

Common response fields

Response headers

Sources array structure

Optional response formats

HTML format

Markdown format

Endpoint-specific formats

Request examples

Common questions

Can I get raw HTML responses instead of structured data?

​Request structure

​Common parameters

​Country codes

​Response structure

​Common response fields

​Response headers

​Sources array structure

​Optional response formats

​HTML format

​Markdown format

​Endpoint-specific formats

​Request examples

​Common questions

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

Request structure

Common parameters

Country codes

Response structure

Common response fields

Response headers

Sources array structure

Optional response formats

HTML format

Markdown format

Endpoint-specific formats

Request examples

Common questions

Can I get raw HTML responses instead of structured data?