The cloro API for JavaScript & Node

Quickstart

Install the SDK, store your API key in the environment, and make your first call. The cloro SDK wraps proxies, rendering, and anti-bot logic on the server — whether you're hitting the Google SERP API or an AI engine like ChatGPT — so your Node code shrinks to one method call and a parse. Prefer Python? See the cloro API for Python.

npm install @cloro-dev/cloro

Store your key in the environment — never hardcode secrets:

export CLORO_API_KEY="sk-..."

Authenticate and make the first call:

import { Cloro } from "@cloro-dev/cloro";

// Reads your key from the CLORO_API_KEY environment variable.
const client = new Cloro();

// Google Search — structured SERP JSON, no proxies or selectors.
const serp = await client.monitor.google({ query: "best running shoes", country: "US" });
for (const item of serp.result.organicResults) {
  console.log(item.position, item.link);
}

// Any AI engine is the same client — just change the method.
const answer = await client.monitor.chatgpt({
  prompt: "What do you know about Acme Corp?",
  country: "US",
});
console.log(answer.result.text);

Every engine, one client

Google Search and every AI engine share one client and one credit pool. You add coverage by changing the method — each maps to one endpoint, shown below — not by writing a new scraper per engine.

Base URL: https://api.cloro.dev. Full request and response schemas live in the API docs, and the TypeScript SDK reference documents every client method.

Recipe 1: rank tracker across countries

The most common production job: a nightly tracker that checks a keyword list across several markets and writes results to JSONL you can load into a warehouse or a database. It fans out 300 queries (100 keywords × 3 countries) across a capped pool of concurrent requests. For the endpoint-level detail, see the Google rank tracking API guide.

import { writeFile } from "node:fs/promises";
import { Cloro } from "@cloro-dev/cloro";

// The client reads CLORO_API_KEY and retries 429/5xx with backoff for you.
const client = new Cloro();

const KEYWORDS = [
  "best running shoes",
  "trail running shoes men",
  "waterproof running shoes",
  // ... up to 100
];
const COUNTRIES = ["US", "GB", "DE"];
const TARGET_DOMAIN = "nike.com";
const MAX_CONCURRENCY = 10; // match your plan's concurrency limit, not your CPU count

interface Row {
  date: string;
  query: string;
  country: string;
  rank: number | null;
  inAiOverview: boolean;
}

async function fetchOne(query: string, country: string): Promise<Row> {
  const res = await client.monitor.google({
    query,
    country,
    include: { aioverview: { markdown: true } },
  });
  const result = res.result;
  const hit = result.organicResults.find((item: any) =>
    (item.link ?? "").includes(TARGET_DOMAIN),
  );
  const aioSources = JSON.stringify(result.aioverview?.sources ?? []);
  return {
    date: new Date().toISOString().slice(0, 10),
    query,
    country,
    rank: hit ? hit.position : null,
    inAiOverview: aioSources.includes(TARGET_DOMAIN),
  };
}

async function runTracker(outputPath = "ranks.jsonl"): Promise<void> {
  const tasks = KEYWORDS.flatMap((kw) => COUNTRIES.map((c) => [kw, c] as const));
  const rows: Row[] = [];

  // Concurrency-capped worker pool — fan out without flooding the API.
  let cursor = 0;
  async function worker(): Promise<void> {
    while (cursor < tasks.length) {
      const [kw, c] = tasks[cursor++];
      try {
        rows.push(await fetchOne(kw, c));
        console.log(`OK  ${kw} / ${c}`);
      } catch (err) {
        console.log(`ERR ${kw} / ${c}: ${(err as Error).message}`);
      }
    }
  }
  await Promise.all(Array.from({ length: MAX_CONCURRENCY }, worker));

  await writeFile(outputPath, rows.map((r) => JSON.stringify(r)).join("\n") + "\n");
  console.log(`\nDone. ${rows.length} rows written to ${outputPath}`);
}

runTracker();

SERP calls are I/O-bound, so a small pool of concurrent promises is the right tool here. Cap MAX_CONCURRENCY at your plan's concurrency limit, and keep each returned row flat so it writes cleanly to JSONL, CSV, or a column.

Recipe 2: AI visibility across ChatGPT, Perplexity & Gemini

