Node.js SDK

npm install zenrows

import { ZenRowsBatchClient } from "zenrows";

const client = new ZenRowsBatchClient("YOUR_ZENROWS_API_KEY");

const job = await client.submitRegular(
  [
    "https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie",
    "https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket",
  ],
  undefined,
  { zenrowsParams: { js_render: "true", premium_proxy: "true" } },
);

const run = await job.run.wait({ timeout: 1800 });
console.log(`${run.data.stats.successful}/${run.data.stats.total} succeeded`);

for await (const row of run.results({ status: "successful" })) {
  console.log(row.external_id ?? row.task_id, "->", row.result_url);
}

const job = await client.submitRegular(
  ["https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie"],
  undefined,
  {
    zenrowsParams: {
      js_render: "true",
      premium_proxy: "true",
      proxy_country: "us",
      wait_for: ".price",
      response_type: "markdown", // markdown | plaintext | pdf; omit it for HTML
    },
  },
);

const job = await client.submitRegular(
  [
    { url: "https://www.scrapingcourse.com/ecommerce/product/artemis-running-short",
      external_id: "order-42", zenrows_params: { proxy_country: "de" } },
    { url: "https://www.scrapingcourse.com/ecommerce/product/atomic-endurance-tee",
      external_id: "order-43", metadata: { sku: "ABC-1" } },
    { url: "https://httpbin.io/post", method: "POST", body: { q: "running shoes" } },
  ],
  undefined,
  { zenrowsParams: { premium_proxy: "true" } },
);

// One file per task, client-side, tune parallelism:
const saved = await client.job(jobId).run.downloadToDir("./out", {
  concurrency: 8,
  // onSkip gets a SkippedResult { taskId, externalId, url, status }, not a raw result row.
  onSkip: (skipped) => console.log("skipped", skipped.taskId, skipped.status),
});
console.log(`saved ${saved} files`);

// The whole run as one server-side zip:
await client.job(jobId).run.downloadAllResults("results.zip");

// A single task's body, to disk or memory, inside a loop:
for await (const row of run.results({ status: "successful" })) {
  if (!row.result_url) continue; // expired: past the retention window
  await run.downloadTaskToFile(row, `./out/${row.task_id}`);
  // or: const body: Buffer = await run.downloadTaskToMemory(row);
}

const job = await client.submitOpen(undefined, { zenrowsParams: { js_render: "true" } });

await job.addTasks([{ url: "https://www.scrapingcourse.com/ecommerce/page/1" }], {
  idempotencyKey: "pages-batch-1",
});
await job.addTasks([{ url: "https://www.scrapingcourse.com/ecommerce/page/2" }], {
  idempotencyKey: "pages-batch-2",
  lastBatch: true,
});

const run = await job.run.wait({ timeout: 1800 });

import { readFileSync } from "node:fs";

const fileInputId = await client.uploadCsv(readFileSync("urls.csv"), {
  fields: { url: "URL", external_id: "Customer Ref" }, // column name (with header: true) or 0-based index
  header: true,
});
const job = await client.submitRegular(undefined, fileInputId, {
  zenrowsParams: { js_render: "true" },
});

for await (const job of client.iterJobs({ type: "regular", status: "closed" })) {
  console.log(job.jobId, job.data.status);
}

for await (const run of client.iterRuns("01J...", 50)) {
  console.log(run.runId, run.data.status);
}

for await (const row of client.iterResults("01J...", { status: "failed" })) {
  console.log(row.task_id, row.error?.code);
}

// Option 1: re-run every task.
const full = await client.job(jobId).rerun({ waitForIngest: true });
await full.wait({ timeout: 1800 });

// Option 2: re-run only the failures (pass includePending: true to also pick up
// tasks that never started). Successful results carry over, so you don't pay to
// re-scrape them.
const retry = await client.job(jobId).retryFailed({ includePending: true, waitForIngest: true });
await retry.wait({ timeout: 1800 });

import { At, Rate } from "zenrows";

const job = await client.submitScheduled(
  new Rate(6, "hour"),
  ["https://www.scrapingcourse.com/ecommerce/"],
);

// One-shot: a tz-naive wall-clock time plus an IANA zone.
const once = await client.submitScheduled(
  new At("2027-01-15T09:00:00", "Europe/Berlin"),
  ["https://www.scrapingcourse.com/ecommerce/"],
);

