Zenrows MCP server: Fetch, Extract, Batch, and Browser Sessions for AI agents
Zenrows MCP Server
The Zenrows MCP (Model Context Protocol) server provides a standard integration for AI systems to access Zenrows web data infrastructure. It enables reliable, real-time access to the live web, including protected web content, via a single connection. The server is intended for AI coding assistants and related agent applications.
🛠️ Key Features
Fetch
Extract
Batch
Browser Sessions
🚀 Use Cases
AI coding assistants needing live web access
Extracting and batching web data for downstream use
Browser-based session access for web content, including protected web
⚡ Developer Benefits
Standard MCP server for using Zenrows infrastructure
Single connection model for accessing live web data reliably and in real time
⚠️ Limitations
No additional limitations are stated in the provided source excerpt.
Topics
data-extractionmcpscraperscraping
Captured live from the server via tools/list.
scrape
Scrape any webpage and return its content using Zenrows (Fetch).
Returns full-page content (markdown/HTML/PDF/screenshot). For structured JSON
fields (products, articles, listings), the extract tool returns parsed fields
instead of a full page body.
By default the request uses automatic mode (mode=auto): Zenrows adds JS rendering
or premium proxies per page only when a plain request does not return the page,
and charges only for the configuration that succeeds. Pass just the URL.
Set js_render or premium_proxy only to force a fixed configuration. Doing so
switches off automatic mode, and every request is billed at that
configuration's cost (premium_proxy with js_render is 25x a basic request).
Examples:
Default: { url: "https://example.com" }
Geo: { url: "https://example.com", proxy_country: "US" }
Forced: { url: "https://spa.com", js_render: true }
Parameters14
url
string
required
The webpage URL to scrape
js_render
boolean | null
optional
Force JavaScript rendering on every request. Overrides automatic mode (mode=auto), which already renders JavaScript when a page needs it. Leave unset unless you need a fixed configuration.
premium_proxy
boolean | null
optional
Force premium residential proxies on every request (10x credit cost). Overrides automatic mode (mode=auto), which already uses premium proxies when a page needs them. Leave unset unless you need a fixed configuration.
proxy_country
string | null
optional
Country for geo-targeted scraping. ISO 3166-1 alpha-2 code (e.g. 'US', 'GB', 'DE'). Works in automatic mode (mode=auto); if you set js_render without premium_proxy, it requires premium_proxy=true.
response_type
any
optional
Output format. 'markdown' (default) preserves structure and is ideal for LLMs. 'plaintext' strips all formatting for pure text extraction. 'pdf' returns a PDF of the page. 'html' returns the raw HTML source (omits the response_type param; Zenrows default). Ignored when autoparse, css_extractor, outputs, or screenshot params are set.
autoparse
boolean | null
optional
Deprecated: general-purpose structured JSON from the page. Prefer the extract tool (extract=auto on a prepared domain, or css_extractor).
css_extractor
string | null
optional
Extract specific elements using CSS selectors. JSON object mapping names to selectors, e.g. '{"title":"h1","price":".price-tag"}'. Returns JSON instead of full page content.
wait_for
string | null
optional
CSS selector to wait for before capturing. Use when key content loads after the initial page render. Requires js_render=true; without it, including in automatic mode, it may be ignored.
wait
any
optional
Milliseconds to wait after page load before capturing content. Max 30000 (30s). Requires js_render=true; without it, including in automatic mode, it may be ignored.
js_instructions
string | null
optional
JSON array of browser interactions to run before scraping. Works in automatic mode (mode=auto), which then renders the page and bills it at the JS rendering rate, or with js_render=true. Example: [{"click":"#load-more"},{"wait":1000},{"wait_for":".results"}]
outputs
string | null
optional
Comma-separated list of data types to extract as structured JSON. Available: emails, headings, links, menus, images, videos, audios. Use '*' for all types. Returns JSON instead of full page content.
screenshot
boolean | null
optional
Capture an above-the-fold screenshot of the page. Returns an image instead of text content. Useful for visual verification or debugging.
screenshot_fullpage
boolean | null
optional
Capture a full-page screenshot including content below the fold. Returns an image instead of text content.
screenshot_selector
string | null
optional
Capture a screenshot of a specific element using a CSS selector. Example: ".product-card". Returns an image instead of text content.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The webpage URL to scrape"
},
"js_render": {
"type": [
"boolean",
"null"
],
"description": "Force JavaScript rendering on every request. Overrides automatic mode (mode=auto), which already renders JavaScript when a page needs it. Leave unset unless you need a fixed configuration."
},
"premium_proxy": {
"type": [
"boolean",
"null"
],
"description": "Force premium residential proxies on every request (10x credit cost). Overrides automatic mode (mode=auto), which already uses premium proxies when a page needs them. Leave unset unless you need a fixed configuration."
},
"proxy_country": {
"type": [
"string",
"null"
],
"description": "Country for geo-targeted scraping. ISO 3166-1 alpha-2 code (e.g. 'US', 'GB', 'DE'). Works in automatic mode (mode=auto); if you set js_render without premium_proxy, it requires premium_proxy=true."
},
"response_type": {
"anyOf": [
{
"type": "string",
"enum": [
"markdown",
"plaintext",
"pdf",
"html"
]
},
{
"type": "null"
}
],
"default": "markdown",
"description": "Output format. 'markdown' (default) preserves structure and is ideal for LLMs. 'plaintext' strips all formatting for pure text extraction. 'pdf' returns a PDF of the page. 'html' returns the raw HTML source (omits the response_type param; Zenrows default). Ignored when autoparse, css_extractor, outputs, or screenshot params are set."
},
"autoparse": {
"type": [
"boolean",
"null"
],
"description": "Deprecated: general-purpose structured JSON from the page. Prefer the extract tool (extract=auto on a prepared domain, or css_extractor)."
},
"css_extractor": {
"type": [
"string",
"null"
],
"description": "Extract specific elements using CSS selectors. JSON object mapping names to selectors, e.g. '{\"title\":\"h1\",\"price\":\".price-tag\"}'. Returns JSON instead of full page content."
},
"wait_for": {
"type": [
"string",
"null"
],
"description": "CSS selector to wait for before capturing. Use when key content loads after the initial page render. Requires js_render=true; without it, including in automatic mode, it may be ignored."
},
"wait": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 30000
},
{
"type": "null"
}
],
"description": "Milliseconds to wait after page load before capturing content. Max 30000 (30s). Requires js_render=true; without it, including in automatic mode, it may be ignored."
},
"js_instructions": {
"type": [
"string",
"null"
],
"description": "JSON array of browser interactions to run before scraping. Works in automatic mode (mode=auto), which then renders the page and bills it at the JS rendering rate, or with js_render=true. Example: [{\"click\":\"#load-more\"},{\"wait\":1000},{\"wait_for\":\".results\"}]"
},
"outputs": {
"type": [
"string",
"null"
],
"description": "Comma-separated list of data types to extract as structured JSON. Available: emails, headings, links, menus, images, videos, audios. Use '*' for all types. Returns JSON instead of full page content."
},
"screenshot": {
"type": [
"boolean",
"null"
],
"description": "Capture an above-the-fold screenshot of the page. Returns an image instead of text content. Useful for visual verification or debugging."
},
"screenshot_fullpage": {
"type": [
"boolean",
"null"
],
"description": "Capture a full-page screenshot including content below the fold. Returns an image instead of text content."
},
"screenshot_selector": {
"type": [
"string",
"null"
],
"description": "Capture a screenshot of a specific element using a CSS selector. Example: \".product-card\". Returns an image instead of text content."
}
},
"required": [
"url"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
extract
Extract structured data from a webpage via Zenrows.
Returns JSON fields (products, articles, listings) in "data" rather than a full
page body. Set include_html to also get the page HTML.
Modes:
- auto (default): extract=auto, site-tailored Extract (currently free,
billing may apply later). Works on any prepared domain, with any API key.
Error REQS007 says why in "reason":
- domain_not_prepared: call prepare_domain with the domain and 1 to 5 example
URLs (one works; we recommend 3 or more of the same page type; a few minutes,
no credits), poll prepared_domain_status about every
30 seconds until it says ready, then call extract again.
- page_not_recognised: the domain is prepared, but this page is not one
Extract extracts (a page with nothing to extract, such as a home page). Try a product,
article or listing page instead; if this page should work, retry it once in
a few minutes; otherwise use mode=css. Do not prepare the domain again.
- domain_not_enabled: preparing does not help; use mode=css.
- autoparse: deprecated general-purpose structured JSON on any domain; use only
when asked for
- css: css_extractor with an explicit selector map
Requests use automatic mode (mode=auto) by default: Zenrows enables JS rendering and
premium proxies only when the site needs them, and charges only for the
configuration that succeeds. Pass just the URL.
Set js_render or premium_proxy only to force a fixed configuration; that turns
automatic mode off and bills every request at that configuration's cost.
Check "empty" in the result: true means no field came back with a value.
"noDataExtracted": true means Extract processed the page and found nothing to
extract (not charged); retrying the same request returns the same answer.
Full-page markdown, HTML and screenshots come from scrape.
Parameters11
url
string
required
The webpage URL to extract from
mode
any
optional
Extraction mode: auto (extract=auto, default), css (requires css_extractor), or the deprecated autoparse
css_extractor
string | null
optional
Required when mode=css. JSON map of field→selector, e.g. '{"title":"h1","price":".price"}'
js_render
boolean | null
optional
Force JS rendering on every request. Overrides automatic mode (mode=auto), which already renders when needed.
premium_proxy
boolean | null
optional
Force premium residential proxies on every request (10x cost). Overrides automatic mode (mode=auto), which already uses premium proxies when a page needs them.
proxy_country
string | null
optional
ISO 3166-1 alpha-2 country code. Works in automatic mode (mode=auto); with js_render or mode_auto=false it requires premium_proxy.
mode_auto
boolean | null
optional
Automatic mode (mode=auto) is on by default; leave unset. False sends a plain request without it.
wait_for
string | null
optional
CSS selector to wait for before extracting. Requires js_render=true; without it, including in automatic mode, it may be ignored.
wait
any
optional
Milliseconds to wait after load. Requires js_render=true; without it, including in automatic mode, it may be ignored.
fallback_autoparse
boolean | null
optional
Deprecated, has no effect: Extract no longer falls back to autoparse. Prepare the domain with prepare_domain instead.
include_html
boolean | null
optional
mode=auto only: also return the full page HTML. Default false; the HTML is most of the response size.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The webpage URL to extract from"
},
"mode": {
"anyOf": [
{
"type": "string",
"enum": [
"auto",
"autoparse",
"css"
]
},
{
"type": "null"
}
],
"default": "auto",
"description": "Extraction mode: auto (extract=auto, default), css (requires css_extractor), or the deprecated autoparse"
},
"css_extractor": {
"type": [
"string",
"null"
],
"description": "Required when mode=css. JSON map of field→selector, e.g. '{\"title\":\"h1\",\"price\":\".price\"}'"
},
"js_render": {
"type": [
"boolean",
"null"
],
"description": "Force JS rendering on every request. Overrides automatic mode (mode=auto), which already renders when needed."
},
"premium_proxy": {
"type": [
"boolean",
"null"
],
"description": "Force premium residential proxies on every request (10x cost). Overrides automatic mode (mode=auto), which already uses premium proxies when a page needs them."
},
"proxy_country": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2 country code. Works in automatic mode (mode=auto); with js_render or mode_auto=false it requires premium_proxy."
},
"mode_auto": {
"type": [
"boolean",
"null"
],
"description": "Automatic mode (mode=auto) is on by default; leave unset. False sends a plain request without it."
},
"wait_for": {
"type": [
"string",
"null"
],
"description": "CSS selector to wait for before extracting. Requires js_render=true; without it, including in automatic mode, it may be ignored."
},
"wait": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 30000
},
{
"type": "null"
}
],
"description": "Milliseconds to wait after load. Requires js_render=true; without it, including in automatic mode, it may be ignored."
},
"fallback_autoparse": {
"type": [
"boolean",
"null"
],
"description": "Deprecated, has no effect: Extract no longer falls back to autoparse. Prepare the domain with prepare_domain instead."
},
"include_html": {
"type": [
"boolean",
"null"
],
"default": false,
"description": "mode=auto only: also return the full page HTML. Default false; the HTML is most of the response size."
}
},
"required": [
"url"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
prepare_domain
Prepare a domain so extract (mode=auto) works on it.
Use this when extract returns error REQS007 with reason domain_not_prepared. Send the
domain (the host, e.g. shop.example.com; a leading www. is dropped, and each host is
prepared separately) and 1 to 5 example URLs of real pages you want extracted. One works;
we recommend 3 or more of the same page type, so pass 3 or more when you can, up to 5 (e.g.
3 product pages: https://www.example.com/products/a, /products/b and /products/c), because
Extract compares pages of one type to check the fields it found and fill in fields one page
is missing. Several page types can share the 5 (e.g. 3 product pages + 2 search-result
pages). It returns at once with status
"preparing" and never waits; preparation takes a few minutes and costs no credits. Then
call prepared_domain_status about every 30 seconds until status is "ready", and call
extract again. Each new domain uses one slot of the account's monthly allowance
(prepared_domain_status shows it). A domain already being prepared returns its current
status; a domain already prepared returns "ready" at once with already_prepared: true and
uses no slot.
Do not call this for REQS007 with reason page_not_recognised: the domain is already
prepared and preparing again does not change that answer.
Parameters3
domain
string
required
The host to prepare, e.g. shop.example.com (a URL is accepted; a leading www. is dropped)
example_urls
array
required
1 to 5 full URLs of real pages on this domain that you want to extract. One works; we recommend 3 or more of the same page type when you can
idempotency_key
string | null
optional
Optional. Resending the same key with the same body returns the original submission
Raw schema
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"minLength": 1,
"description": "The host to prepare, e.g. shop.example.com (a URL is accepted; a leading www. is dropped)"
},
"example_urls": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"minItems": 1,
"maxItems": 5,
"description": "1 to 5 full URLs of real pages on this domain that you want to extract. One works; we recommend 3 or more of the same page type when you can"
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "Optional. Resending the same key with the same body returns the original submission"
}
},
"required": [
"domain",
"example_urls"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
prepared_domain_status
Check a domain submitted with prepare_domain, and the account's monthly allowance.
Returns status (preparing, ready or failed), state (the current step), roles (one per page
kind), a failure code and detail when it failed, the allowance (used, limit, remaining) and
"next": what to do now. Poll about every 30 seconds; preparation takes a few minutes. Call
extract again once status is "ready". Costs no credits.
Parameters1
domain
string
required
The domain passed to prepare_domain, e.g. example.com
Raw schema
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"minLength": 1,
"description": "The domain passed to prepare_domain, e.g. example.com"
}
},
"required": [
"domain"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_create
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.
Parameters12
tasks
any
optional
Tasks (each needs a url), up to 100,000. Prefer this over urls when you need per-task params.
urls
any
optional
Shorthand: list of URLs (converted to tasks), up to 100,000. Ignored when tasks is provided.
js_render
boolean | null
optional
Force js_render on all tasks (5 credits each). Overrides automatic mode (mode=auto), which already renders when needed.
premium_proxy
boolean | null
optional
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
boolean | null
optional
Automatic mode (mode=auto) is on by default; leave unset. False sends plain requests without it.
proxy_country
string | null
optional
Job-level ISO country code. Works in automatic mode (mode=auto); with js_render alone it requires premium_proxy.
response_type
any
optional
Job-level output format. Leave unset for the raw HTML, the default.
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
boolean | null
optional
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
any
optional
Max wait in seconds when wait=true (default 50). Many MCP clients cancel a call after 60 s.
wait_timeout_ms
any
optional
Deprecated: the same wait in milliseconds. Use the seconds parameter instead.
Raw 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#"
}
batch_status
Get a Batch job's latest run: job_id, run_id, status (pending, running, completed, stopped, failed), stats (total, completed, successful, failed) and the job.
A failed run answers ok:false with error.code BATCH_INSUFFICIENT_CREDITS, BATCH_KEY_CAP_REACHED, AUTH_INVALID (subscription_inactive) or BATCH_RUN_FAILED, error.server_code (the failure_reason) and failure_detail; batch_rerun recovers it once fixed. A paused run has paused:true; one still writing its tasks has ingesting:true.
Parameters1
job_id
string
required
Batch job id returned by batch_create or batch_list
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"required": [
"job_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_wait
Poll a Batch job until its run ends (completed, stopped or failed) or pauses, and return its status and stats like batch_status. If the wait runs out first, it returns the current state with ok:true, timed_out:true and a note: call batch_wait again. A paused run returns at once with paused:true (it does not move until batch_resume). A failed run answers ok:false with error.code and server_code (insufficient_credits, subscription_inactive or api_key_cap_reached). Transient poll errors are retried. A call that carries a progressToken gets a progress notification after each poll.
Parameters3
job_id
string
required
Batch job id returned by batch_create or batch_list
timeout
any
optional
Max wait in seconds (default 50). Many MCP clients cancel a call after 60 s.
timeout_ms
any
optional
Deprecated: the same wait in milliseconds. Use the seconds parameter instead.
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
},
"timeout": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 3600
},
{
"type": "null"
}
],
"description": "Max wait in seconds (default 50). Many MCP clients cancel a call after 60 s."
},
"timeout_ms": {
"anyOf": [
{
"type": "integer",
"minimum": 1000,
"maximum": 3600000
},
{
"type": "null"
}
],
"description": "Deprecated: the same wait in milliseconds. Use the seconds parameter instead."
}
},
"required": [
"job_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_results
List a Batch run's result rows, a page at a time: up to limit rows (default 100, max 1000) and next_cursor. Pass next_cursor back as cursor to continue; it is null once every row was read.
Each row has task_id, external_id, url, metadata, status (successful, failed, pending, processing, expired), type, result_url when successful, and error when failed. A result_url is presigned and expires after 2 hours: call batch_results again for a fresh one, or read the body with batch_content. Results are kept 14 days by default; after that a successful row reads as status "expired", with no result_url, and batch_content answers BATCH_RESULT_EXPIRED.
Filter with status: all (default), successful, failed, or processing (not finished yet). A sparse filter can return fewer rows than limit with next_cursor still set: keep paging. While the run is still running or writing its tasks, the list is partial.
Parameters5
job_id
string
required
Batch job id returned by batch_create or batch_list
run_id
any
optional
An earlier run's id (from batch_status or batch_rerun). Default: the job's latest run.
status
any
optional
Filter rows by status (default all). processing = tasks not finished yet. successful also returns expired rows.
cursor
string | null
optional
next_cursor from a previous batch_results call
limit
any
optional
Max rows to return (default 100, max 1000)
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
},
"run_id": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"description": "An earlier run's id (from batch_status or batch_rerun). Default: the job's latest run."
},
"status": {
"anyOf": [
{
"type": "string",
"enum": [
"successful",
"failed",
"processing",
"all"
]
},
{
"type": "null"
}
],
"description": "Filter rows by status (default all). processing = tasks not finished yet. successful also returns expired rows."
},
"cursor": {
"type": [
"string",
"null"
],
"description": "next_cursor from a previous batch_results call"
},
"limit": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 1000
},
{
"type": "null"
}
],
"description": "Max rows to return (default 100, max 1000)"
}
},
"required": [
"job_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_content
Read one Batch task's stored result, by job_id and task_id (from batch_results). A text result (HTML, Markdown, plain text, JSON) comes back inline, cut to max_chars (default 20000); a final note says when it was cut. A binary result (a PDF) is not inlined: the reply gives its result_url, presigned for 2 hours. Finding that URL reads the run's results; on a large run one call may run out of time first and answer with lookup_cursor: call batch_content again with it to go on.
BATCH_TASK_NOT_READY: the task has not finished; BATCH_TASK_FAILED: it failed (task_error holds its error); BATCH_RESULT_EXPIRED: past the job's retention (14 days by default); rerun to scrape it again.
Parameters5
job_id
string
required
Batch job id returned by batch_create or batch_list
task_id
string
required
task_id from a batch_results row
run_id
any
optional
An earlier run's id (from batch_status or batch_rerun). Default: the job's latest run.
max_chars
any
optional
Max characters of a text result to return (default 20000)
lookup_cursor
any
optional
lookup_cursor from a previous batch_content reply on a binary result, to go on looking for its result_url
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
},
"task_id": {
"type": "string",
"minLength": 1,
"description": "task_id from a batch_results row"
},
"run_id": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"description": "An earlier run's id (from batch_status or batch_rerun). Default: the job's latest run."
},
"max_chars": {
"anyOf": [
{
"type": "integer",
"minimum": 1000,
"maximum": 10000000
},
{
"type": "null"
}
],
"description": "Max characters of a text result to return (default 20000)"
},
"lookup_cursor": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"description": "lookup_cursor from a previous batch_content reply on a binary result, to go on looking for its result_url"
}
},
"required": [
"job_id",
"task_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_list
List this account's Batch jobs, newest first, each with its latest run's status and stats. Filter by status (open or closed) and type (regular or scheduled). Pass next_cursor as cursor for the next page; a page can hold fewer than limit jobs while next_cursor is still set, so keep paging until it is null. Deleted jobs are not listed.
Stop a Batch job's current run for good. No task still waiting is started or billed; tasks already in flight finish (and bill). Results so far stay readable with batch_results. Tasks that never started stay pending: batch_rerun (default failed and pending) runs them later. Idempotent: a run that already ended answers with its final status and already_ended:true. To halt without ending the run, use batch_pause.
Parameters1
job_id
string
required
Batch job id returned by batch_create or batch_list
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"required": [
"job_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_pause
Pause a Batch job's current run: it picks up no new tasks until batch_resume. Tasks already in flight still finish and bill; for a hard cost stop use batch_cancel. A paused run still counts as an active job. Idempotent; a run that already ended answers with its final status and already_ended:true.
Parameters1
job_id
string
required
Batch job id returned by batch_create or batch_list
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"required": [
"job_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_resume
Resume a paused Batch run: it picks up its remaining tasks again, billed as they finish. Idempotent on a run that is not paused; a run that already ended answers with its final status and already_ended:true. Needs credits: BATCH_INSUFFICIENT_CREDITS or BATCH_KEY_CAP_REACHED otherwise.
Parameters1
job_id
string
required
Batch job id returned by batch_create or batch_list
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"required": [
"job_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_rerun
Start a new run of a Batch job whose latest run ended (completed, stopped or failed). By default it reruns only the tasks that failed or never started (status ["failed", "pending"]), and carries the others' results over: the recovery after a run that failed on credits or was cancelled. Pass status to pick other task statuses, or full:true to scrape every task again. Rerun tasks are billed like new ones.
A rerun of only some tasks works up to 10 days after the run started (BATCH_RERUN_WINDOW_EXPIRED after that; full:true still works). BATCH_NO_MATCHING_TASKS: no task has those statuses. BATCH_RUN_NOT_FINISHED: the latest run is still in flight. Sends an Idempotency-Key, so a retry never starts two runs. Returns the new run at once (it writes its tasks first, ingesting:true); call batch_wait.
Parameters4
job_id
string
required
Batch job id returned by batch_create or batch_list
status
any
optional
Task statuses to rerun (default ["failed", "pending"]). Ignored with full:true.
full
boolean | null
optional
Rerun every task, not only some (default false)
idempotency_key
any
optional
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.
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
},
"status": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"failed",
"pending",
"processing",
"successful"
]
},
"minItems": 1
},
{
"type": "null"
}
],
"description": "Task statuses to rerun (default [\"failed\", \"pending\"]). Ignored with full:true."
},
"full": {
"type": [
"boolean",
"null"
],
"description": "Rerun every task, not only some (default false)"
},
"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."
}
},
"required": [
"job_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
batch_delete
Delete a Batch job with all its runs and results, for good. A run in flight stops picking up tasks at once, and the job frees its active-job slot. The job reads as not found right away; storage is cleaned up in the background. Idempotent. To keep the results, use batch_cancel instead.
Parameters1
job_id
string
required
Batch job id returned by batch_create or batch_list
Raw schema
{
"type": "object",
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"required": [
"job_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
crawl_create
Start a crawl from one URL (Zenrows Crawl API). Crawl follows the links in each page's HTML up to depth hops (no depth limit when depth is omitted), keeps the URLs that match include_patterns / exclude_patterns, and stays on the start URL's registrable domain (subdomains count).
Use crawl when you have one start page (a listing, category, blog index) and need
the URLs behind it, optionally with each page's HTML. For a single page, use scrape.
Each page fetched is billed as one scrape on this account; max_pages bounds the cost
(default 100), max_items bounds how many URLs are kept (default 100). Without depth, the
crawl keeps following links until max_pages or max_items stops it or nothing is left to
open, so set max_pages to what you are willing to spend. The start page itself is never
a result, but its fetch is billed: a crawl whose include_patterns / exclude_patterns match
nothing still costs that one scrape. A crawl whose pages held nothing new to follow (no link,
only links to other sites, or only links the patterns reject) ends completed with no results
and no error. When patterns are set, check them against the URLs the start page links to.
Set output_format "html" or "markdown" to also store each kept URL's page,
then read it with crawl_content.
Set webhook to have signed events posted to your https URL when the crawl starts and when it
ends; the account needs a webhook signing key, else CRAWL_INVALID_REQUEST (webhook_signing_key_required).
Returns crawl_id, status and the crawl (with coverage) at once; the crawl runs
asynchronously. Call crawl_wait, then crawl_results. Set idempotency_key to make a retry
safe: the same key returns the crawl the first request created instead of starting another.
CRAWL_NOT_ENABLED: Crawl is not enabled for this account; do not retry.
CRAWL_TOO_MANY_CRAWLS: the account has reached its limit of active jobs (3 by default), shared with its Batch jobs; retry after retry_after seconds.
Parameters10
url
string
required
Start URL: a public http(s) page, such as a listing or category page
depth
any
optional
Link hops to follow from the start URL. 1 returns the start page's links; 2 also opens those. Omit for no depth limit: the crawl follows links until max_pages or max_items stops it.
max_items
any
optional
Stop once this many URLs are kept (default 100)
max_pages
any
optional
Stop once this many pages are fetched, each billed as one scrape (default 100). With output_format, every kept URL's page counts too.
include_patterns
any
optional
Keep only URLs containing at least one of these substrings, e.g. ["/product/"]
exclude_patterns
any
optional
Drop URLs containing any of these substrings, even if they match include_patterns
output_format
any
optional
'html' or 'markdown' also stores each kept URL's page for crawl_content, as fetched or converted to Markdown. Omit for URLs only.
discovery
any
optional
How the crawl finds the URLs it follows on each page it walks. ['links'] follows the links in each page's HTML, and is what a crawl runs with when you omit this.
webhook
any
optional
Where to post the crawl's signed events (crawl.started, then one of crawl.completed, crawl.stopped, crawl.failed). Each is signed with the account's webhook signing key, in the X-Signature header.
idempotency_key
any
optional
Sent as the Idempotency-Key header. Reusing a key returns the crawl it created; reusing it with a different body is CRAWL_INVALID_REQUEST.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Start URL: a public http(s) page, such as a listing or category page"
},
"depth": {
"anyOf": [
{
"type": "integer",
"maximum": 100000
},
{
"type": "null"
}
],
"description": "Link hops to follow from the start URL. 1 returns the start page's links; 2 also opens those. Omit for no depth limit: the crawl follows links until max_pages or max_items stops it."
},
"max_items": {
"anyOf": [
{
"type": "integer",
"maximum": 100000
},
{
"type": "null"
}
],
"description": "Stop once this many URLs are kept (default 100)"
},
"max_pages": {
"anyOf": [
{
"type": "integer",
"maximum": 100000
},
{
"type": "null"
}
],
"description": "Stop once this many pages are fetched, each billed as one scrape (default 100). With output_format, every kept URL's page counts too."
},
"include_patterns": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
{
"type": "null"
}
],
"description": "Keep only URLs containing at least one of these substrings, e.g. [\"/product/\"]"
},
"exclude_patterns": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
{
"type": "null"
}
],
"description": "Drop URLs containing any of these substrings, even if they match include_patterns"
},
"output_format": {
"anyOf": [
{
"type": "string",
"enum": [
"html",
"markdown"
]
},
{
"type": "null"
}
],
"description": "'html' or 'markdown' also stores each kept URL's page for crawl_content, as fetched or converted to Markdown. Omit for URLs only."
},
"discovery": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"links"
]
},
"minItems": 1
},
{
"type": "null"
}
],
"description": "How the crawl finds the URLs it follows on each page it walks. ['links'] follows the links in each page's HTML, and is what a crawl runs with when you omit this."
},
"webhook": {
"anyOf": [
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "Absolute https URL each event is posted to"
},
"events": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"crawl.started",
"crawl.completed",
"crawl.stopped",
"crawl.failed"
]
},
"minItems": 1
},
{
"type": "null"
}
],
"description": "Events to send, each once. Omit for all four."
},
"metadata": {
"anyOf": [
{
"type": "object",
"additionalProperties": {},
"propertyNames": {
"minLength": 1,
"maxLength": 64
}
},
{
"type": "null"
}
],
"description": "Sent back with every event, to match it to your records. Up to 20 keys of 1-64 characters, each value at most 1,024 bytes as JSON."
}
},
"required": [
"url"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Where to post the crawl's signed events (crawl.started, then one of crawl.completed, crawl.stopped, crawl.failed). Each is signed with the account's webhook signing key, in the X-Signature header."
},
"idempotency_key": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"description": "Sent as the Idempotency-Key header. Reusing a key returns the crawl it created; reusing it with a different body is CRAWL_INVALID_REQUEST."
}
},
"required": [
"url"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
crawl_get
Get a crawl and one page of the URLs it kept: crawl_id, status (running, completed, stopped, failed), the crawl (with coverage: pages_fetched, pages_failed, items_found; webhook when set), results and next_cursor.
completed with stop_reason max_items / max_pages means a limit ended it; stopped with stop_reason user means crawl_stop ended it; stopped with no stop_reason and error.code insufficient_credits or api_key_cap_reached means the account ran out of credits or the API key hit a credit cap (the URLs kept before that stay readable); completed with no results and no error means the crawl's pages held nothing new to follow; when include_patterns / exclude_patterns are set, check them against the URLs the start page links to. failed carries error.code and error.detail: seed_unreachable means the start URL could not be fetched or returned an empty page; no_items_found means the crawl read the start page but found no data it could use, so it had nothing to follow; start from a listing or product page. A failed crawl, and a stopped one with an error, answer ok: false: error.code is CRAWL_INSUFFICIENT_CREDITS or CRAWL_KEY_CAP_REACHED (the codes crawl_create gets on a 402) when credits ended it, failed or stopped, else CRAWL_FAILED; error.server_code is the crawl's error.code. Pass next_cursor as cursor for the next page; while the crawl runs, next_cursor is never null. To read many pages at once, use crawl_results.
Parameters3
crawl_id
string
required
Crawl id returned by crawl_create (c_…)
cursor
string | null
optional
next_cursor from a previous crawl_get call, to continue from there
limit
any
optional
Results in this page (default 100, max 10000)
Raw schema
{
"type": "object",
"properties": {
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
},
"cursor": {
"type": [
"string",
"null"
],
"description": "next_cursor from a previous crawl_get call, to continue from there"
},
"limit": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10000
},
{
"type": "null"
}
],
"description": "Results in this page (default 100, max 10000)"
}
},
"required": [
"crawl_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
crawl_results
List the URLs a crawl kept, in the order it kept them, following the API's pages up to limit.
Each result has url and, when the crawl has output_format, content_status (pending, fetched, failed) and, once fetched, content_url: pass it to crawl_content as content.
While the crawl runs the list is partial (partial=true): call again later with the returned next_cursor to get only the URLs kept since. A stopped crawl can still add URLs from pages fetched before the stop for up to 10 minutes, so next_cursor stays set during that window: call again later. next_cursor is null once the crawl ended and every URL was read.
Parameters3
crawl_id
string
required
Crawl id returned by crawl_create (c_…)
cursor
string | null
optional
next_cursor from a previous crawl_results call, to continue from there
limit
any
optional
Max results to return in this call (default 100, max 10000)
Raw schema
{
"type": "object",
"properties": {
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
},
"cursor": {
"type": [
"string",
"null"
],
"description": "next_cursor from a previous crawl_results call, to continue from there"
},
"limit": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 10000
},
{
"type": "null"
}
],
"description": "Max results to return in this call (default 100, max 10000)"
}
},
"required": [
"crawl_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
crawl_content
Read the stored page of one URL a crawl kept, in the crawl's output_format. Works only for crawls created with an output_format, and only for results whose content_status is fetched.
Pass crawl_id and content_id: a content id, or content_url from a crawl_results row. Returns the page
as stored — raw HTML for output_format "html", Markdown for "markdown" — cut to max_chars (default
20000); a final note says when it was cut. To read a page the crawl did not
store, use scrape on its URL instead.
Parameters3
crawl_id
string
required
Crawl id returned by crawl_create (c_…)
content_id
string
required
A content id (ct_…), or content_url from a crawl_results row; its last path segment is the id
max_chars
any
optional
Max characters of the page to return (default 20000)
Raw schema
{
"type": "object",
"properties": {
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
},
"content_id": {
"type": "string",
"minLength": 1,
"description": "A content id (ct_…), or content_url from a crawl_results row; its last path segment is the id"
},
"max_chars": {
"anyOf": [
{
"type": "integer",
"minimum": 1000,
"maximum": 10000000
},
{
"type": "null"
}
],
"description": "Max characters of the page to return (default 20000)"
}
},
"required": [
"crawl_id",
"content_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
crawl_list
List this account's crawls, newest first, with status and coverage (no results). Pass next_cursor as cursor for the next page; next_cursor is absent on the last page.
Stop a running crawl. No page still waiting is fetched or billed; pages already in flight finish. The URLs kept so far stay readable with crawl_results. A stopped crawl cannot resume.
Idempotent: a crawl that already ended answers with its final status. A 429, 502, 503 or 504 is retried up to 3 times, waiting at most 50 seconds in all; a 503 crawl_busy means the stop was not saved yet, and if it persists, CRAWL_BUSY says when to call again. Pages in flight still finish, so coverage and results can keep growing for up to 10 minutes after the stop; read them with crawl_get and crawl_results.
Parameters1
crawl_id
string
required
Crawl id returned by crawl_create (c_…)
Raw schema
{
"type": "object",
"properties": {
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
}
},
"required": [
"crawl_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
crawl_wait
Poll a crawl until it ends (completed, stopped, or failed) and return its status, its counts and the first 20 URLs (first_urls). For every result, call crawl_download (one file) or crawl_results (pages). A crawl that ends completed with no results and no error finished; it is not a failure (see crawl_get). If the wait runs out first, it returns the crawl with status running and a note: call crawl_wait again. A call that carries a progressToken gets a progress notification after each poll, with the status and counts.
Parameters2
crawl_id
string
required
Crawl id returned by crawl_create (c_…)
timeout
any
optional
Max wait in seconds (default 50). Many MCP clients cancel a call after 60 s.
Raw schema
{
"type": "object",
"properties": {
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
},
"timeout": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 3600
},
{
"type": "null"
}
],
"description": "Max wait in seconds (default 50). Many MCP clients cancel a call after 60 s."
}
},
"required": [
"crawl_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
crawl_download
Save every result of a crawl to one local file, as JSON lines: url, content_status and, once fetched, content (the page). Returns the file's path and line count, not the results, so a crawl of any size costs one small reply. Read the file with your own tools.
The file goes to path when given (a relative path inside ~/.zenrows/crawls; an absolute path or one that leaves that folder fails with INVALID_PATH), else ~/.zenrows/crawls/<crawl_id>.jsonl. An existing file is kept and the call fails with FILE_EXISTS unless overwrite is true.
On a running crawl the file holds only what was kept so far: download again once crawl_wait says it ended. After crawl_stop, pages in flight can still add lines for up to 10 minutes: the reply says so with partial: true. On the hosted server no file is written: the reply gives the download URL and a command to run where your API key is set.
Parameters3
crawl_id
string
required
Crawl id returned by crawl_create (c_…)
path
any
optional
File to write, relative to ~/.zenrows/crawls (default <crawl_id>.jsonl)
overwrite
boolean | null
optional
Replace the file if it exists (default false)
Raw schema
{
"type": "object",
"properties": {
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
},
"path": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"description": "File to write, relative to ~/.zenrows/crawls (default <crawl_id>.jsonl)"
},
"overwrite": {
"type": [
"boolean",
"null"
],
"description": "Replace the file if it exists (default false)"
}
},
"required": [
"crawl_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
account_usage
Read the current plan's credit allowance and how much of it is spent.
Useful before a large batch, or after a 402 / AUTH004, to see whether the account has
credits left and when the allowance renews. The call is free and does not use a
concurrency slot.
Credit costs per request: 1 basic, 5 js_render, 10 premium_proxy, 25 both.
AUTH004 ("usage exceeded") means this allowance is spent until it renews at the end of
the billing period (period_ends_at in this tool's response). Plans and credit options are
described at https://www.zenrows.com/pricing.
AUTH006 is the concurrency limit, not a credit limit.
AUTH014 (Batch: api_key_cap_reached) means this API key hit one of its own credit caps
while the account still has credits; other keys keep working. The response's
api_key.caps lists the calling key's caps: window, credits, used_credits,
remaining_credits, resets_at, and unavailable (usage could not be read). Caps are
managed at https://app.zenrows.com/settings/api-keys.
Open a Zenrows Browser Sessions session and navigate to a URL.
This is the entry point for all browser automation. It creates a new session backed by
Zenrows' hosted browser infrastructure and navigates to the given URL in one step.
Returns a session_id that every other browser_* tool takes. The session holds one
concurrency slot until browser_close closes it.
When to use options:
- proxy_country: geo-restricted content (ISO 3166-1 alpha-2, e.g. "US", "DE")
- proxy_region: world region for geo-targeted proxy (eu, na, ap, sa, af, me)
Parameters3
url
string
required
The URL to navigate to
proxy_country
string | null
optional
ISO 3166-1 alpha-2 country code for geo-targeted proxy (e.g. 'US', 'GB', 'DE')
proxy_region
string | null
optional
World region code for geo-targeted proxy (eu=Europe, na=North America, ap=Asia Pacific, sa=South America, af=Africa, me=Middle East)
Drag an element from its current position to a target element.
Parameters3
session_id
string
required
Session ID returned by browser_navigate
source_selector
string
required
CSS selector of the element to drag
target_selector
string
required
CSS selector of the drop target
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"source_selector": {
"type": "string",
"description": "CSS selector of the element to drag"
},
"target_selector": {
"type": "string",
"description": "CSS selector of the drop target"
}
},
"required": [
"session_id",
"source_selector",
"target_selector"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_get_accessibility_tree
Get the ARIA accessibility tree of the current page as readable text.
Shows the page structure and the selectors needed to interact with elements, in
fewer tokens than a screenshot.
The tree shows all interactive elements (buttons, inputs, links) with their roles,
labels, and states — everything needed to drive browser interactions.
Parameters1
session_id
string
required
Session ID returned by browser_navigate
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_get_url
Get the current URL of the browser session.
Parameters1
session_id
string
required
Session ID returned by browser_navigate
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_get_title
Get the title of the current page.
Parameters1
session_id
string
required
Session ID returned by browser_navigate
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_get_text
Get the visible text content of an element or the entire page body.
Parameters2
session_id
string
required
Session ID returned by browser_navigate
selector
string | null
optional
CSS selector of the element (omit for full page body text)
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"selector": {
"type": [
"string",
"null"
],
"description": "CSS selector of the element (omit for full page body text)"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_get_attribute
Get the value of a specific attribute on an element.
Parameters3
session_id
string
required
Session ID returned by browser_navigate
selector
string
required
CSS selector of the element
attribute
string
required
Attribute name to retrieve (e.g. 'href', 'src', 'data-id')
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"selector": {
"type": "string",
"description": "CSS selector of the element"
},
"attribute": {
"type": "string",
"description": "Attribute name to retrieve (e.g. 'href', 'src', 'data-id')"
}
},
"required": [
"session_id",
"selector",
"attribute"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_get_html
Get the HTML source of an element or the full page.
Parameters2
session_id
string
required
Session ID returned by browser_navigate
selector
string | null
optional
CSS selector of the element (omit for full page HTML)
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"selector": {
"type": [
"string",
"null"
],
"description": "CSS selector of the element (omit for full page HTML)"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_query_selector_all
Find all elements matching a CSS selector and return their text, HTML, and attributes.
Parameters2
session_id
string
required
Session ID returned by browser_navigate
selector
string
required
CSS selector to query
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"selector": {
"type": "string",
"description": "CSS selector to query"
}
},
"required": [
"session_id",
"selector"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_screenshot
Take a screenshot of the current page or a specific element. Use for visual verification or when the accessibility tree is not sufficient.
Parameters3
session_id
string
required
Session ID returned by browser_navigate
full_page
boolean | null
optional
Capture full page including content below the fold (default false)
selector
string | null
optional
CSS selector to capture only a specific element (overrides full_page)
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"full_page": {
"type": [
"boolean",
"null"
],
"description": "Capture full page including content below the fold (default false)"
},
"selector": {
"type": [
"string",
"null"
],
"description": "CSS selector to capture only a specific element (overrides full_page)"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
Wait until an element matching the CSS selector is stable in the DOM. Set visible=true to also require the element to be visible (not hidden).
Parameters3
session_id
string
required
Session ID returned by browser_navigate
selector
string
required
CSS selector to wait for
visible
boolean | null
optional
Also require the element to be visible, not just present in the DOM (default false)
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"selector": {
"type": "string",
"description": "CSS selector to wait for"
},
"visible": {
"type": [
"boolean",
"null"
],
"description": "Also require the element to be visible, not just present in the DOM (default false)"
}
},
"required": [
"session_id",
"selector"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_wait_for_navigation
Wait for the page to navigate to a new URL. It waits for the next navigation event, so a navigation that already finished is not seen and the call waits until timeout_ms. Pages that update without changing URL (AJAX/SPA) fire no navigation event. Optional timeout_ms (default 30000ms).
Parameters2
session_id
string
required
Session ID returned by browser_navigate
timeout_ms
any
optional
How long to wait in milliseconds (default 30000, max 60000)
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"timeout_ms": {
"anyOf": [
{
"type": "integer",
"minimum": 1000,
"maximum": 60000
},
{
"type": "null"
}
],
"description": "How long to wait in milliseconds (default 30000, max 60000)"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_wait
Wait for a fixed duration. browser_wait_for_selector waits only until an element appears.
Execute JavaScript in the browser context and return the result. The script can change or delete the session's page state, such as cookies, storage and form data.
Parameters2
session_id
string
required
Session ID returned by browser_navigate
script
string
required
JavaScript expression or function body to evaluate in the page context
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"script": {
"type": "string",
"description": "JavaScript expression or function body to evaluate in the page context"
}
},
"required": [
"session_id",
"script"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_get_cookies
Get all cookies for the current page.
Parameters1
session_id
string
required
Session ID returned by browser_navigate
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_set_cookies
Set one or more cookies in the browser session. A cookie with the same name, domain and path replaces the existing one.
Clear all cookies for the current browser session.
Parameters1
session_id
string
required
Session ID returned by browser_navigate
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_get_local_storage
Read one localStorage value in the current page context.
Parameters2
session_id
string
required
Session ID returned by browser_navigate
key
string
required
Storage key to read
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"key": {
"type": "string",
"description": "Storage key to read"
}
},
"required": [
"session_id",
"key"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_set_local_storage
Write one localStorage value in the current page context. An existing value under the same key is replaced.
Parameters3
session_id
string
required
Session ID returned by browser_navigate
key
string
required
Storage key to write
value
string
required
Value to store
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"key": {
"type": "string",
"description": "Storage key to write"
},
"value": {
"type": "string",
"description": "Value to store"
}
},
"required": [
"session_id",
"key",
"value"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_clear_local_storage
Delete every localStorage entry in the current page context.
Parameters1
session_id
string
required
Session ID returned by browser_navigate
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_new_tab
Open a new browser tab. Returns a tab_id to use with browser_switch_tab.
Parameters2
session_id
string
required
Session ID returned by browser_navigate
url
any
optional
URL to open in the new tab (opens blank tab if omitted)
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "URL to open in the new tab (opens blank tab if omitted)"
}
},
"required": [
"session_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_switch_tab
Switch focus to a different browser tab.
Parameters2
session_id
string
required
Session ID returned by browser_navigate
tab_id
string
required
Tab ID returned by browser_new_tab
Raw schema
{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"tab_id": {
"type": "string",
"description": "Tab ID returned by browser_new_tab"
}
},
"required": [
"session_id",
"tab_id"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}
browser_batch
Execute a sequence of browser actions in a single call against an existing session.
Use this when you already know the full sequence of steps — it reduces round trips and
is faster than calling each tool individually.
Actions run sequentially and stop at the first failure unless stop_on_error is false.
Each step result is returned in the results array at the same index.
Note: screenshots in batch results are returned as base64 strings inside the JSON;
browser_screenshot returns them as images.
A batch can include evaluate, so it can change or delete page state the same way
browser_evaluate can.
Parameters3
session_id
string
required
Session ID returned by browser_navigate
actions
array
required
Ordered list of actions to perform. Each action has a 'type' field plus type-specific parameters.
stop_on_error
boolean | null
optional
Stop executing on the first failed action (default true)
The Zenrows MCP (Model Context Protocol) server is the standard way AI systems use Zenrows' web data infrastructure. A single connection gives your AI assistant, agent, or application reliable, real-time access to the live web, including the protected web.
Reach sites that normally block bots. Get reliable access to protected sites at scale, without building anti-bot handling yourself.
Managed web data infrastructure. Proxy rotation, headless browser orchestration, anti-bot handling, and session management run on Zenrows' infrastructure.
Plug into any AI you already use. Works with any MCP client, including AI assistants, agent frameworks, AI SDKs, IDE plugins, and custom applications.
Plain English, no scraping code. Describe the task naturally and the AI picks the right tool. No selectors, no proxy management, no anti-bot tuning.
Quick start
Zenrows MCP supports two transport options. Both expose the same set of tools and capabilities. Pick the one that fits your client.
What works without a key:
Local (npx @zenrows/mcp): no signup, no key. The first tool call creates a Free account (5,000 credits/month) that you can claim later, keeping the key and its usage. Opt out with ZENROWS_AUTO_SIGNUP=false. In CI, set ZENROWS_API_KEY as a secret or persist ZENROWS_HOME between runs.
Remote (https://mcp.zenrows.com/mcp):initialize and tools/list answer without a key; tool calls need one (OAuth in clients that support it, or a Bearer key). The remote server never creates accounts by itself. A headless agent can create a Free account with POST https://app.zenrows.com/api/agent/signup and use the returned apiKey as the Bearer token. The endpoint may first answer 428 with a short question; POST {"challenge_id": "...", "answer": "..."} back to the same URL to get the key.
Remote MCP server
Use the hosted Zenrows MCP server when your AI application calls an LLM API directly. The server runs on Zenrows' infrastructure, so there is nothing to install, configure, or update.
Server URL:
code
https://mcp.zenrows.com/mcp
Transport: Streamable HTTP
Authentication: OAuth or API key as Bearer token. Pass your Zenrows API key in the Authorization header on every request (or complete OAuth in clients that support it).
code
Authorization: Bearer YOUR_ZENROWS_API_KEY
Most MCP clients accept this through an authorization shorthand field on the tool config and forward it as the Bearer token automatically. Some clients use a free-form headers field instead. Either approach works.
Remote MCP does not auto-create accounts. initialize and tools/list work without a key; a keyless tool call gets a 401 whose body names the signup endpoint (agent_signup). Use OAuth “Create Free account” in the client, pass an existing API key, or, from a headless agent, POST https://app.zenrows.com/api/agent/signup (anonymous; returns apiKey, or first a 428 question to answer with challenge_id and answer; per-network limits apply) and retry with Authorization: Bearer <apiKey>.
Example: OpenAI Responses API
python
import os
from openai import OpenAI
ZENROWS_API_KEY = os.environ["ZENROWS_API_KEY"]
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
response = client.responses.create(
model="gpt-5",
tools=[
{
"type": "mcp",
"server_label": "zenrows",
"server_description": "Web scraping MCP server for accessing live web content.",
"server_url": "https://mcp.zenrows.com/mcp",
"authorization": ZENROWS_API_KEY,
"require_approval": "never",
}
],
input="Visit https://news.ycombinator.com/ and summarize the three most recent posts.",
)
print(response.output_text)
For the full walkthrough with framework-specific examples, see the Remote MCP server docs.
Local MCP server
Use the local stdio configuration when your MCP client runs the server as a local subprocess instead of calling a remote URL. This is the standard setup for desktop AI tools and IDE plugins, including Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Zed, and JetBrains IDEs.
Key previously stored in ~/.zenrows/secrets.json, or
Auto-signup (default): if neither is set, the server still starts, and the first tool call provisions a Free plan account via POST /api/agent/signup, persists the key + claim metadata under ~/.zenrows/ (secrets.json + account.json, mode 0600), and prints a claim URL on stderr. Zenrows may first ask a short question: the tool call then returns it, and the agent answers with the account_signup_answer tool, then retries. If signup is refused (for example the per-network cap in CI), that tool call returns an error saying when to retry; in CI, set ZENROWS_API_KEY as a secret or persist ZENROWS_HOME between runs. Opt out with ZENROWS_AUTO_SIGNUP=false: tool calls then return an error until a key is set. The signup request also sends a random per-machine id (shared with the Zenrows CLI) and a guess at the host agent (claude-code, cursor, …) so signups can be attributed; set ZENROWS_TELEMETRY=off to omit both.
Optional:ZENROWS_CRAWL_API_BASE sets the Crawl API base URL for the crawl_* tools (default https://api.zenrows.com/v1). Set it only to point those tools at another deployment.
Optional:ZENROWS_BATCH_API_BASE sets the Batch API base URL for the batch_* tools (default https://async.api.zenrows.com/v1). Set it only to point those tools at another deployment.
Optional:ZENROWS_FETCH_RETRIES lets scrape and extract retry, up to that many times, a call the API did not serve. The default 0 sends each call once. They retry a 429, 502, 503 or 504, and a connection that failed before the request was sent (refused, name resolution, unreachable network or host, connect timeout); every other status or error is returned at once, because the API may have received the request. Each wait is the Retry-After in whole seconds (clamped to 250 ms - 30 s), or else random between 250 ms and 1 s, 2 s, 4 s, ... up to 30 s. A retry starts only if its wait ends within 50 s of the first request, because MCP clients cancel a tool call at about 60 s; a retry that starts near 50 s can still run past that timeout. Each retry writes one line to stderr. The value is read once at start, and anything other than a whole number of 0 or more stops the server. The hosted server retries only if its operator sets it.
The exact location of this config varies by client. See the per-client setup guides for the file path for your client.
Structured JSON (extract=auto or css_extractor; autoparse is deprecated) + optional stealth flags. extract=auto is currently free (billing may apply later) and works on any prepared domain, with any API key. Returns parsed fields only; set include_html: true to also get the page HTML. Error REQS007 says why in reason: domain_not_prepared → call prepare_domain (the error carries its arguments; one URL works; we recommend 3 or more of the same page type, so add them to example_urls, up to 5); page_not_recognised → the domain is prepared, but this page is not one Extract extracts (a page with nothing to extract, such as a home page): try a product, article or listing page instead, retry it once in a few minutes if it should work, otherwise use css_extractor, and do not prepare again; domain_not_enabled → preparing does not help, use css_extractor. The error never offers autoparse, and the tool never falls back to it: fallback_autoparse is deprecated and has no effect (when it is true, the result carries a note saying it was ignored).
prepare_domain / prepared_domain_status
Prepare a domain for extract (mode=auto) after a REQS007 with reason domain_not_prepared. prepare_domain takes the domain and 1 to 5 example URLs. One works; we recommend 3 or more of the same page type (e.g. 3 product pages: https://www.example.com/products/a, /products/b and /products/c), because Extract compares pages of one type to check the fields it found and fill in fields one page is missing. Several page types can share the 5 (e.g. 3 product pages + 2 search-result pages). It returns at once with status: "preparing" (it never waits), and costs no credits. Preparation takes a few minutes: poll prepared_domain_status about every 30 seconds (status, current step, failure code, the account's monthly allowance used / limit / remaining, and next, the step to take now) until status is ready, then call extract again. Each new domain uses one allowance slot; a domain that is already prepared answers ready at once with already_prepared: true and uses none. The domain is the host: shop.example.com and example.com are prepared separately, and a leading www. is dropped.
Crawl API (api.zenrows.com/v1/crawls). New. Crawl is still evolving: new features are coming, limits may be tuned, and the changelog announces each change. Give one start URL, get back the URLs behind it on the same registrable domain (subdomains count), optionally with each page's HTML (output_format: "html"). crawl_create returns at once; call crawl_wait (counts and the first 20 URLs), then crawl_download to save every result to a local JSON-lines file (default ~/.zenrows/crawls/<crawl_id>.jsonl; a path must stay inside ~/.zenrows/crawls; an existing file is kept unless overwrite: true; the hosted server writes no file and returns the download URL and a curl command instead), or crawl_results to page through them. Leave depth out of crawl_create for no depth limit: the crawl follows links until max_pages or max_items (default 100 each) stops it, and each page fetched is billed as one scrape. Set idempotency_key on crawl_create to make a retry safe. crawl_content takes crawl_id and content_id (a content id or a result's content_url). Reads retry on 429, 502, 503, 504 and network errors (up to 3 times, honoring Retry-After up to 30 seconds); crawl_create retries only with an idempotency_key, and never on 429; crawl_stop retries on 429, 502, 503 and 504 (repeating a stop is safe; a 503 crawl_busy means the stop was not saved yet), up to 3 times and 50 seconds at most in all, and returns CRAWL_BUSY if a crawl_busy persists. May return CRAWL_NOT_ENABLED (Crawl is not enabled for this account).
browser_*
30+ tools for full browser automation (navigation, clicks, forms, JS, cookies, tabs, sessions).
Batch tools
A Batch job scrapes many URLs asynchronously. The usual flow: batch_create, then batch_wait until the run ends, batch_results to page through the rows, and batch_content to read one task's page.
batch_create submits one closed job with all its tasks, up to 100,000 per call. Each task takes a url (http or https, up to 2,048 characters), plus optional external_id (up to 128 characters of letters, digits, ., _ and -; need not be unique), metadata (up to 20 string-to-string entries, 4 KiB in all), method and body for POST tasks (body up to 16 KiB; POST is for read-only queries, since the target can receive a POST more than once), and scrape params, in zenrows_params or flat on the task. An unknown task field fails the call by name, before anything is sent. response_type takes markdown, plaintext or pdf; leave it out for HTML. Tasks use mode=auto unless you force js_render or premium_proxy. Every call sends an Idempotency-Key, generated unless you set idempotency_key: a repeat with the same key and body within 24 hours returns the original job instead of a second one, and a different body is BATCH_IDEMPOTENCY_CONFLICT. An error reply carries the key to retry with. Set wait: true to return when the run ends or pauses, or when wait_timeout (seconds, default 50) passes.
batch_status and batch_wait report the latest run's status (pending, running, completed, stopped, failed) and stats. batch_wait polls until the run ends, returns at once with paused: true on a paused run, and tolerates transient errors. Its timeout is in seconds (default 50, under the 60 seconds after which many clients cancel a call); when it runs out, the reply is the current state with ok: true, timed_out: true and a note, not an error. A call with a progressToken gets a progress notification after each poll. A run still writing its tasks (submits of 10,000 or more, and every rerun) has ingesting: true.
batch_results returns up to limit rows (default 100, max 1,000) and a next_cursor; pass it back as cursor until it is null. Filter with status: all, successful, failed or processing. Pass run_id for an earlier run. A row's result_url is presigned for 2 hours: list again, or use batch_content, for a fresh one. Results are kept 14 days by default; after that a successful row reads as expired, with no result_url.
batch_content returns one task's result. Text (HTML, Markdown, plain text, JSON) comes back inline, cut to max_chars (default 20,000); a PDF comes back as its presigned result_url; on a large run, finding it can take more than one call, and the reply then carries lookup_cursor to pass back. A task not finished yet is BATCH_TASK_NOT_READY, a failed one BATCH_TASK_FAILED (with task_error), an expired one BATCH_RESULT_EXPIRED.
batch_list lists the account's jobs, newest first (default 20 per page, max 100).
batch_cancel stops the current run for good: no waiting task starts, in-flight tasks finish and bill, results stay. batch_pause halts it until batch_resume; a paused run still counts as an active job. All three are idempotent, and on a run that already ended they answer with its final state and already_ended: true.
batch_rerun starts a new run once the latest one ended. By default it reruns the failed and pending tasks and carries the others over: the recovery after a run that ran out of credits or was cancelled. Pass status for other task statuses, or full: true to scrape every task again. A partial rerun works up to 10 days after the run started. It sends an Idempotency-Key.
batch_delete deletes a job with its runs and results, and frees its active-job slot.
Costs: the same credits as the regular API, per successful task: 1 basic, 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. An account runs 3 active jobs at once by default, shared with Crawl.
A run that ends failed answers ok: false, with error.code the same as the matching HTTP error (BATCH_INSUFFICIENT_CREDITS, BATCH_KEY_CAP_REACHED, or AUTH_INVALID for an inactive subscription; BATCH_RUN_FAILED otherwise), error.server_code (the failure_reason), error.job_id and advice. Fix the cause, then batch_rerun.
Errors carry code, message, detail, server_code (the Batch API's own code) and, for a call about one job, job_id:
Code
When
BATCH_INVALID_REQUEST
400: the request was rejected; invalid_tasks lists the first bad tasks. Nothing was created.
AUTH_INVALID
401: the API key was rejected, or, with server_codesubscription_inactive, the key is valid but the subscription needs fixing in Billing.
BATCH_INSUFFICIENT_CREDITS
402: the account has no credits left.
BATCH_KEY_CAP_REACHED
402: this API key reached one of its credit caps; the account's other keys still work.
BATCH_ACCESS_DENIED
403: Batch is not enabled for this account or key. Do not retry.
BATCH_NOT_FOUND
404: no such job, run or task for this account (a deleted job included).
429: a job limit more credits do not raise (3 active jobs, shared with Crawl; 5 scheduled jobs).
BATCH_RATE_LIMITED
Any other 429.
BATCH_FAILED
Any other HTTP error.
BACKEND_UNAVAILABLE
No response: a network error or timeout, after retries.
Reads retry on 429, 500, 502, 503, 504 and network errors, up to 3 times, honoring Retry-After up to 30 seconds. batch_create and batch_rerun retry on 500, 502, 503, 504, network errors and a 429 with Retry-After, always with the same Idempotency-Key; never on the job-limit 429. On BATCH_IDEMPOTENCY_CONFLICT for the same request, keep the key, check batch_list and retry later: a new key can create a second, billed job.
Schedules, webhooks, results exports, CSV inputs, open jobs (adding tasks over time), runs and task history are available through the Batch API and the Zenrows SDKs only.
The AI selects the right tool from your prompt. You don't call tools directly in code.
git clone https://github.com/ZenRows/zenrows-mcp
cd zenrows-mcp
npm install
cp .env.example .env# Optional: add your API key (stdio can auto-signup)
npm run dev # Run with .env loaded (requires Node.js 20.6+)
npm run build # Compile to dist/
npm run inspect # Open the MCP inspector UI
Running the Crawl end-to-end test
npm test stays offline. npm run test:e2e drives the crawl_* tools through a real MCP client against a live Crawl API: it creates a small crawl (depth 1, at most 3 URLs and 5 pages) of the start URL you give it, waits for it, reads its results and one page, lists crawls, stops the ended crawl, and checks the not-found error. It is skipped unless the first three variables are set:
ZENROWS_API_KEY: a key with Crawl access.
ZENROWS_CRAWL_API_BASE: the Crawl API base, e.g. https://api.zenrows.com/v1. Point it at a local or staging deployment to test against that instead.
ZENROWS_E2E_CRAWL_URL: the start URL to crawl, a listing page whose links lead to item pages.
ZENROWS_E2E_CRAWL_INCLUDE (optional): an include pattern; when set, the test checks that every result URL contains it.
bash
export ZENROWS_API_KEY=... # a key with Crawl accessexport ZENROWS_CRAWL_API_BASE=https://api.zenrows.com/v1
export ZENROWS_E2E_CRAWL_URL=https://example.com/products/
export ZENROWS_E2E_CRAWL_INCLUDE=/product/
npm run test:e2e
The crawl is billed to the key's account (at most 5 page fetches), and it counts against the account's limit of active jobs (3 by default), shared with its Batch jobs. When the account has reached that limit, the test waits and retries for up to 5 minutes.
Releases
Merge PRs with Conventional Commit titles, for example fix(extract): ... or
feat(crawl): .... fix, feat and perf need a scope.
After each merge to main, release-please opens or updates the PR
chore: release X.Y.Z. It sets the version in package.json,
package-lock.json and server.json. Do not change these by hand.
To release, merge that PR. The Release workflow runs the checks, creates the
tag vX.Y.Z and the GitHub release, and starts the Publish workflow. That
workflow publishes to npm and the MCP Registry, pushes the GHCR image and
deploys the hosted server.
To publish an existing tag again, run the Release workflow by hand from
main with that tag.
If the checks fail after the release PR is merged
The release PR runs CI like any other PR. After you merge it, the release
run checks the code again before it tags and publishes. If that check
fails, main already has the new version, but there is no tag, and the
merged release PR keeps the autorelease: pending label, which blocks the
next release PR. To recover:
Fix the problem in a normal PR and merge it.
Create the release on that fix commit, with the version from
.release-please-manifest.json:
gh release create vX.Y.Z --target <fix commit> --title vX.Y.Z --generate-notes --notes-start-tag <previous tag>
On the merged release PR, replace the label autorelease: pending with
autorelease: tagged.
Run the Release workflow by hand from main with the tag vX.Y.Z.
Optional. Without it, the first tool call creates a Free account (5,000 credits/month) you can claim later. ZENROWS_AUTO_SIGNUP=false opts out. Keys: https://app.zenrows.com/account/settings