Skip to main content
The cloro Python package is the official SDK for the cloro API — one typed client for Google Search and every AI answer engine. Each call is a single authenticated request that returns structured JSON with sources; there are no proxies, headless browsers, or selectors to maintain. The source lives in the cloro-python repository. This page is the SDK reference. For a guided walkthrough with recipes, cost math, and production patterns, see the Python API guide. Prefer raw HTTP? Every method below maps to one endpoint you can call directly — see Making requests.

​
Prerequisites

​
Install the package

pip install cloro

​
Configure your API key

Set the key as an environment variable — the client reads CLORO_API_KEY automatically: 
export CLORO_API_KEY="YOUR_API_KEY"
Or pass it directly when constructing the client: 
from cloro import Cloro

client = Cloro(api_key="YOUR_API_KEY")

​
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).

​
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.
MethodEndpoint
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.perplexity(prompt, country)POST /v1/monitor/perplexity
client.monitor.copilot(prompt, country)POST /v1/monitor/copilot
client.monitor.grok(prompt, country)POST /v1/monitor/grok
client.monitor.aimode(prompt, country)POST /v1/monitor/aimode
client.monitor.google_news(query, country)POST /v1/monitor/google/news
client.monitor.google also accepts location, uule, device, and pages (1–20). The client exposes client.countries() and client.states() for the supported countries and states.
client.monitor.grok is available, but the provider is temporarily unavailable — calls to it will fail until Grok access is restored.

​
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"]["result"]["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, PERPLEXITY, COPILOT, GROK, AIMODE, GOOGLE, GOOGLE_NEWS.

​
Reliability and configuration

The client retries timeouts, connection errors, and 429/5xx responses with exponential backoff — tune it with Cloro(max_retries=2, timeout=60.0). 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).

​
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
ExceptionMeaning
AuthenticationError401 — missing or invalid API key
BadRequestError400 — malformed request or failed validation
PermissionDeniedError403 — key not allowed for this action
NotFoundError404 — resource does not exist
ConflictError409 — conflicts with current state (e.g. concurrency limit)
RateLimitError429 — too many requests
InternalServerError5xx — the API failed to process the request
APITimeoutErrorrequest timed out before a response
TaskFailedError / TaskTimeoutErrorasync task failed, or did not finish within the poll timeout

​
Next steps