@zenrows/cli 1.2.2 → 1.3.0

package/README.md

@@ -139,9 +139,22 @@ zenrows batch cancel <job-id>                        # stop an in-flight run
 ```
 
 `jobs.jsonl` is one JSON object per line, each with a `url` (plus optional
-per-line overrides like `js_render`, `premium_proxy`, `proxy_country`). Request
-beta access from Zenrows to run in the cloud; until then, validate/estimate
-locally or fan out with `zenrows fetch` per URL.
+per-line overrides like `js_render`, `premium_proxy`, `proxy_country`,
+`extract`). Request beta access from Zenrows to run in the cloud; until then,
+validate/estimate locally or fan out with `zenrows fetch` per URL.
+
+**Extract in Batch.** Set `"extract": "auto"` on a line to run that URL through
+Extract — structured data instead of raw HTML:
+
+```jsonl
+{"url": "https://example.com/products", "extract": "auto", "external_id": "p1"}
+{"url": "https://example.com/reviews", "extract": "auto", "external_id": "r1"}
+```
+
+An Extract task costs the same as a regular one (1 credit at base tier), so
+`batch estimate` prices it correctly. Results for an Extract task carry two
+keys: `html` (the raw page) and `parsed` (the structured data) — validate a
+sample with `zenrows extract <url>` before running the full batch.
 
 ## 10. Browser Sessions
 

package/agent-plugin/skills/batch-jobs/SKILL.md

@@ -30,7 +30,9 @@ Optional if exposed by the server: `batch_wait` to block until terminal status.
 1. Validate the workflow on **one** URL with `scrape` or `extract`.
 2. `batch_create` with the full task list (each task: `url` + optional
    overrides like `js_render`, `premium_proxy`, `proxy_country`, `mode`,
-   `autoparse`, `external_id`, `metadata`).
+   `autoparse`, `extract`, `external_id`, `metadata`). `extract: "auto"`
+   returns structured data instead of raw HTML, at the same credit cost as a
+   regular task; the result carries `html` and `parsed` keys.
 3. Poll `batch_status` until terminal (`completed` / `stopped` / …).
 4. Collect with `batch_results`.
 5. `batch_cancel` if the user aborts or the run should stop early.

package/dist/src/adapters/protected-fetch.js

@@ -98,6 +98,6 @@ export async function runFetch(opts, config, policy, apiKey) {
     validateAutoManual(opts, config);
     const params = buildParams(opts, config);
     const mode = params.mode === "auto" ? "auto" : "manual";
-    const result = await scrape(config.apiBase, apiKey, params);
+    const result = await scrape(config.apiBase, apiKey, params, { timeoutMs: opts.timeoutMs });
     return { result, params, mode };
 }

package/dist/src/cli/commands/batch.js

@@ -17,7 +17,7 @@ import { assertDomainAllowed, assertWithinLimits, loadPolicy } from "../../core/
 import { newRunId, writeRun } from "../../core/artifacts.js";
 import { createJob, downloadResults, getJob, listResults, rerunJob, stopJob, waitForJob } from "../../core/batch-api.js";
 import { asNumber, asString, parse } from "../command.js";
-import { ToolkitError } from "../../core/errors.js";
+import { ToolkitError, isKeyCapReached, keyCapReached } from "../../core/errors.js";
 import { printError, writeOut } from "../output.js";
 export const batch = {
     name: "batch",
@@ -166,20 +166,22 @@ async function createCmd(rest, ctx) {
     try {
         const job = await createJob(body, { apiKey });
         const finished = follow ? await waitForJob(job.job_id, { apiKey }) : job;
+        const runError = runFailure(finished);
         const runDir = writeRun({
             runId,
             command: "zenrows batch create",
             capability: "batch",
             startedAt,
             finishedAt: new Date().toISOString(),
-            status: "ok",
+            status: runError ? "error" : "ok",
             request: { file, tasks: body.tasks.length, estimatedCredits: est.credits, jobParams },
-            result: { jobId: job.job_id, status: finished.latest_run?.status ?? "unknown" },
+            result: { jobId: job.job_id, status: finished.latest_run?.status ?? "unknown", ...failureFields(finished) },
+            ...(runError ? { error: runError.toJSON() } : {}),
         });
-        printJob(finished, json, `Submitted job ${job.job_id}`);
+        const code = printJob(finished, json, `Submitted job ${job.job_id}`);
         if (runDir && !json)
             log.dim(`  artifact: ${runDir}`);
-        return 0;
+        return code;
     }
     catch (err) {
         writeRun({
@@ -201,8 +203,7 @@ async function statusCmd(rest, ctx) {
     assertUsable("batch");
     const apiKey = requireApiKey();
     const job = await getJob(id, { apiKey });
-    printJob(job, ctx.json, `Job ${id}`);
-    return 0;
+    return printJob(job, ctx.json, `Job ${id}`);
 }
 async function resultsCmd(rest, ctx) {
     const { values, positionals } = parse(rest, {
@@ -273,8 +274,7 @@ async function cancelCmd(rest, ctx) {
     assertUsable("batch");
     const apiKey = requireApiKey();
     const job = await stopJob(id, { apiKey });
-    printJob(job, ctx.json, `Stopped job ${id}`);
-    return 0;
+    return printJob(job, ctx.json, `Stopped job ${id}`);
 }
 async function waitCmd(rest, ctx) {
     const { values, positionals } = parse(rest, { timeout: { type: "string" }, json: { type: "boolean" } });
@@ -283,8 +283,7 @@ async function waitCmd(rest, ctx) {
     assertUsable("batch");
     const apiKey = requireApiKey();
     const job = await waitForJob(id, { apiKey, timeoutMs: asNumber(values.timeout) });
-    printJob(job, json, `Job ${id} finished`);
-    return 0;
+    return printJob(job, json, `Job ${id} finished`);
 }
 async function retryCmd(rest, ctx) {
     const { positionals } = parse(rest, {});
@@ -294,21 +293,72 @@ async function retryCmd(rest, ctx) {
     // "Reruns and retrying failures": POST /jobs/{id}/rerun?status=failed replays
     // only the failures; already-successful tasks carry over.
     const job = await rerunJob(id, { apiKey, status: "failed" });
-    printJob(job, ctx.json, `Reran failed tasks for job ${id}`);
-    return 0;
+    return printJob(job, ctx.json, `Reran failed tasks for job ${id}`);
+}
+/** The run's failure_reason / failure_detail, when the API reports them. */
+function failureFields(job) {
+    const run = job.latest_run ?? {};
+    const out = {};
+    if (typeof run.failure_reason === "string" && run.failure_reason)
+        out.failure_reason = run.failure_reason;
+    if (typeof run.failure_detail === "string" && run.failure_detail)
+        out.failure_detail = run.failure_detail;
+    return out;
+}
+/**
+ * The error for a run that ended `failed`, or null for any other state. A run the
+ * key's credit cap stopped (`api_key_cap_reached`) gets the cap guidance: the
+ * account still has credits and its other keys keep working.
+ */
+export function runFailure(job) {
+    if (job.latest_run?.status !== "failed")
+        return null;
+    const { failure_reason, failure_detail } = failureFields(job);
+    const where = `batch job ${job.job_id}`;
+    if (isKeyCapReached(failure_reason)) {
+        return keyCapReached(where, { status: null, detail: failure_detail });
+    }
+    const why = [failure_reason, failure_detail].filter(Boolean).join(": ");
+    return new ToolkitError({
+        code: "BATCH_FAILED",
+        message: `Batch job ${job.job_id} failed.`,
+        likely_cause: why || "The run ended in status failed without a reason.",
+        next_action: "Inspect the per-task results, fix the cause, then rerun the failed tasks.",
+        suggested_commands: [`zenrows batch results ${job.job_id} --status failed`, `zenrows batch retry-failed ${job.job_id}`],
+    });
 }
-/** Print a job's status + stats, structured under --json. */
+/**
+ * Print a job's status + stats, structured under --json, and return the exit
+ * code: 1 when the run ended `failed`, else 0. `stopped` and `deleted` are
+ * deliberate outcomes (someone cancelled or removed the run), so they exit 0
+ * but print as a warning, not a success.
+ */
 function printJob(job, json, headline) {
     const run = job.latest_run ?? {};
     const stats = run.stats;
+    const failure = failureFields(job);
+    const err = runFailure(job);
     if (json) {
-        log.out(JSON.stringify({ ok: true, jobId: job.job_id, status: run.status, stats }, null, 2));
-        return;
+        log.out(JSON.stringify({ ok: !err, jobId: job.job_id, status: run.status, stats, ...failure, ...(err ? { error: err.toJSON() } : {}) }, null, 2));
+        return err ? 1 : 0;
     }
-    log.success(`${headline} · status: ${run.status ?? "unknown"}`);
+    const line = `${headline} · status: ${run.status ?? "unknown"}`;
+    if (err)
+        log.error(line);
+    else if (run.status === "stopped" || run.status === "deleted")
+        log.warn(line);
+    else
+        log.success(line);
     if (stats) {
         log.info(`  ${stats.completed}/${stats.total} completed · ${stats.successful} successful · ${stats.failed} failed`);
     }
+    if (failure.failure_reason)
+        log.info(`  failure_reason: ${failure.failure_reason}`);
+    if (failure.failure_detail)
+        log.info(`  failure_detail: ${failure.failure_detail}`);
+    if (err)
+        printError(err, false);
+    return err ? 1 : 0;
 }
 function normalizeResultStatus(v) {
     if (!v)

package/dist/src/cli/commands/fetch.js

@@ -34,6 +34,7 @@ export const fetch_ = {
         "  --output <fmt>         html (default) | markdown | text | pdf",
         "  --screenshot           capture an above-the-fold screenshot",
         "  --out <file>           write the response body to a file",
+        "  --timeout <ms>         client-side timeout (default 120000; above the API's own 90s budget)",
         "  --no-signup            do not auto-create a Free plan account if no key exists",
         "  --json                 print a structured result",
         "",
@@ -55,6 +56,7 @@ export const fetch_ = {
             output: { type: "string" },
             screenshot: { type: "boolean" },
             out: { type: "string" },
+            timeout: { type: "string" },
             "no-signup": { type: "boolean" },
             json: { type: "boolean" },
         });
@@ -90,6 +92,7 @@ export const fetch_ = {
             originalStatus: values["original-status"] === true,
             output: normalizeOutput(asString(values.output)),
             screenshot: values.screenshot === true,
+            timeoutMs: normalizeTimeout(values.timeout),
         };
         const runId = newRunId();
         const startedAt = new Date().toISOString();
@@ -166,6 +169,28 @@ export const fetch_ = {
         }
     },
 };
+/**
+ * `--timeout <ms>`, in milliseconds, matching `batch wait --timeout`.
+ *
+ * Rejects a non-numeric or non-positive value rather than silently falling back
+ * to the default: an agent that passes `--timeout fast` must not get a green
+ * result on a timeout the CLI never honored.
+ */
+export function normalizeTimeout(v) {
+    if (v === undefined)
+        return undefined;
+    const ms = asNumber(v);
+    if (ms === undefined || ms <= 0) {
+        throw new ToolkitError({
+            code: "INVALID_USAGE",
+            message: `Invalid --timeout value '${String(v)}'.`,
+            likely_cause: "--timeout takes a positive number of milliseconds.",
+            next_action: "Pass milliseconds, e.g. --timeout 180000 for three minutes.",
+            suggested_commands: ["zenrows fetch <url> --timeout 180000"],
+        });
+    }
+    return ms;
+}
 export function normalizeOutput(v) {
     if (!v)
         return undefined;

package/dist/src/cli/commands/usage.js

@@ -7,6 +7,10 @@ import { loadConfig } from "../../core/config.js";
 import { log } from "../../core/logger.js";
 import { fetchUsage } from "../../core/usage.js";
 import { parse } from "../command.js";
+/** Thousands separators, so a seven-digit credit limit stays readable. */
+export function fmt(n) {
+    return n.toLocaleString("en-US");
+}
 /** Free plan still ships as plan_code=trial in R1; display the product name. */
 export function formatPlanName(name) {
     if (!name)
@@ -23,6 +27,22 @@ export function formatPlanStatus(status) {
         return "active";
     return status;
 }
+const CAP_WINDOW_LABEL = {
+    day: "daily",
+    week: "weekly",
+    month: "monthly",
+    billing_period: "billing-period",
+};
+/** One line per credit cap on the calling key; none when the key is uncapped. */
+export function formatKeyCaps(caps) {
+    return (caps ?? []).map((c) => {
+        const label = `This key: ${CAP_WINDOW_LABEL[c.window] ?? c.window} cap ${fmt(c.credits)}`;
+        const reset = c.resets_at ? `, resets ${c.resets_at}` : "";
+        if (c.unavailable || c.used_credits === undefined)
+            return `${label}, usage unavailable right now${reset}`;
+        return `${label}, ${fmt(c.used_credits)} used, ${fmt(c.remaining_credits ?? Math.max(0, c.credits - c.used_credits))} left${reset}`;
+    });
+}
 export const usage = {
     name: "usage",
     summary: "Show plan usage, credits, and concurrency for the current API key.",
@@ -40,6 +60,17 @@ export const usage = {
         const api = u.plan?.products?.api;
         log.info(`Plan:    ${formatPlanName(u.plan?.name)}${u.plan?.recurrence ? ` (${u.plan.recurrence})` : ""}`);
         log.info(`Status:  ${formatPlanStatus(u.status)}`);
+        // Credits are the unit the docs, the dashboard and the error messages all speak in,
+        // and the endpoint has been returning them all along. Showing only the dollar figure
+        // left the reader to convert — and the rate is per plan, so they could not.
+        if (u.usage_credits !== undefined && u.credit_limit !== undefined) {
+            const remaining = Math.max(0, u.credit_limit - u.usage_credits);
+            log.info(`Credits: ${fmt(u.usage_credits)} of ${fmt(u.credit_limit)} used` +
+                `${u.usage_percent !== undefined ? ` (${u.usage_percent}%)` : ""} — ${fmt(remaining)} left`);
+        }
+        else if (u.usage_credits !== undefined) {
+            log.info(`Credits: ${fmt(u.usage_credits)} used`);
+        }
         if (u.usage !== undefined) {
             log.info(`Usage:   ${u.usage}${u.usage_percent !== undefined ? ` (${u.usage_percent}% of plan)` : ""}`);
         }
@@ -48,6 +79,8 @@ export const usage = {
         }
         if (u.period_ends_at)
             log.info(`Billing period ends: ${u.period_ends_at}`);
+        for (const line of formatKeyCaps(u.api_key?.caps))
+            log.info(line);
         if (Array.isArray(u.top_ups) && u.top_ups.length)
             log.info(`Top-ups: ${u.top_ups.length}`);
         return 0;

package/dist/src/core/batch-api.js

@@ -16,7 +16,7 @@
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { ToolkitError, quotaExhausted } from "./errors.js";
+import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
 /** Confirmed Batch API base (no trailing slash). */
@@ -139,6 +139,9 @@ function problemToError(status, body, method, path) {
             suggested_commands: ["zenrows batch status <id>"],
         });
     }
+    if (status === 402 && isKeyCapReached(serverCode)) {
+        return keyCapReached(`${method} ${path}`, { status: 402, detail: problem.detail || problem.title || undefined });
+    }
     if (status === 402) {
         // Out of credits ("Subscription has no credit available") — the same
         // exhausted state as the scraper/usage 402. Surface the credits error with

package/dist/src/core/browser-api.js

@@ -3,7 +3,7 @@
  *
  * A managed REST session API (used in production by the official `@zenrows/mcp`
  * server) hosted at `https://mcp.zenrows.com/browser/sessions/*`. Auth is the
