TypeScript SDK - cloro
Integrations
TypeScript SDK
Official cloro TypeScript/Node SDK: install, authenticate, and call Google Search, ChatGPT, Gemini, AI Mode, and Google News.
The
@cloro-dev/cloro
npm package is the official TypeScript/Node 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. It ships ESM and CommonJS builds with bundled type declarations; the source lives in the
cloro-node repository
.
Navigate to header: Prerequisites Prerequisites
Node 18 or newer (uses the built-in fetch )
A cloro API key from the dashboard (see Authentication )
Navigate to header: Install the package Install the package
npm
install
@cloro-dev/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:
import
{
Cloro
}
from
"@cloro-dev/cloro"
;
const
client
=
new
Cloro
({
apiKey:
"YOUR_API_KEY"
});
Navigate to header: Quickstart Quickstart
import
{
Cloro
}
from
"@cloro-dev/cloro"
;
const
client
=
new
Cloro
();
// reads CLORO_API_KEY
const
res
=
await
client
.
monitor
.
chatgpt
({
prompt:
"What do you know about Acme Corp?"
,
country:
"US"
,
include:
{
markdown:
true
},
});
console
.
log
(
res
.
result
.
text
);
for
(
const
source
of
res
.
result
.
sources
) {
console
.
log
(
source
.
position
,
source
.
url
,
source
.
label
);
}
Every call resolves with 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.bingAimode({ prompt, country }) | POST /v1/monitor/bing/aimode |
| client.monitor.googleNews({ 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.
createBatch
submits up to 500 tasks in one request;
wait
polls a task to completion with interval backoff. See
Async requests
.
import
{
Cloro
}
from
"@cloro-dev/cloro"
;
const
client
=
new
Cloro
();
const
KEYWORDS
=
[
"best running shoes"
,
"trail running shoes"
,
"waterproof running shoes"
];
// Enqueue up to 500 tasks in a single call.
const
results
=
await
client
.
asyncTasks
.
createBatch
(
KEYWORDS
.
map
((
kw
)
=>
({
taskType:
"GOOGLE"
,
payload:
{
query:
kw
,
country:
"US"
} })),
);
for
(
const
item
of
results
) {
if
(
item
.
success
) {
const
done
=
await
client
.
asyncTasks
.
wait
(
item
.
task
.
id
);
const
organic
=
done
.
response
.
organicResults
;
if
(
organic
?.
length
) {
console
.
log
(
item
.
task
.
id
,
"→"
,
organic
[
0
].
link
);
}
else
{
console
.
log
(
item
.
task
.
id
,
"→ no results"
);
}
}
else
{
console
.
log
(
"failed:"
,
item
.
error
.
message
);
}
}
For a single task,
client.asyncTasks.run({ taskType, payload })
creates it and resolves once it completes. Valid
taskType
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:
new Cloro({ maxRetries: 2, timeout: 300000 })
(timeout in milliseconds; 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 optional chaining (
?.
) 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
instanceof CloroError
check catches everything. HTTP failures map to status-specific types:
import
{
Cloro
,
AuthenticationError
,
RateLimitError
,
CloroError
}
from
"@cloro-dev/cloro"
;
const
client
=
new
Cloro
();
try
{
const
res
=
await
client
.
monitor
.
chatgpt
({
prompt:
"..."
,
country:
"US"
});
}
catch
(
err
) {
if
(
err
instanceof
AuthenticationError
) {
// 401 — bad or missing API key
}
else
if
(
err
instanceof
RateLimitError
) {
// 429 — the client already retried; back off further if it persists
}
else
if
(
err
instanceof
CloroError
) {
// everything else
}
else
{
throw
err
;
}
}
| 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
JavaScript & Node API guide — the landing-page walkthrough with recipes, pricing, and production patterns
Python SDK — the same client surface in Python
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-node on GitHub and on npm
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