Submit a Batch job: many URLs scraped asynchronously in the cloud (Zenrows Batch API). Suited to large URL lists; scrape and extract handle single pages. Not the same as browser_batch.
Tasks use automatic mode (mode=auto) by default: Zenrows enables JS rendering and premium proxies only on the pages that need them. Pass just the URLs. Set js_render or premium_proxy (job-level, or per task) only to force a fixed configuration; that turns automatic mode off for those tasks.
Cost: the same credits as the regular API, per successful task: 1 for a basic request, 5 with js_render, 10 with premium_proxy, 25 with both; mode=auto bills each task at the configuration that worked. Failed tasks are not billed, except target 404 and 410 answers, billed as on the regular API.
Limits: up to 100,000 tasks per call; 3 active jobs per account by default, shared with Crawl (BATCH_QUOTA_EXCEEDED past that); a job frees its slot when its run ends.
Creates a closed job with every task in this one call. Each task takes a url plus optional external_id, metadata, method/body (POST tasks) and scrape params. Every call sends an Idempotency-Key, so the bounded retries on network errors and 5xx never create a second job; an error reply carries the key to retry with.
Returns job_id, status and stats at once; the job runs asynchronously. Then: batch_wait until it ends, batch_results to list rows (paged), batch_content to read one task's page. A run that ends failed (out of credits, inactive subscription, key cap) answers ok:false with error.code and server_code; batch_rerun recovers it. Submits of 10,000+ tasks keep writing tasks for a while (ingesting:true).
Errors: BATCH_INVALID_REQUEST (400, server_code and invalid_tasks say what), BATCH_INSUFFICIENT_CREDITS (402), BATCH_KEY_CAP_REACHED (402, this key's cap), BATCH_QUOTA_EXCEEDED (429, job limit), AUTH_INVALID (401; server_code subscription_inactive means fix Billing), BATCH_ACCESS_DENIED (403, do not retry), BACKEND_UNAVAILABLE.
Schedules, webhooks, exports, CSV inputs and open jobs are available through the Batch API and SDKs only.
View input schema
{
"type": "object",
"properties": {
"tasks": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Target URL for this task: http or https, up to 2,048 characters"
},
"external_id": {
"anyOf": [
{
"type": "string",
"maxLength": 128,
"pattern": "^[A-Za-z0-9._-]+$"
},
{
"type": "null"
}
],
"description": "Optional id of your own, echoed back on results: up to 128 characters, letters, digits, '.', '_' and '-' only (no spaces). Need not be unique. Put free text in metadata instead."
},
"metadata": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 1024
},
"propertyNames": {
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9._-]+$"
}
},
{
"type": "null"
}
],
"description": "Optional string-to-string map echoed back on results: up to 20 entries; keys 1 to 64 characters of letters, digits, '.', '_' and '-'; values up to 1,024 characters; 4 KiB in all. Values must be strings: convert numbers and booleans first."
},
"method": {
"anyOf": [
{
"type": "string",
"enum": [
"GET",
"POST"
]
},
{
"type": "null"
}
],
"description": "HTTP method for this task (default GET). POST is for read-only queries such as search or GraphQL endpoints: the target can receive the same POST more than once. POST cannot be combined with js_render, js_instructions or json_response."
},
"body": {
"description": "Request body, only with method POST, up to 16 KiB. An object or array is sent as JSON; a string is sent as is, form encoded."
},
"zenrows_params": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
}
},
{
"type": "null"
}
],
"description": "Per-task scrape params, over the job's. Accepted: allowed_status_codes, autoparse, block_resources, css_extractor, custom_headers, extract, extract_fields, js_instructions, js_render, json_response, mode, original_status, outputs, premium_proxy, proxy_country, response_type, session_id, wait, wait_for. Booleans as true/false. Screenshot params are not supported in Batch."
}
},
"required": [
"url"
],
"additionalProperties": true,
"description": "A task. Scrape params may go in zenrows_params or flat on the task (e.g. extract, js_render); a flat key wins over the same key in zenrows_params."
},
"maxItems": 100000
},
{
"type": "null"
}
],
"description": "Tasks (each needs a url), up to 100,000. Prefer this over urls when you need per-task params."
},
"urls": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uri",
"maxLength": 2048
},
"maxItems": 100000
},
{
"type": "null"
}
],
"description": "Shorthand: list of URLs (converted to tasks), up to 100,000. Ignored when tasks is provided."
},
"js_render": {
"type": [
"boolean",
"null"
],
"description": "Force js_render on all tasks (5 credits each). Overrides automatic mode (mode=auto), which already renders when needed."
},
"premium_proxy": {
"type": [
"boolean",
"null"
],
"description": "Force premium_proxy on all tasks (10 credits each, 25 with js_render). Overrides automatic mode (mode=auto), which already uses premium proxies when a page needs them."
},
"mode_auto": {
"type": [
"boolean",
"null"
],
"description": "Automatic mode (mode=auto) is on by default; leave unset. False sends plain requests without it."
},
"proxy_country": {
"type": [
"string",
"null"
],
"description": "Job-level ISO country code. Works in automatic mode (mode=auto); with js_render alone it requires premium_proxy."
},
"response_type": {
"anyOf": [
{
"type": "string",
"enum": [
"markdown",
"plaintext",
"pdf"
]
},
{
"type": "null"
}
],
"description": "Job-level output format. Leave unset for the raw HTML, the default."
},
"zenrows_params": {
"anyOf": [
{
"$ref": "#/properties/tasks/anyOf/0/items/properties/zenrows_params/anyOf/0"
},
{
"type": "null"
}
],
"description": "Additional job-level scrape params merged with the flags above. Accepted: allowed_status_codes, autoparse, block_resources, css_extractor, custom_headers, extract, extract_fields, js_instructions, js_render, json_response, mode, original_status, outputs, premium_proxy, proxy_country, response_type, session_id, wait, wait_for."
},
"idempotency_key": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 128
},
{
"type": "null"
}
],
"description": "Sent as the Idempotency-Key header, up to 128 characters; generated per call when unset. Reusing a key with the identical request within 24 hours returns the original response instead of doing it again; with a different request it is BATCH_IDEMPOTENCY_CONFLICT."
},
"wait": {
"type": [
"boolean",
"null"
],
"description": "If true, poll before returning until the run ends or pauses, or wait_timeout passes; a timeout returns the current state with ok:true"
},
"wait_timeout": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 3600
},
{
"type": "null"
}
],
"description": "Max wait in seconds when wait=true (default 50). Many MCP clients cancel a call after 60 s."
},
"wait_timeout_ms": {
"anyOf": [
{
"type": "integer",
"minimum": 1000,
"maximum": 3600000
},
{
"type": "null"
}
],
"description": "Deprecated: the same wait in milliseconds. Use the seconds parameter instead."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}