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"

:

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

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()

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

);

}

Was this page helpful?

Ask a question...

Making requests

Providers

ISO 3166-1 alpha-2 country code

Countries endpoint

state-level targeting

Output formats

Google Search endpoint documentation

Navigate to header: Sources array structure

expires after 24 hours

Rate & concurrency limits

Navigate to header: Request structure

Navigate to header: Common parameters

Navigate to header: Response structure

Navigate to header: Common response fields

Navigate to header: Response headers

Navigate to header: Request examples