- * `Authorization: Bearer <key>` header (same key as the scraper API). Bodies are
+ * `Authorization: Bearer <key>` header (same key as the Fetch API). Bodies are
  * JSON; the CLI drives it directly — no CDP/WebSocket, no browser dependency.
  * Structurally the same shape as `batch-api.ts` (separate host, header auth,
  * injectable `fetchImpl` for tests).
@@ -11,7 +11,7 @@
  * Sessions are billed by bandwidth + session time, so callers must always close
  * them (`closeSession`) — the `browser run` command does so in a `finally`.
  */
-import { ToolkitError, quotaExhausted } from "./errors.js";
+import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
 import { CLI_VERSION } from "./config.js";
@@ -105,6 +105,12 @@ export function browserProblemToError(status, body, method, path) {
             suggested_commands: ["zenrows login --api-key <your-key>"],
         });
     }
+    if (status === 402 && isKeyCapReached(serverCode, body)) {
+        return keyCapReached(`${method} ${path}`, {
+            status: 402,
+            detail: parsed.error || parsed.detail || parsed.title || undefined,
+        });
+    }
     if (status === 402) {
         // Out of credits — same exhausted state as the scraper/batch 402.
         const acct = readAccount();

package/dist/src/core/config.js

@@ -11,7 +11,7 @@ export const CONFIG_VERSION = "0.1.0";
  * entrypoint) so core modules — telemetry, signup provenance — can read it
  * without an import cycle. `VERSION` in `cli/index.ts` re-exports this.
  */
