Python SDK

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.

Prerequisites

Python 3.8 or newer
A cloro API key from the dashboard (see Authentication)

Install the package

pip install cloro

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

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.

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.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–10). The client exposes client.countries() and client.states() for the supported countries and states.

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

Exception	Meaning
`AuthenticationError`	`401` — missing or invalid API key
`BadRequestError`	`400` — malformed request or failed validation
`PermissionDeniedError`	`403` — key not allowed for this action, or insufficient credits
`NotFoundError`	`404` — resource does not exist
`ConflictError`	`409` — conflicts with current state (e.g. concurrency limit)
`RateLimitError`	`429` — too many requests
`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

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

Introduction

Guides

Integrations

Prerequisites

Install the package

Configure your API key

Quickstart

Every engine, one client

Async task queue

Reliability and configuration

Error handling

Next steps

​Prerequisites

​Install the package

​Configure your API key

​Quickstart

​Every engine, one client

​Async task queue

​Reliability and configuration

​Error handling

​Next steps

Prerequisites

Install the package

Configure your API key

Quickstart

Every engine, one client

Async task queue

Reliability and configuration

Error handling

Next steps