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
},
)
(res[
"result"
][
"text"
])
for
source
in
res[
"result"
][
"sources"
]:
(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:
(item[
"task"
][
"id"
],
"→"
, organic[
0
][
"link"
])
else
:
(item[
"task"
][
"id"
],
"→ no results"
)
else
:
(
"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_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...
Navigate to header: Prerequisites
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