-export const CLI_VERSION = "1.2.2";
+export const CLI_VERSION = "1.3.0";
 /** Env var to override the Fetch and Extract API base (local/staging testing). */
 export const API_BASE_ENV = "ZENROWS_API_BASE";
 /**

package/dist/src/core/errors.js

@@ -5,7 +5,7 @@
  * a `next_action`, and optional `suggested_commands`. Agents (and humans) can
  * react to the code and follow the suggested command without guessing.
  */
-import { DASHBOARD_URL } from "./open-url.js";
+import { BILLING_TOPUP_URL, PLANS_URL } from "./open-url.js";
 export class ToolkitError extends Error {
     code;
     likely_cause;
@@ -39,15 +39,49 @@ export class ToolkitError extends Error {
  * quota, …) instead of a hardcoded status.
  */
 export function quotaExhausted(url, claimUrl, opts = {}) {
+    // Say that the allowance comes back. Without it this reads as a permanent paywall,
+    // which is how the API's own AUTH004 text reads ("Purchase a new subscription to
+    // continue") and why exhausted clients retry-loop instead of waiting or upgrading —
+    // one account spent seven days at ~3 req/s against this wall. `zenrows usage` prints
+    // the exact `period_ends_at`, so the date is one command away rather than guessed here.
+    const renewLine = "Credits renew at the end of the billing period — run `zenrows usage` for the date.";
     const claimLine = claimUrl
-        ? `You are on the Zenrows Free plan. Claim your account to keep your usage and add credits: ${claimUrl}`
-        : `You are out of Zenrows credits. Add credits or upgrade your plan: ${DASHBOARD_URL}`;
+        ? `You are on the Zenrows Free plan. Claim your account to keep your usage and add credits: ${claimUrl}. ${renewLine}`
+        : `You are out of Zenrows credits. ${renewLine} To carry on now, add a credit pack (${BILLING_TOPUP_URL} opens the purchase directly) or upgrade your plan: ${PLANS_URL}`;
     const detail = opts.detail ? `${opts.detail.replace(/\.\s*$/, "")}. ` : "";
     return new ToolkitError({
         code: "POLICY_MAX_CREDITS_EXCEEDED",
         message: "Zenrows request quota exhausted.",
         likely_cause: `${detail}HTTP ${opts.status ?? 429} for ${url}`,
         next_action: claimLine,
-        suggested_commands: claimUrl ? [] : ["zenrows usage"],
+        suggested_commands: ["zenrows usage"],
+    });
+}
+/** Where an account manages its API keys and their credit caps. */
+export const API_KEYS_SETTINGS_URL = "https://app.zenrows.com/settings/api-keys";
+/**
+ * True when a 402 is a per-key credit cap (gateway AUTH014, Batch
+ * `api_key_cap_reached`), not an account out of credits. The account still has
+ * credits, so the out-of-credits advice (top up, upgrade, claim) is wrong here.
+ */
+export function isKeyCapReached(code, body) {
+    if (code === "AUTH014" || code === "api_key_cap_reached")
+        return true;
+    return !!body && /\b(AUTH014|api_key_cap_reached)\b/.test(body);
+}
+/**
+ * The error for a request refused because this API key reached one of its credit
+ * caps. `opts.status: null` is for a Batch run the cap stopped: the run's status
+ * call succeeded, so there is no HTTP 402 to cite, only `url` (the job).
+ */
+export function keyCapReached(url, opts = {}) {
+    const detail = opts.detail ? `${opts.detail.replace(/\.\s*$/, "")}. ` : "";
+    const where = opts.status === null ? `Stopped ${url}` : `HTTP ${opts.status ?? 402} for ${url}`;
+    return new ToolkitError({
+        code: "KEY_CREDIT_CAP_REACHED",
+        message: "This API key reached one of its credit caps.",
+        likely_cause: `${detail}${where}`,
+        next_action: `The account still has credits and its other API keys keep working. Wait for the cap to reset (\`zenrows usage\` shows when), or raise or remove this key's cap at ${API_KEYS_SETTINGS_URL}.`,
+        suggested_commands: ["zenrows usage"],
     });
 }

package/dist/src/core/http.js

@@ -5,11 +5,25 @@
  * query parameter (per docs) and is registered as a secret so it is redacted
  * from any logged URL.
  */
-import { ToolkitError, quotaExhausted } from "./errors.js";
+import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
 import { readAccount } from "./agent-account.js";
 import { ENV_KEY, resolveApiKey } from "./auth.js";
 import { registerSecret } from "./logger.js";
 import { CLI_VERSION } from "./config.js";
+/**
+ * Client-side timeout for a Fetch and Extract request, deliberately ABOVE the
+ * gateway's own 90s request budget.
+ *
+ * The two must not be equal. When they were both 90s, any request that used
+ * the full server budget became a race between our own abort and the API's
+ * real error envelope — and the abort usually won, so a specific, actionable
+ * server error (a 422, a 499) was reported as "could not reach the API". The
+ * client must outlive the server budget so the API always gets the chance to
+ * answer for itself.
+ */
+export const DEFAULT_TIMEOUT_MS = 120_000;
+/** The gateway's own request budget. Kept here only to justify the default above. */
+export const SERVER_BUDGET_MS = 90_000;
 function buildUrl(apiBase, apiKey, params) {
     const u = new URL(apiBase);
     u.searchParams.set("apikey", apiKey);
@@ -27,8 +41,17 @@ function buildUrl(apiBase, apiKey, params) {
 export async function scrape(apiBase, apiKey, params, opts = {}) {
     registerSecret(apiKey);
     const { full, redacted } = buildUrl(apiBase, apiKey, params);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs ?? 90_000);
+    // Our own timer is the only thing that aborts this controller, so this flag —
+    // not `err.name === "AbortError"` — is what tells a client-side give-up apart
+    // from a genuine transport failure. The two must never share an error code.
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    const startedAt = Date.now();
     let res;
     try {
         res = await fetch(full, {
@@ -39,11 +62,14 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
     }
     catch (err) {
         clearTimeout(timeout);
+        const elapsedMs = Date.now() - startedAt;
+        if (timedOut)
+            throw requestTimeout(params.url, timeoutMs, elapsedMs);
         const cause = err instanceof Error ? err.message : String(err);
         throw new ToolkitError({
             code: "BACKEND_UNAVAILABLE",
             message: `Could not reach the Zenrows API.`,
-            likely_cause: `Network error or timeout: ${cause}`,
+            likely_cause: `Network error after ${formatMs(elapsedMs)}: ${cause}`,
             next_action: "Check connectivity and retry. Verify api base in `zenrows config show`.",
             suggested_commands: ["zenrows status", "zenrows config show"],
         });
@@ -116,6 +142,11 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
                 suggested_commands: [`zenrows extract ${params.url} --autoparse`],
             });
         }
+        // AUTH014: this key hit one of its credit caps; the account still has credits.
+        if (isKeyCapReached(zrErrorCode(body) ?? undefined)) {
+            // `detail` names the cap and its reset date; the title alone says neither.
+            throw keyCapReached(redacted, { status: 402, detail: zrErrorProblemDetail(body) ?? zrErrorDetail(body) ?? undefined });
+        }
         // Zenrows returns 402 with a JSON error envelope (e.g. AUTH004 "reached its
         // usage limit" / "Subscription has no credit available") when the account is
         // out of credits. This is NOT scraped content — surface it as a credits
@@ -197,6 +228,31 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
     }
     return result;
 }
+/**
+ * The CLI gave up waiting before the API answered. This is NOT unreachability:
+ * the connection was established and the gateway was still working, so telling
+ * the operator to check connectivity would send them at the wrong problem. The
+ * elapsed time is included so the 90s server budget is visible in the output.
+ */
+export function requestTimeout(url, timeoutMs, elapsedMs) {
+    const suggestedMs = Math.max(timeoutMs + 60_000, SERVER_BUDGET_MS + 60_000);
+    const atBudget = elapsedMs >= SERVER_BUDGET_MS;
+    return new ToolkitError({
+        code: "REQUEST_TIMEOUT",
+        message: `The CLI stopped waiting after ${formatMs(timeoutMs)}. The Zenrows API did not respond in time.`,
+        likely_cause: `The request was aborted client-side after ${formatMs(elapsedMs)}. The API was reached — this is not a ` +
+            (atBudget
+                ? `connectivity problem. The request also passed the API's own ${formatMs(SERVER_BUDGET_MS)} budget, so the target is very likely rendering slowly or a wait condition never matched.`
+                : `connectivity problem, and the API's own ${formatMs(SERVER_BUDGET_MS)} budget had not run out yet.`),
+        next_action: `Retry with a longer client timeout (\`--timeout ${suggestedMs}\`). If the target needs a long render, drop ` +
+            "`--wait-for` so the request finishes inside the API's budget and the API can return its own error instead.",
+        suggested_commands: [`zenrows fetch ${url} --timeout ${suggestedMs}`],
+    });
+}
+/** `89677` → `89.7s`; `120004` → `120s`. One decimal, and never a bare `.0`. */
+function formatMs(ms) {
+    return `${(ms / 1000).toFixed(1).replace(/\.0$/, "")}s`;
+}
 function looksLikeContent(r) {
     // allowed_status_codes / original_status can legitimately return 4xx bodies
     // (the target's real page content). But Zenrows' OWN error responses also
@@ -307,6 +363,18 @@ export function zrErrorCode(body) {
         return null;
     }
 }
+/** The problem body's `detail` field alone, prefixed with its code. */
+function zrErrorProblemDetail(body) {
+    try {
+        const j = JSON.parse(body);
+        if (!j.detail)
+            return null;
+        return j.code ? `(${j.code}) ${j.detail}` : j.detail;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Clean one-line detail from a Zenrows JSON error body
  * (e.g. `(AUTH003) Invalid apikey provided`).

package/dist/src/core/open-url.js

@@ -9,6 +9,9 @@ export const AGENT_SIGNUP_API_URL = "https://app.zenrows.com/api/agent/signup";
 /** Well-known path advertising the agent-auth endpoints (signup discovery). */
 export const WELL_KNOWN_PROTECTED_RESOURCE = "/.well-known/oauth-protected-resource";
 export const DASHBOARD_URL = "https://app.zenrows.com/dashboard";
+/** Lands on Billing with the credit-pack purchase modal already open (app PR #1972). */
+export const BILLING_TOPUP_URL = "https://app.zenrows.com/billing?topup=open";
+export const PLANS_URL = "https://app.zenrows.com/plans";
 export const DOCS_URL = "https://docs.zenrows.com";
 /** Append query params to a URL (used to attach anonymous `utm_*` attribution). */
 export function withParams(url, params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenrows/cli",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Open-source CLI, MCP, skills, templates, workflows, recipes, and evals layer for giving AI agents reliable access to protected web data through Zenrows cloud infrastructure.",
   "type": "module",
   "license": "MIT",

package/skills/batch-jobs/SKILL.md

@@ -24,7 +24,21 @@ zenrows batch estimate jobs.jsonl     # validate the spec + estimate credits
 
 `jobs.jsonl` is one JSON object per line, each with a `url` (plus optional
 per-task keys: `external_id`, `metadata`, and scrape params like `js_render`,
-`premium_proxy`, `proxy_country`, `mode`, `autoparse`).
+`premium_proxy`, `proxy_country`, `mode`, `autoparse`, `extract`).
+
+## Extract in Batch
+
+`"extract": "auto"` on a line runs that URL through Extract, returning
+structured data instead of raw HTML.
+
+```
+{"url": "https://example.com/products", "extract": "auto", "external_id": "p1"}
+```
+
+An Extract task costs the same as a regular one (1 credit at base tier), so
+`batch estimate` prices it correctly. The result carries two keys: `html` (the
+raw page) and `parsed` (the structured data). Validate on a single URL with
+`zenrows extract <url>` before running the full batch.
 
 ## Cloud (needs a key + beta access)
 ```
@@ -40,6 +54,14 @@ zenrows batch retry-failed <id>       # rerun only the failed tasks (new run)
 `--premium-proxy` (or `mode=auto`) and is rejected before any request. Job-level
 flags apply to every task; per-task keys in the JSONL override them.
 
+A run ends in one of `completed`, `failed`, `stopped`, or `deleted`. `status`,
+`wait`, and `create --wait` exit non-zero (`ok: false` under `--json`) only for
+`failed`, and print the run's `failure_reason` and `failure_detail`. When
+`failure_reason` is `api_key_cap_reached`, the key hit its own credit cap
+(`KEY_CREDIT_CAP_REACHED`): the account still has credits, other keys keep
+working, and the tasks not yet run stay pending. Wait for the cap to reset
+(`zenrows usage`) or raise the cap; do not resubmit the job with the same key.
+
 Deferred (documented, not yet in the CLI): CSV upload, open/queue jobs,
 scheduled jobs, webhooks/HMAC, and ZIP export.
 

package/skills/extract/SKILL.md

@@ -28,7 +28,10 @@ zenrows extract <url> --validate                   # fail if not valid JSON
 
 ## Rules
 - Validate on a single page before scaling across many URLs.
-- If Autoparse misses fields, switch to `--css` with explicit selectors, or add
-  `--manual --js-render` for JS-heavy pages.
+- If Autoparse misses fields, switch to `--css` with explicit selectors. Auto
+  mode already renders JS when the target needs it, so reach for
+  `--manual --js-render` only after auto mode has returned an incomplete page:
+  it costs several times a basic call ([[cost-control]]) and it makes the
+  escalation yours.
 
 See [[protected-fetch]] for retrieval semantics.

package/skills/protected-fetch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: protected-fetch
-description: Use Zenrows Protected Fetch for anti-bot-protected page retrieval.
+description: Use Zenrows Protected Fetch in auto mode for anti-bot-protected page retrieval. Auto mode handles the anti-bot escalation, so never enable JS rendering or premium proxies yourself on a first attempt.
 version: 0.1.0
 requires_backend_capabilities: [protected_fetch]
 ---
@@ -16,18 +16,33 @@ cannot. This is the **core primitive** — backed by Zenrows **Fetch**
 - The target has anti-bot protection, needs JS rendering, or geo-specific access.
 
 ## How to call
+
+Auto mode is the answer for anti-bot targets, Cloudflare included. It escalates
+for you and bills only for the configuration that succeeds.
+
 ```
-zenrows fetch <url>                       # Adaptive Stealth Mode (recommended)
+zenrows fetch <url>                       # Adaptive Stealth Mode. Start here, always
 zenrows fetch <url> --output markdown     # convert to Markdown
-zenrows fetch <url> --manual --js-render --premium-proxy   # full manual control
-zenrows fetch <url> --proxy-country us    # geo-target (auto mode; in manual mode needs --premium-proxy)
+zenrows fetch <url> --proxy-country us    # geo-target, works in auto mode
 zenrows fetch <url> --wait-for ".price"   # wait for a selector
 ```
 
+Manual mode exists for the rare case where auto mode has already failed and a
+trace shows why. It costs more and it makes the escalation your problem:
+
+```
+zenrows fetch <url> --manual --js-render --premium-proxy   # the most expensive path, see [[cost-control]]
+```
+
 ## Rules
-- Start with **auto mode**. In auto mode, `js_render` and `premium_proxy` are
-  managed for you — passing them manually requires `--manual`
-  (otherwise you get `PARAM_CONFLICT_AUTO_MANUAL`).
+- Start with **auto mode**. Enabling `--js-render` and `--premium-proxy` yourself
+  is the most expensive configuration this API offers, by a wide margin, and auto
+  mode reaches the same place only when the target actually needs it. The
+  multipliers are in [[cost-control]].
+- A hard target is not a reason to skip auto mode. It is the reason auto mode
+  exists.
+- In auto mode `js_render` and `premium_proxy` are managed for you. Passing them
+  manually requires `--manual`, otherwise you get `PARAM_CONFLICT_AUTO_MANUAL`.
 - `--proxy-country` works in auto mode on its own; in `--manual` mode it also
   needs `--premium-proxy` (else `PARAM_PROXY_COUNTRY_REQUIRES_PREMIUM`).
 - You are billed only for the configuration that succeeds.

package/skills/trace-debug/SKILL.md

@@ -19,9 +19,31 @@ zenrows trace export <run-id>     # JSON for sharing
 ```
 
 ## Failure → action map
-- `FETCH_FAILED` / empty content → retry `--manual --js-render`, then add
-  `--premium-proxy`; for slow pages add `--wait-for <selector>`.
+- `FETCH_FAILED` / empty content → first retry in auto mode (`mode=auto`), which
+  escalates for you and bills only for what succeeds. For slow pages add
+  `--wait-for <selector>`. Only when auto mode has failed on its own, take
+  manual control with `--manual --js-render`, then `--premium-proxy`. Each step
+  multiplies the cost of the request, and both together are the most expensive
+  configuration available ([[cost-control]]).
+- `REQUEST_TIMEOUT` → the CLI stopped waiting; the API was reached. Raise
+  `--timeout` (default 120000ms, above the API's own 90s budget), or drop
+  `--wait-for` so the request finishes inside that budget and the API returns
+  its own error. Not a connectivity problem — do not chase the network.
+- `BACKEND_UNAVAILABLE` → a genuine transport failure (DNS/TCP/TLS). Check
+  connectivity and `zenrows config show`.
 - `AUTH_INVALID` → re-check the key, `zenrows login --api-key …`.
+- `KEY_CREDIT_CAP_REACHED` → this API key hit one of its own credit caps (HTTP
+  402, gateway code `AUTH014`, Batch `api_key_cap_reached`). The account still
+  has credits and its other keys keep working. Do not retry and do not escalate:
+  `zenrows usage` shows the cap and when it resets. Wait for the reset, or have
+  the account owner raise or remove the cap at
+  https://app.zenrows.com/settings/api-keys.
+- `POLICY_MAX_CREDITS_EXCEEDED` → the account itself is out of credits (or a
+  local policy credit limit was hit). Do not retry-loop; `zenrows usage` shows
+  when credits renew. Top up or upgrade, or claim the account if it is an
+  auto-created Free plan.
+- `BATCH_FAILED` → the batch run ended `failed`; `failure_reason` and
+  `failure_detail` in `zenrows batch status <id> --json` say why.
 - `PARAM_CONFLICT_AUTO_MANUAL` → drop the managed flags or add `--manual`.
 - `CAPABILITY_UNAVAILABLE` → the primitive is not available on this account (e.g. beta/invite-only); use the local-spec path where offered.
 

package/templates/batch-jsonl-pipeline/README.md

@@ -3,7 +3,12 @@
 Scaffold for a high-scale workload expressed as a JSONL job spec, run on the
 Zenrows **Batch**. One JSON object per line, each with a `url` (plus
 optional per-line overrides like `js_render`, `premium_proxy`, `proxy_country`,
-`mode`, `autoparse`, and an `external_id` echoed back on each result).
+`mode`, `autoparse`, `extract`, and an `external_id` echoed back on each
+result).
+
+Set `"extract": "auto"` on a line to run that URL through Extract — structured
+data instead of raw HTML, at the same credit cost as a regular task. Extract
+results carry `html` and `parsed` keys.
 
 ## Local (no key)
 

package/templates/batch-jsonl-pipeline/jobs.example.jsonl

@@ -1,3 +1,4 @@
 {"url": "https://www.scrapingcourse.com/ecommerce/", "mode": "auto", "autoparse": true}
 {"url": "https://httpbin.io/html"}
 {"url": "https://example.com", "js_render": true, "premium_proxy": true}
+{"url": "https://www.scrapingcourse.com/ecommerce/", "extract": "auto", "external_id": "extract-demo"}