Synchronous requests - cloro
Types of requests
Synchronous requests
Make synchronous requests to the cloro API: request structure, common parameters, response shape, and code examples.
cloro API monitoring endpoints share a mostly consistent request and response structure. See
Making requests
for an overview of both request modes.
Navigate to header: Request structure 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"
,
"include"
: {
"markdown"
:
false
,
"html"
:
false
}
}
Navigate to header: Common parameters 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 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
for details.
Navigate to header: Response structure 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
}
}
Navigate to header: Common response fields 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 |
Navigate to header: Response headers 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
.
Navigate to header: Sources array structure Sources array structure
{
"position"
:
1
,
"url"
:
,
"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.
Navigate to header: Request examples 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()
(result[
'result'
][
'text'
])
(result[
'result'
][
'sources'
])
if
'html'
in
result[
'result'
]:
(result[
'result'
][
'html'
])
if
'markdown'
in
result[
'result'
]:
(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
);
}
Was this page helpful?
Ask a question...
ISO 3166-1 alpha-2 country code
Google Search endpoint documentation
Navigate to header: Sources array structure
Navigate to header: Request structure
Navigate to header: Common parameters
Navigate to header: Response structure
Navigate to header: Common response fields