> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Zenrows HTTP API serves Fetch and Extract (extract=auto) at https://api.zenrows.com/v1/, Crawl at https://api.zenrows.com/v1/crawls, and Batch at https://async.api.zenrows.com/v1. Fetch, Extract, Crawl and Batch are described in OpenAPI 3.1 at https://www.zenrows.com/openapi.json and listed in the RFC 9727 API catalog at https://www.zenrows.com/.well-known/api-catalog. Every endpoint also has its own page under /api-reference with its schema. Use the spec for exact parameter names and types. Crawl's endpoints, parameters and errors are also at https://docs.zenrows.com/crawl/endpoints.md. To call Zenrows from an agent, connect the MCP server at https://mcp.zenrows.com/mcp. To search these docs from an agent, connect the docs MCP server at https://docs.zenrows.com/mcp. Agent skills for Zenrows are published at https://github.com/ZenRows/cli and install with `npx skills add ZenRows/cli`.

# FAQ (Frequently Asked Questions)

> Frequently asked questions about Zenrows Batch: access, pricing, limits, scraping options, results, scheduling, and how it relates to Fetch.

Quick answers to the questions teams ask most when they start with Batch. For step-by-step code, see the [API reference](https://docs.zenrows.com/batch/developer-guide-restapi.md). For error-specific help, see [Troubleshooting](https://docs.zenrows.com/batch/troubleshooting.md).

## Getting Started

> [accordion] Is Batch available to everyone?
>
> Yes. Batch is available to every Zenrows account. You can start submitting jobs right away with your existing API key, with no extra setup.

> [accordion] Do I need a separate API key?
>
> No. Batch uses the **same API key as your Fetch**. There's nothing extra to generate.

> [accordion] What's the base URL?
>
> All REST requests go to `https://async.api.zenrows.com/v1`. Send your key in the `X-API-Key` header on every request.

> [accordion] How do I integrate?
>
> Batch is a REST API, so you can call it from any language with an HTTP client. The [API reference](https://docs.zenrows.com/batch/developer-guide-restapi.md) shows every request in Python, Node.js, Java, PHP, Go, Ruby and cURL, and the same calls work from any HTTP client. Official SDKs exist for [Python](https://docs.zenrows.com/batch/sdk/python.md), [Node.js](https://docs.zenrows.com/batch/sdk/nodejs.md) and [Go](https://docs.zenrows.com/batch/sdk/go.md).

## How It Works

> [accordion] What's the difference between a job, a run, and a task?
>
> A **job** is the template: your URLs and configuration. A **run** is one execution of that job, where each rerun or scheduled fire creates a new run. A **task** is a single URL within a run, with its own status and result.

> [accordion] What's the difference between a rerun and retrying failures?
>
> A **rerun** replays every task in the job as a fresh run. **Retry failed** re-executes only the tasks that failed (and optionally those that never started), carrying over the successful results so you only pay to re-scrape what failed. Both create a new run on the same job.

> [accordion] How do I know when a job is done?
>
> Two ways: attach a **webhook** and the API sends a `run.completed` event when the run completes (or `run.failed` if it fails on its own; stopping a run sends no event), delivered best effort with retries for up to 3 days, or **poll** the job until `latest_run.status` is terminal (`completed`, `failed`, or `stopped`) and read the `stats` counters (`completed === successful + failed`). Webhooks are a convenience; the run state remains the source of truth.

> [accordion] Can I pause or stop a running job?
>
> Yes. `POST /jobs/{id}/pause` reversibly suspends the current run and `POST /jobs/{id}/resume` continues it, while `POST /jobs/{id}/stop` (alias `POST /jobs/{id}/cancel`) ends it for good. These act on the job's current run, which is different from pausing a scheduled job's recurring schedule. See [Control the current run](https://docs.zenrows.com/batch/developer-guide-restapi.md#control-the-current-run).

> [accordion] My submit returned 202 instead of 201. Is that an error?
>
> No. `POST /jobs` returns `201 Created` for fewer than 10,000 tasks and `202 Accepted` for 10,000 or more, inline or from a CSV upload. Every rerun returns `202` too. The response body is identical and you track completion the same way, so treat both the same. For a large `202`, `GET /jobs/{id}/results` may return partial pages for a few seconds while the task list finishes writing, but `stats.total` is correct from the start.

> [accordion] Can I submit URLs as I go, instead of all at once?
>
> Yes. Open a job, add tasks in batches over time (up to 10,000 per add-tasks call and 100,000 per job), then close it with `last_batch: true`. See [open jobs](https://docs.zenrows.com/batch/developer-guide-restapi.md#open-jobs-adding-tasks-in-batches).

> [accordion] How many jobs can I run at the same time?
>
> An account runs **3 active jobs by default**, shared with [Crawl](https://docs.zenrows.com/crawl/introduction.md), and keeps up to **5 scheduled jobs**. One more of either returns `429 quota_exceeded`. A job counts as active until you delete it, or until it's closed and its latest run has ended, so an open job always counts. An open job that receives no tasks for 48 hours closes automatically. To run more than 3 at once, use the chat in your [dashboard](https://app.zenrows.com). Email [success@zenrows.com](mailto:success@zenrows.com) if you can't use the chat.
>
> [Open the dashboard](https://app.zenrows.com)

## Scraping Options

> [accordion] What scraping options can I use?
>
> The same `zenrows_params` as Fetch, including `js_render`, `premium_proxy`, `proxy_country`, `mode` (`auto`), `wait_for`, `wait`, `css_extractor`, `extract`, `extract_fields`, `json_response`, `custom_headers`, and more. Set them once on the job, and override any of them per URL. Screenshot parameters aren't supported, and an unknown key rejects the submit with `400`. A task can also fetch its target with `POST` and a body of up to 16 KiB; see [POST target fetches](https://docs.zenrows.com/batch/developer-guide-restapi.md#post-target-fetches).

> [accordion] Can I use different options for different URLs in the same job?
>
> Yes. Options set on the job apply to every URL; options set on an individual URL override the job-level ones for that URL. This lets you configure the common case once and tune the exceptions (for example, a different `proxy_country` for a handful of URLs).

> [accordion] Can one job include URLs from different websites?
>
> Yes. A job is just a list of URLs plus the options to apply to them, so you can mix targets in a single job and use per-URL overrides where a specific site needs different handling.

> [accordion] What output formats are available?
>
> Raw HTML, parsed **JSON**, **Markdown**, **plain text**, and **PDF**. The API derives the output format from your options (for example `response_type: markdown`) and records it on each result.

## Results and Limits

> [accordion] How long are result download links valid?
>
> Each result's `result_url` is a presigned link valid for **2 hours**. If it expires, re-list the results to get a fresh one rather than storing it. You can also stream a task's content directly, or export an entire run as a ZIP.

> [accordion] How long are results stored, and do I need to manage storage?
>
> Each `result_url` lasts 2 hours; re-list the results to get a fresh one. The result itself stays available for **14 days** by default, counted from the task's `updated_at`: when it finished, or when a partial rerun carried it over. After that, the task's result row reads `status: "expired"` with no `result_url`, and its content endpoint returns `410 result_expired`. The stored body is deleted automatically within 30 days of being scraped. You don't need to delete anything to stay within storage limits. If you want to remove results sooner, you can delete a single run's results or an entire job yourself. See [Delete a job or a run](https://docs.zenrows.com/batch/developer-guide-restapi.md#delete-a-job-or-a-run).

> [accordion] Can I delete a job or its results?
>
> Yes. Use `DELETE /jobs/{id}/runs/{run_id}` to delete one run's stored results while keeping the job, or `DELETE /jobs/{id}` to delete the whole job (all runs and results). Stopping a run only ends it and keeps the results, so use delete when you want the data removed. See [Delete a job or a run](https://docs.zenrows.com/batch/developer-guide-restapi.md#delete-a-job-or-a-run).

> [accordion] How many URLs can a job handle?
>
> Up to **100,000 URLs per job submit**. On an open job, each add-tasks call accepts up to **10,000 URLs**, up to 100,000 in total, and CSV uploads support up to **50 MB / 100,000 rows**. Results page at \~1,000 per page. Every limit is in the [Limits](https://docs.zenrows.com/batch/introduction.md#limits) table.

> [accordion] How do I match results back to my own records?
>
> Attach an `external_id` to each URL. The API returns it unchanged on every result, so you can correlate results to your records without tracking the API's task IDs. It doesn't need to be unique, but it must use only letters, digits, `.`, `_` and `-`, up to 128 characters; put free text in `metadata`.

> [accordion] Can I download all results at once?
>
> Yes. Start a bulk export to bundle a run's result bodies into a single ZIP. The download link is valid for 2 hours, the export for 12 hours, and a run whose combined results exceed 100 GiB can't be exported as one archive. Page through the results instead.

## Scheduling

> [accordion] Can I run a job on a recurring schedule?
>
> Yes. An account keeps up to 5 scheduled jobs. Schedule a job as **one-shot** (a single future time), **interval** (every N minutes, hours, or days, minimum 60 minutes between runs), or **calendar** (specific times on specific days). Schedules are timezone-aware using IANA names. You can pause and resume any time without losing the schedule.

> [accordion] Why was my scheduled time rejected?
>
> Times of day must be **full hours**: use `"09:00"`, not `"09:30"`. Also provide exactly one schedule type (`at`, `rate`, or `calendar`) and a valid IANA timezone for `at` and `calendar`.

## Pricing

> [accordion] How is Batch priced?
>
> Pricing is **identical to Fetch**, in credits. Successful tasks are billed, and so are tasks whose target answered `404` or `410`. The credit cost depends on the scraping tier each URL uses.
>
> | Configuration | Credits per billed request |
> | - | - |
> | Base (no special options) | 1 |
> | JavaScript rendering | 5 |
> | Premium proxy | 10 |
> | JavaScript rendering + premium proxy | 25 |
> | Adaptive Stealth Mode (`mode=auto`) | Dynamic, 1–25 |

> [accordion] Am I charged for failed requests?
>
> Mostly no. A task that fails because the target answered `404 Not Found` or `410 Gone` is billed, as on Fetch, even though Batch records it as `failed` because it has no usable content. Other failed tasks aren't billed. A task's attempt history shows what each attempt was charged, and `stats.spend` on the run shows the total.

> [accordion] Can I estimate the cost before running a job?
>
> Yes. Because the rate card is small and stable, you can estimate credits client-side with no API call, then show your users an accurate range up front. After a run finishes, you can also read the actual credits it consumed. See [Estimate cost](https://docs.zenrows.com/batch/developer-guide-restapi.md#estimate-cost) and [Check actual cost](https://docs.zenrows.com/batch/developer-guide-restapi.md#check-actual-cost).

> [accordion] How can I keep costs as low as possible?
>
> Use **Adaptive Stealth Mode** (`mode=auto`). It starts each request with the cheapest viable setup and escalates to JavaScript rendering or premium proxies only when a site actually needs them, so you pay for the lightest configuration that succeeds.

## Reliability and Security

> [accordion] What happens if a page is temporarily unavailable?
>
> The API retries transient failures automatically, so a page that's briefly unavailable still has a strong chance of being fetched. Requests are also paced to stay polite to the sites you scrape.

> [accordion] What does the idempotency key do, and is it safe to retry a submit?
>
> An **idempotency key** (the `Idempotency-Key` header) makes a retry safe. It works on submits, reruns, and add-tasks calls, and lasts 24 hours. If you never saw the answer, such as after a timeout, resend the same request with the same key: the API replays the original response if the request went through, so you never get a second job, run or set of tasks. A submit or rerun the API refused, for example with `429 quota_exceeded`, doesn't use up its key, so you can fix the cause and retry with it. An add-tasks call keeps its key, so send a corrected body with a new key. The same key with a different request, or while the first attempt is still running, returns `409 idempotency_key_conflict`. See [Idempotency](https://docs.zenrows.com/batch/developer-guide-restapi.md#idempotency).

> [accordion] How do I verify that a webhook really came from Zenrows?
>
> Set `signature: true` when you attach the webhook. The API then HMAC-signs each delivery, and your receiver verifies the `X-Signature` header against the raw request body with your organization's key, base64-decoded. The SDKs include a helper for it. See [Verify signed webhooks](https://docs.zenrows.com/batch/developer-guide-restapi.md#verify-signed-webhooks).

## Didn't Find Your Answer?

Check the [Troubleshooting](https://docs.zenrows.com/batch/troubleshooting.md) page for error-specific guidance, or reach out to support with your `job_id`, the request body (API key redacted), and the exact error `code` and `detail`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.