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

,

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

on npm

cloro-node 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

JavaScript & Node API guide

Python SDK

Google SERP API

Making requests

Providers

Billing & credits