import { Calendar, Weekly } from "zenrows";

await job.schedule.pause();  // stop firing new runs
await job.schedule.resume();
await job.schedule.update(new Calendar(["09:00"], new Weekly(["mon", "fri"]), "Europe/Berlin"));

await job.run.pause();       // reversibly suspend the current run (a different endpoint)
await job.run.resume();
await job.run.stop();        // end the current run

const job = await client.submitRegular(
  ["https://www.scrapingcourse.com/ecommerce/"],
  undefined,
  { webhook: { url: "https://your-app.com/webhooks/zenrows", signature: true } },
);

await client.job(jobId).run.downloadAllResults("results.zip");

const est = client.estimateCost(
  ["https://www.scrapingcourse.com/ecommerce/", "https://www.scrapingcourse.com/ecommerce/page/2"],
  { js_render: "true" },
);
console.log(`${est.min} credits (${est.taskCount} tasks)`); // "10 credits (2 tasks)"
console.log(est.breakdown); // per-tier lines: { tier, count, unitMin, unitMax }

const run = await client.job(jobId).run.wait({ timeout: 1800 });
const spend = run.data.stats.spend;
if (spend) console.log(`this run used ${spend.credits} credits (cost ${spend.cost})`);

const created = await client.rotateHmacKey(); // the first call creates the active key
console.log(created.kid, created.secret);     // the secret is returned ONCE, so store it now

// Phased rotation:
await client.rotateHmacKey();       // stage a candidate (start accepting both)
await client.finalizeHmacKey();     // promote the candidate to active, retire the old one
// await client.cancelHmacRotation(); // or discard the candidate
await client.listHmacKeys();        // metadata only; never returns secrets

import { createServer } from "node:http";
import {
  WEBHOOK_EVENT_ID_HEADER,
  WEBHOOK_SIGNATURE_HEADER,
  type WebhookEvent,
  verifyWebhookSignature,
} from "zenrows";

// The kid and base64 secret that rotateHmacKey() returned, from your secret store.
const secrets = { "YOUR_KEY_ID": "YOUR_BASE64_SECRET" };

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk: Buffer) => chunks.push(chunk));
  req.on("end", () => {
    const body = Buffer.concat(chunks);
    const signature = req.headers[WEBHOOK_SIGNATURE_HEADER.toLowerCase()];
    if (typeof signature !== "string" || !verifyWebhookSignature(body, signature, secrets)) {
      res.writeHead(401).end();
      return;
    }
    const event = JSON.parse(body.toString("utf8")) as WebhookEvent;
    console.log(req.headers[WEBHOOK_EVENT_ID_HEADER.toLowerCase()], event.event_type, event.stats);
    res.writeHead(204).end(); // answer fast, then process the event
  });
}).listen(3000);

import { BatchErrorCode, ZenRowsBatchError } from "zenrows";

try {
  await client.submitRegular(["https://www.scrapingcourse.com/ecommerce/"]);
} catch (err) {
  if (!(err instanceof ZenRowsBatchError)) throw err;
  switch (err.code) {
    case BatchErrorCode.PaymentRequired: // 402: the account is out of credits
    case BatchErrorCode.SubscriptionInactive: // 401: the subscription isn't active
      console.log("Check Billing in your dashboard:", err.detail);
      break;
    case BatchErrorCode.ApiKeyCapReached: // 402: detail names the cap and when it resets
      console.log(err.detail);
      break;
    case BatchErrorCode.QuotaExceeded: // 429: an account limit, read detail
      console.log("Wait for a run to end, or delete a job:", err.detail);
      break;
    default:
      throw err;
  }
}

import { ZenRowsBatchClient } from "zenrows";

const client = new ZenRowsBatchClient("YOUR_ZENROWS_API_KEY", {
  retries: 3, // 0 disables
  timeout: 30, // seconds per API request
});

const job = await client.submitRegular(
  ["https://www.scrapingcourse.com/ecommerce/"],
  undefined,
  { idempotencyKey: "nightly-2027-01-15" },
);

// A rerun needs the previous run to be finished first. This one re-runs every task.
await client.job(job.jobId).run.wait({ timeout: 1800 });
await client.job(job.jobId).rerun({ idempotencyKey: "nightly-2027-01-15-rerun" });