zenrows-mcp

Submit a cloud Batch job that fans out: many URLs scraped asynchronously in the cloud (Zenrows Batch API).

NOT the same as browser_batch — this hits https://async.api.zenrows.com/v1 with X-API-Key.
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, and charges
only for the configuration that succeeds.them. Pass just the URLs. Set js_render or
 premium_proxy (job-level, or in a task'sper zenrows_paramstask) only to force a fixed
 configuration; that turns automatic mode off for those tasks.

Cost: the affectedsame 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 bills410 answers, billed as on the regular API.
themLimits: atup to 100,000 tasks per call; 3 active jobs per account by default, shared with Crawl (BATCH_QUOTA_EXCEEDED past that); configuration'sa cost.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 latest_run.status/stats.and batch_statusstats andat once; the job runs asynchronously. Then: batch_wait reportuntil progress;it ends, batch_results liststo thelist results.
Ifrows you(paged), getbatch_content BATCH_ACCESS_DENIEDto read one task's page. A run that ends failed (out of credits, Batchinactive issubscription, notkey enabledcap) 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 accountkey's orcap), 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 key.and SDKs only.

{"$schema":"http://json-schema.org/draft-07/schema#","additionalProperties":false,"properties":{"idempotency_key":{"anyOf":[{"maxLength":128,"minLength":1,"type":"string"},{"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."},"js_render":{"description":"Force js_render on all tasks.tasks (5 credits each). Overrides automatic mode (mode=auto), which already renders ⟨26 unchanged words⟩ "description":"Force premium_proxy on all tasks (10x10 costcredits each, 25 with js_render). Overrides automatic mode (mode=auto), which  ⟨35 unchanged words⟩ [{"enum":["markdown","plaintext","html","pdf"],"type":"string"},{"type":"null"}],"description":"Job-level response_typeoutput format. Leave unset for the raw HTML, the default."},"tasks":{"anyOf":[{"items":{"additionalProperties":falsetrue,"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.","properties":{"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."},"

List a Batch run's result rows, fora page at a Batchtime: jobup (cursor-paginatedto server-side;limit returnsrows the(default full100, listmax 1000). and next_cursor. Pass next_cursor back as cursor to continue; it is null once every row was read.

Each row may includehas task_id, external_id, url, metadata, status (successful, failed, pending, processing, expired), type, result_url when successful, and aerror short-livedwhen failed. A result_url is presigned and expires after 2 hours: call batch_results again for a fresh one, or read the body.
Downloadbody with batch_content. Results are kept 14 days by default; after that a successful row reads as status "expired", with no result_url, soonand —batch_content presignedanswers linksBATCH_RESULT_EXPIRED.

Filter expire.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.

{"$schema":"http://json-schema.org/draft-07/schema#","additionalProperties":false,"properties":{"cursor":{"description":"next_cursor from a previous batch_results call","type":["string","null"]},"job_id":{"description":"Batch job id returned by batch_create or batch_list","minLength":1,"type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"description":"Max rows to return (default 100, max 1000)"},"run_id":{"anyOf":[{"minLength":1,"type":"string"},{"type":"null"}],"description":"An earlier run's id (from batch_status or batch_rerun). Default: the job's latest run."},"status":{"anyOf":[{"enum":["successful","failed","processing","all"],"type":"string"},{"type":"null"}],"description":"Filter resultsrows by status (default: all). processing = tasks not finished yet. successful also returns expired rows."}},"required":["job_id"],"type":"object"}

Get a Batch job's latest run: job_id, run_id, status and(pending, running, completed, stopped, failed), stats for(total, acompleted, Zenrowssuccessful, Batchfailed) joband the job.

A failed run answers ok:false with error.code BATCH_INSUFFICIENT_CREDITS, BATCH_KEY_CAP_REACHED, AUTH_INVALID (latest_run.statussubscription_inactive) +or latest_run.statsBATCH_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.

 ⟨7 unchanged words⟩ "description":"Batch job id returned by batch_create or batch_list","minLength":1,"type":"string"}},"required":[ ⟨3 unchanged words⟩ 

Poll batch_status untila theBatch job reachesuntil aits terminalrun stateends (completed, stopped or failed) or pauses, stoppedand return its status and stats like batch_status. If the wait runs out first, orit deleted).returns the current state with ok:true, timed_out:true and a note: call batch_wait again. A paused run thatreturns hitsat anonce APIwith keypaused:true credit(it capdoes endsnot asmove until batch_resume). A failed run answers ok:false with failure_reasonerror.code api_key_cap_reached.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.

 ⟨6 unchanged words⟩ {"job_id":{"description":"Batch job id returned by batch_create or batch_list","minLength":1,"type":"string"},"timeout_mstimeout":{"anyOf":[{"maximum":36000003600,"minimum":10001,"type":"integer"},{"type":"null"}],"description":"Max wait time in msseconds (default 60000050). Many MCP clients cancel a call after 60 s."},"timeout_ms":{"anyOf":[{"maximum":3600000,"minimum":1000,"type":"integer"},{"type":"null"}],"description":"Deprecated: the same wait in milliseconds. Use the seconds parameter instead."}},"required":["job_id"],"type":"object"}

{"destructiveHint":falsetrue,"openWorldHint":true,"readOnlyHint":false,"title":"Clear Cookies"}

 ⟨8 unchanged words⟩ 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,  ⟨4 unchanged words⟩ billing may apply later). Works on any domain Zenrows has prepared domain, with any
   API key;key.
  Error fallsREQS007 backsays why in "reason":
  - domain_not_prepared: call prepare_domain with the domain and 1 to autoparse5 whenexample
    URLs (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 isn'tis prepared, yetbut this page is not one
    Extract extracts (REQS007a 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 domaindomain; use only
  when asked for
- css: css_extractor with an explicit selector  ⟨101 unchanged words⟩ 

 ⟨27 unchanged words⟩ "string","null"]},"fallback_autoparse":{"description":"Deprecated, has no effect: Extract no longer falls back to autoparse. Prepare the domain with prepare_domain instead.","type":["boolean","null"]},"include_html":{"default":truefalse,"description":"When mode=auto and theonly: domainalso isn'treturn preparedthe forfull Extractpage yetHTML. (REQS007,Default orfalse; the legacy AUTH010),HTML retryis 

 ⟨5 unchanged words⟩ ,"properties":{"autoparse":{"description":"AutomaticallyDeprecated: extractgeneral-purpose structured dataJSON from the pagepage. intoPrefer JSON.the Bestextract fortool product(extract=auto pages,on articlesa prepared domain, andor listings.css_extractor).","type":["boolean","null"]} ⟨441 unchanged words⟩ 

 ⟨28 unchanged words⟩  (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 ⟨29 unchanged words⟩ 

 ⟨156 unchanged words⟩ costs that one scrape. Set output_format "html" or "markdown" to also store each kept URL's page,
then ⟨76 unchanged words⟩ 

 ⟨42 unchanged words⟩  until max_pages or max_items stops it."},"discovery":{"anyOf":[{"items":{"enum":["links"],"type":"string"},"minItems":1,"type":"array"},{"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."},"exclude_patterns":{"anyOf":[{"items":{" ⟨127 unchanged words⟩ :{"anyOf":[{"enum":["html","markdown"],"type":"string"},{"type":"null"}],"description":"'html' or 'markdown' also stores each kept URL's page for crawl_content.crawl_content, as fetched or converted to Markdown. Omit for URLs only."},"url":{ ⟨23 unchanged words⟩ 

 ⟨103 unchanged words⟩ : 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: ⟨17 unchanged words⟩ 

 ⟨30 unchanged words⟩ 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); failed carries error.code and error.detail. 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; ⟨16 unchanged words⟩