Python SDK - cloro

Integrations

Python SDK

Official cloro Python SDK reference: install, authenticate, and call Google Search, ChatGPT, Gemini, AI Mode, and Google News.

The

cloro

Python package is the official SDK for the cloro API — one typed client for Google Search and every AI answer engine, where each call is a single authenticated request that returns structured JSON with sources. The source lives in the

cloro-python repository

.

Navigate to header: Prerequisites Prerequisites

Python 3.8 or newer

A cloro API key from the dashboard (see Authentication )

Navigate to header: Install the package Install the package

pip

install

cloro

Navigate to header: Configure your API key Configure your API key

The client reads

CLORO_API_KEY

from the environment automatically:

export

CLORO_API_KEY

=

"YOUR_API_KEY"

Or pass it to the constructor:

from

cloro

import

Cloro

client

=

Cloro(

api_key

=

"YOUR_API_KEY"

)

Navigate to header: Quickstart Quickstart

from

cloro

import

Cloro

client

=

Cloro()

# reads CLORO_API_KEY

res

=

client.monitor.chatgpt(

prompt

=

"What do you know about Acme Corp?"

,

country

=

"US"

,

include

=

{

"markdown"

:

True

},

)

print

(res[

"result"

][

"text"

])

for

source

in

res[

"result"

][

"sources"

]:

print

(source[

"position"

], source[

"url"

], source[

"label"

])

Every call returns the

{"success": ..., "result": {...}}

envelope. Pass

include={...}

to request extra formats (

markdown

,

html

,

searchQueries

,

shopping

, and more, depending on the engine).

Navigate to header: Every engine, one client Every engine, one client

AI engines take a

prompt

; Google Search and Google News take a

query

. Each method is a thin wrapper over one endpoint.

Method Endpoint
client.monitor.google(query, country) POST /v1/monitor/google
client.monitor.chatgpt(prompt, country) POST /v1/monitor/chatgpt
client.monitor.gemini(prompt, country) POST /v1/monitor/gemini
client.monitor.aimode(prompt, country) POST /v1/monitor/aimode
client.monitor.bing_aimode(prompt, country) POST /v1/monitor/bing/aimode
client.monitor.google_news(query, country) POST /v1/monitor/google/news

client.monitor.google

also accepts

location

,

uule

,

device

, and

pages

(1–10). The client exposes

client.countries()

and

client.states()

for the

supported countries

and states.

Navigate to header: Async task queue Async task queue

For large batches, don’t loop synchronous calls — enqueue tasks and poll them.

create_batch

submits up to 500 tasks in one request;

wait

polls a task to completion with interval backoff. See

Async requests

.

from

cloro

import

Cloro

client

=

Cloro()

KEYWORDS

=

[

"best running shoes"

,

"trail running shoes"

,

"waterproof running shoes"

]

# Enqueue up to 500 tasks in a single call.

results

=

client.async_tasks.create_batch(

[{

"task_type"

:

"GOOGLE"

,

"payload"

: {

"query"

: kw,

"country"

:

"US"

}}

for

kw

in

KEYWORDS

]

)

for

item

in

results:

if

item[

"success"

]:

done

=

client.async_tasks.wait(item[

"task"

][

"id"

])

organic

=

done[

"response"

][

"organicResults"

]

if

organic:

print

(item[

"task"

][

"id"

],

"→"

, organic[

0

][

"link"

])

else

:

print

(item[

"task"

][

"id"

],

"→ no results"

)

else

:

print

(

"failed:"

, item[

"error"

][

"message"

])

For a single task,

client.async_tasks.run(task_type=..., payload=...)

creates it and blocks until it completes. Valid

task_type

values:

CHATGPT

,

GEMINI

,

AIMODE

,

BING_AIMODE

,

GOOGLE

,

GOOGLE_NEWS

.

Navigate to header: Reliability and configuration Reliability and configuration

The client retries timeouts, connection errors, and

429

/

5xx

responses with exponential backoff. Its default timeout is 300 seconds, the minimum the docs advise for a sync request. To set it yourself:

Cloro(max_retries=2, timeout=300.0)

(see

Retries and cancellation

). Cap your own concurrency to your plan’s limit (see

Concurrency

), read the key from

CLORO_API_KEY

rather than hardcoding it, and access response fields with

.get()

since shapes vary by query (a Google result with no AI Overview omits

aioverview

).

Navigate to header: Error handling Error handling

Every error subclasses

CloroError

, so one

except CloroError

catches everything. HTTP failures map to status-specific types:

from

cloro

import

Cloro, AuthenticationError, RateLimitError, CloroError

client

=

Cloro()

try

:

res

=

client.monitor.chatgpt(

prompt

=

"..."

,

country

=

"US"

)

except

AuthenticationError:

...

# 401 — bad or missing API key

except

RateLimitError:

...

# 429 — the client already retried; back off further if it persists

except

CloroError

as

exc:

...

# everything else

Exception Meaning
AuthenticationError 401 — missing or invalid API key
BadRequestError 400 — malformed request or failed validation
PermissionDeniedError 403 — insufficient credits
NotFoundError 404 — resource does not exist
ConflictError 409 — an async task with that idempotencyKey already exists
RateLimitError 429 — rate, concurrency, or queue limit exceeded
InternalServerError 5xx — the API failed to process the request
APITimeoutError request timed out before a response
TaskFailedError / TaskTimeoutError async task failed, or did not finish within the poll timeout

Navigate to header: Next steps Next steps

Python API guide — the landing-page walkthrough with recipes, pricing, and production patterns

TypeScript SDK — the same client surface in TypeScript/Node

Python web scraping pillar — Python data-extraction fundamentals

Google SERP API — the SERP endpoint this SDK wraps

Making requests — the raw sync and async HTTP contracts

Providers and Billing & credits — per-engine credit costs

API reference — full request and response schemas

cloro-python on GitHub and on PyPI

Was this page helpful?

Ask a question...

on PyPI

cloro-python on GitHub

API reference

POST /v1/monitor/chatgpt

POST /v1/monitor/gemini

POST /v1/monitor/aimode

POST /v1/monitor/bing/aimode

POST /v1/monitor/google/news

supported countries

async

Retries and cancellation

Concurrency

Navigate to header: Prerequisites

dashboard

Authentication

Navigate to header: Install the package

Navigate to header: Configure your API key

Navigate to header: Quickstart

Navigate to header: Every engine, one client

Navigate to header: Async task queue

Navigate to header: Reliability and configuration

Navigate to header: Error handling

Navigate to header: Next steps

Python API guide

TypeScript SDK

Python web scraping pillar

Google SERP API

Making requests

Providers

Billing & credits