> ## Documentation Index
> Fetch the complete documentation index at: https://cloro.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Synchronous requests
> Make synchronous requests to the cloro API: request structure, common parameters, response shape, optional formats, and code examples.
See [Making requests](/guides/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:
```json theme={null}
{
"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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) 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 exception**
The 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](/api-reference/endpoint/monitor-google) 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](/api-reference/endpoint/countries).
## Response structure
All successful responses follow this base structure:
```json theme={null}
{
"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](#sources-array-structure) 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 [Credits & limits](/guides/credits-and-limits).
## Sources array structure
Each source in the `sources` array follows this format:
```json theme={null}
{
"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](/guides/providers) for endpoint costs and credit information.
## Request examples
```bash theme={null}
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
}
}'
```
```python theme={null}
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'])
```
```javascript theme={null}
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.