Rank tracking no longer stops at Google. If your brand appears in a ChatGPT answer but not a Perplexity citation, that gap is worth measuring. Each AI engine is a separate endpoint on the same credit pool — notice how little changes from the rank-tracker code above.

import { Cloro } from "@cloro-dev/cloro";

const client = new Cloro();

// Same client, same call shape — only the method changes per engine.
const ENGINES = {
  chatgpt: (prompt: string) => client.monitor.chatgpt({ prompt, country: "US" }),
  perplexity: (prompt: string) => client.monitor.perplexity({ prompt, country: "US" }),
  gemini: (prompt: string) => client.monitor.gemini({ prompt, country: "US" }),
};

const BRAND_QUERIES = [
  "best electric SUV 2026",
  "tesla model y vs competitors",
  "ev range comparison",
];
const TARGET_BRAND = "tesla.com";

async function runAiVisibilityAudit() {
  const results = [];
  for (const prompt of BRAND_QUERIES) {
    for (const [engine, call] of Object.entries(ENGINES)) {
      try {
        const { result } = await call(prompt);
        const sources = result.sources ?? [];
        const brandCited = sources.some((s: any) => (s.url ?? "").includes(TARGET_BRAND));
        results.push({ engine, prompt, brandCited, answer: (result.text ?? "").slice(0, 200) });
        const status = brandCited ? "cited" : "not cited";
        console.log(`[${engine}] ${prompt.slice(0, 40)}... -> ${status}`);
      } catch (err) {
        console.log(`ERR [${engine}] ${prompt.slice(0, 40)}...: ${(err as Error).message}`);
      }
    }
  }
  return results;
}

const rows = await runAiVisibilityAudit();
const cited = rows.filter((r) => r.brandCited).length;
console.log(`\n${cited}/${rows.length} queries cite ${TARGET_BRAND} across AI engines`);

This is the foundation of AI visibility monitoring: tracking where your brand surfaces (or doesn't) in generative answers alongside traditional search. You add engines by adding endpoints, not by writing new scrapers.

Production concerns

Five things separate a script that works once from one that runs on a schedule:

• Retries are built in. The client retries 429 and 5xx responses with exponential backoff automatically — tune it with new Cloro({ maxRetries: 3 }).
• Cap concurrency. Match your in-flight request count to your plan's concurrency limit with a worker pool or a library like p-limit — set it to the plan limit, not an arbitrary number.
• Scale with the task queue. When you need hundreds of queries per minute, enqueue them with client.asyncTasks.createBatch() and poll — the queue absorbs concurrency and retries instead of you hand-tuning a pool.
• Keep secrets out of code. Load the key from an environment variable or a .env file, add .env to .gitignore, and rotate any key that lands in a commit.
• Access fields defensively. Use optional chaining (?.) and nullish defaults — response shapes evolve, and not every query returns an AI Overview box.

Batching high-volume work through the async task queue looks like this:

import { Cloro } from "@cloro-dev/cloro";

const client = new Cloro();

const KEYWORDS = ["best running shoes", "trail shoes", "waterproof boots"];

// Enqueue up to 500 tasks in one request, then poll each to completion.
// The queue absorbs concurrency and retries — no Semaphore to hand-tune.
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 top = done.response.result.organicResults[0];
    console.log(item.task.id, "->", top.link);
  } else {
    console.log("failed:", item.error.message);
  }
}

Error handling

The SDK throws typed errors, all subclassing CloroError. Catch the ones you want to handle specially and let the transient ones (which the client already retries) bubble. They map to the underlying HTTP status codes:

import {
  Cloro,
  AuthenticationError,
  BadRequestError,
  RateLimitError,
  CloroError,
} from "@cloro-dev/cloro";

const client = new Cloro();

try {
  const res = await client.monitor.google({ query: "best running shoes", country: "US" });
  // ... use res.result
} catch (err) {
  if (err instanceof AuthenticationError) {
    throw new Error("Invalid or missing CLORO_API_KEY");
  } else if (err instanceof BadRequestError) {
    throw new Error(`Bad request: ${err.message}`);
  } else if (err instanceof RateLimitError) {
    // the client already retried; back off further if this persists
  } else if (err instanceof CloroError) {
    throw err; // timeouts, 5xx, task failures — all subclass CloroError
  } else {
    throw err;
  }
}