Zenrows MCP server: Fetch, Extract, Batch, and Browser Sessions for AI agents
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Bearer <ZENROWS_API_KEY> or OAuth. Needed for tool calls only. No auto-signup; agents can POST https://app.zenrows.com/api/agent/signup for a key (it may ask a short question first).
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
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.
This tool takes no arguments.
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.
No arguments.
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
}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.
| Argument | Type | Description |
|---|---|---|
| job_id* | string | Batch job id returned by batch_create or batch_list |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id"
],
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| job_id* | string | Batch job id returned by batch_create or batch_list |
| run_id | any | An earlier run's id (from batch_status or batch_rerun). Default: the job's latest run. |
| task_id* | string | task_id from a batch_results row |
| max_chars | any | Max characters of a text result to return (default 20000) |
| lookup_cursor | any | lookup_cursor from a previous batch_content reply on a binary result, to go on looking for its result_url |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id",
"task_id"
],
"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."
},
"task_id": {
"type": "string",
"minLength": 1,
"description": "task_id from a batch_results row"
},
"max_chars": {
"anyOf": [
{
"type": "integer",
"maximum": 10000000,
"minimum": 1000
},
{
"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"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| urls | any | Shorthand: list of URLs (converted to tasks), up to 100,000. Ignored when tasks is provided. |
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.
| Argument | Type | Description |
|---|---|---|
| job_id* | string | Batch job id returned by batch_create or batch_list |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id"
],
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| type | any | Only jobs of this type |
| limit | any | Jobs per page (default 20, max 100) |
| cursor | string | null | next_cursor from a previous batch_list call |
| status | any | Only jobs with this job status |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"type": {
"anyOf": [
{
"enum": [
"regular",
"scheduled"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Only jobs of this type"
},
"limit": {
"anyOf": [
{
"type": "integer",
"maximum": 100,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Jobs per page (default 20, max 100)"
},
"cursor": {
"type": [
"string",
"null"
],
"description": "next_cursor from a previous batch_list call"
},
"status": {
"anyOf": [
{
"enum": [
"open",
"closed"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Only jobs with this job status"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| job_id* | string | Batch job id returned by batch_create or batch_list |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id"
],
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| full | boolean | null | Rerun every task, not only some (default false) |
| job_id* | string | Batch job id returned by batch_create or batch_list |
| status | any | Task statuses to rerun (default ["failed", "pending"]). Ignored with full:true. |
| idempotency_key | any | 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. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id"
],
"properties": {
"full": {
"type": [
"boolean",
"null"
],
"description": "Rerun every task, not only some (default false)"
},
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
},
"status": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"failed",
"pending",
"processing",
"successful"
],
"type": "string"
},
"minItems": 1
},
{
"type": "null"
}
],
"description": "Task statuses to rerun (default [\"failed\", \"pending\"]). Ignored with full:true."
},
"idempotency_key": {
"anyOf": [
{
"type": "string",
"maxLength": 128,
"minLength": 1
},
{
"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."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| limit | any | Max rows to return (default 100, max 1000) |
| cursor | string | null | next_cursor from a previous batch_results call |
| job_id* | string | Batch job id returned by batch_create or batch_list |
| run_id | any | An earlier run's id (from batch_status or batch_rerun). Default: the job's latest run. |
| status | any | Filter rows by status (default all). processing = tasks not finished yet. successful also returns expired rows. |
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.
| Argument | Type | Description |
|---|---|---|
| job_id* | string | Batch job id returned by batch_create or batch_list |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id"
],
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| job_id* | string | Batch job id returned by batch_create or batch_list |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id"
],
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| job_id* | string | Batch job id returned by batch_create or batch_list |
| timeout | any | Max wait in seconds (default 50). Many MCP clients cancel a call after 60 s. |
| timeout_ms | any | Deprecated: the same wait in milliseconds. Use the seconds parameter instead. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id"
],
"properties": {
"job_id": {
"type": "string",
"minLength": 1,
"description": "Batch job id returned by batch_create or batch_list"
},
"timeout": {
"anyOf": [
{
"type": "integer",
"maximum": 3600,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Max wait in seconds (default 50). Many MCP clients cancel a call after 60 s."
},
"timeout_ms": {
"anyOf": [
{
"type": "integer",
"maximum": 3600000,
"minimum": 1000
},
{
"type": "null"
}
],
"description": "Deprecated: the same wait in milliseconds. Use the seconds parameter instead."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| actions* | array | Ordered list of actions to perform. Each action has a 'type' field plus type-specific parameters. |
| session_id* | string | Session ID returned by browser_navigate |
| stop_on_error | boolean | null | Stop executing on the first failed action (default true) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"type",
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"const": "navigate"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "go_back"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "go_forward"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "reload"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector"
],
"properties": {
"type": {
"type": "string",
"const": "click"
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector"
],
"properties": {
"type": {
"type": "string",
"const": "hover"
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector",
"text"
],
"properties": {
"text": {
"type": "string"
},
"type": {
"type": "string",
"const": "type"
},
"selector": {
"type": "string"
},
"clear_first": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector",
"value"
],
"properties": {
"type": {
"type": "string",
"const": "fill"
},
"value": {
"type": "string"
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector",
"value"
],
"properties": {
"type": {
"type": "string",
"const": "select"
},
"value": {
"type": "string"
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector"
],
"properties": {
"type": {
"type": "string",
"const": "check"
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector"
],
"properties": {
"type": {
"type": "string",
"const": "uncheck"
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector"
],
"properties": {
"type": {
"type": "string",
"const": "focus"
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"key"
],
"properties": {
"key": {
"type": "string"
},
"type": {
"type": "string",
"const": "press_key"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"direction"
],
"properties": {
"type": {
"type": "string",
"const": "scroll"
},
"distance": {
"type": [
"number",
"null"
]
},
"direction": {
"enum": [
"up",
"down",
"left",
"right"
],
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"source_selector",
"target_selector"
],
"properties": {
"type": {
"type": "string",
"const": "drag"
},
"source_selector": {
"type": "string"
},
"target_selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "get_accessibility_tree"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "get_url"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "get_title"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "get_text"
},
"selector": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector",
"attribute"
],
"properties": {
"type": {
"type": "string",
"const": "get_attribute"
},
"selector": {
"type": "string"
},
"attribute": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "get_html"
},
"selector": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector"
],
"properties": {
"type": {
"type": "string",
"const": "query_selector_all"
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "screenshot"
},
"selector": {
"type": [
"string",
"null"
]
},
"full_page": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"selector"
],
"properties": {
"type": {
"type": "string",
"const": "wait_for_selector"
},
"visible": {
"type": [
"boolean",
"null"
]
},
"selector": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"const": "wait_for_navigation"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"ms"
],
"properties": {
"ms": {
"type": "integer",
"maximum": 30000,
"minimum": 0
},
"type": {
"type": "string",
"const": "wait"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"script"
],
"properties": {
"type": {
"type": "string",
"const": "evaluate"
},
"script": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"maxItems": 50,
"minItems": 1,
"description": "Ordered list of actions to perform. Each action has a 'type' field plus type-specific parameters."
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"stop_on_error": {
"type": [
"boolean",
"null"
],
"description": "Stop executing on the first failed action (default true)"
}
},
"additionalProperties": false
}Check a checkbox or radio button.
| Argument | Type | Description |
|---|---|---|
| selector* | string | CSS selector of the checkbox or radio element |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector"
],
"properties": {
"selector": {
"type": "string",
"description": "CSS selector of the checkbox or radio element"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Clear all cookies for the current browser session.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Delete every localStorage entry in the current page context.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Click an element on the page using a CSS selector.
| Argument | Type | Description |
|---|---|---|
| selector* | string | CSS selector of the element to click |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector"
],
"properties": {
"selector": {
"type": "string",
"description": "CSS selector of the element to click"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Close a browser session and free all associated resources, including the concurrency slot it holds.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Drag an element from its current position to a target element.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
| source_selector* | string | CSS selector of the element to drag |
| target_selector* | string | CSS selector of the drop target |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"source_selector",
"target_selector"
],
"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"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| script* | string | JavaScript expression or function body to evaluate in the page context |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"script"
],
"properties": {
"script": {
"type": "string",
"description": "JavaScript expression or function body to evaluate in the page context"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Clear an input field and set its value, replacing what was there (browser_type appends instead).
| Argument | Type | Description |
|---|---|---|
| value* | string | Value to fill in |
| selector* | string | CSS selector of the input element |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector",
"value"
],
"properties": {
"value": {
"type": "string",
"description": "Value to fill in"
},
"selector": {
"type": "string",
"description": "CSS selector of the input element"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Move focus to an element, triggering focus-dependent UI changes.
| Argument | Type | Description |
|---|---|---|
| selector* | string | CSS selector of the element to focus |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector"
],
"properties": {
"selector": {
"type": "string",
"description": "CSS selector of the element to focus"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Render the current page as a PDF document.
| Argument | Type | Description |
|---|---|---|
| scale | any | Page scale factor (default 1) |
| landscape | boolean | null | Landscape orientation (default false) |
| session_id* | string | Session ID returned by browser_navigate |
| print_background | boolean | null | Print background graphics (default false) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"scale": {
"anyOf": [
{
"type": "number",
"maximum": 2,
"minimum": 0.1
},
{
"type": "null"
}
],
"description": "Page scale factor (default 1)"
},
"landscape": {
"type": [
"boolean",
"null"
],
"description": "Landscape orientation (default false)"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"print_background": {
"type": [
"boolean",
"null"
],
"description": "Print background graphics (default false)"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Get the value of a specific attribute on an element.
| Argument | Type | Description |
|---|---|---|
| selector* | string | CSS selector of the element |
| attribute* | string | Attribute name to retrieve (e.g. 'href', 'src', 'data-id') |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector",
"attribute"
],
"properties": {
"selector": {
"type": "string",
"description": "CSS selector of the element"
},
"attribute": {
"type": "string",
"description": "Attribute name to retrieve (e.g. 'href', 'src', 'data-id')"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Get all cookies for the current page.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Get the HTML source of an element or the full page.
| Argument | Type | Description |
|---|---|---|
| selector | string | null | CSS selector of the element (omit for full page HTML) |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"selector": {
"type": [
"string",
"null"
],
"description": "CSS selector of the element (omit for full page HTML)"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Read one localStorage value in the current page context.
| Argument | Type | Description |
|---|---|---|
| key* | string | Storage key to read |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"key"
],
"properties": {
"key": {
"type": "string",
"description": "Storage key to read"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Get the visible text content of an element or the entire page body.
| Argument | Type | Description |
|---|---|---|
| selector | string | null | CSS selector of the element (omit for full page body text) |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"selector": {
"type": [
"string",
"null"
],
"description": "CSS selector of the element (omit for full page body text)"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Get the title of the current page.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Get the current URL of the browser session.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Navigate back to the previous page in the browser history.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Navigate forward to the next page in the browser history.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Move the mouse cursor over an element to trigger hover effects.
| Argument | Type | Description |
|---|---|---|
| selector* | string | CSS selector of the element to hover over |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector"
],
"properties": {
"selector": {
"type": "string",
"description": "CSS selector of the element to hover over"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}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)
| Argument | Type | Description |
|---|---|---|
| url* | string | The URL to navigate to |
| proxy_region | string | null | World region code for geo-targeted proxy (eu=Europe, na=North America, ap=Asia Pacific, sa=South America, af=Africa, me=Middle East) |
| proxy_country | string | null | ISO 3166-1 alpha-2 country code for geo-targeted proxy (e.g. 'US', 'GB', 'DE') |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The URL to navigate to"
},
"proxy_region": {
"type": [
"string",
"null"
],
"description": "World region code for geo-targeted proxy (eu=Europe, na=North America, ap=Asia Pacific, sa=South America, af=Africa, me=Middle East)"
},
"proxy_country": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2 country code for geo-targeted proxy (e.g. 'US', 'GB', 'DE')"
}
},
"additionalProperties": false
}Open a new browser tab. Returns a tab_id to use with browser_switch_tab.
| Argument | Type | Description |
|---|---|---|
| url | any | URL to open in the new tab (opens blank tab if omitted) |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "URL to open in the new tab (opens blank tab if omitted)"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Press a keyboard key. Examples: "Enter", "Tab", "Escape", "ArrowDown", "Control+a".
| Argument | Type | Description |
|---|---|---|
| key* | string | Key to press (e.g. "Enter", "Tab", "Escape", "ArrowDown", "Control+a") |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"key"
],
"properties": {
"key": {
"type": "string",
"description": "Key to press (e.g. \"Enter\", \"Tab\", \"Escape\", \"ArrowDown\", \"Control+a\")"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Find all elements matching a CSS selector and return their text, HTML, and attributes.
| Argument | Type | Description |
|---|---|---|
| selector* | string | CSS selector to query |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector"
],
"properties": {
"selector": {
"type": "string",
"description": "CSS selector to query"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Reload the current page of a browser session.
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Take a screenshot of the current page or a specific element. Use for visual verification or when the accessibility tree is not sufficient.
| Argument | Type | Description |
|---|---|---|
| selector | string | null | CSS selector to capture only a specific element (overrides full_page) |
| full_page | boolean | null | Capture full page including content below the fold (default false) |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"selector": {
"type": [
"string",
"null"
],
"description": "CSS selector to capture only a specific element (overrides full_page)"
},
"full_page": {
"type": [
"boolean",
"null"
],
"description": "Capture full page including content below the fold (default false)"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Scroll the page in a given direction.
| Argument | Type | Description |
|---|---|---|
| distance | any | Pixels to scroll (default 500) |
| direction* | string | Scroll direction |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"direction"
],
"properties": {
"distance": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"description": "Pixels to scroll (default 500)"
},
"direction": {
"enum": [
"up",
"down",
"left",
"right"
],
"type": "string",
"description": "Scroll direction"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Select an option from a <select> dropdown element.
| Argument | Type | Description |
|---|---|---|
| value* | string | Value of the option to select |
| selector* | string | CSS selector of the <select> element |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector",
"value"
],
"properties": {
"value": {
"type": "string",
"description": "Value of the option to select"
},
"selector": {
"type": "string",
"description": "CSS selector of the <select> element"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Set one or more cookies in the browser session. A cookie with the same name, domain and path replaces the existing one.
| Argument | Type | Description |
|---|---|---|
| cookies* | array | Array of cookie objects to set |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"cookies"
],
"properties": {
"cookies": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string"
},
"path": {
"type": [
"string",
"null"
]
},
"value": {
"type": "string"
},
"domain": {
"type": [
"string",
"null"
]
},
"secure": {
"type": [
"boolean",
"null"
]
},
"expires": {
"type": [
"number",
"null"
],
"description": "Unix timestamp"
},
"http_only": {
"type": [
"boolean",
"null"
]
}
},
"additionalProperties": false
},
"description": "Array of cookie objects to set"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Write one localStorage value in the current page context. An existing value under the same key is replaced.
| Argument | Type | Description |
|---|---|---|
| key* | string | Storage key to write |
| value* | string | Value to store |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"description": "Storage key to write"
},
"value": {
"type": "string",
"description": "Value to store"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Switch focus to a different browser tab.
| Argument | Type | Description |
|---|---|---|
| tab_id* | string | Tab ID returned by browser_new_tab |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"tab_id"
],
"properties": {
"tab_id": {
"type": "string",
"description": "Tab ID returned by browser_new_tab"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Type text into an input element. Appends to existing content unless clear_first is set.
| Argument | Type | Description |
|---|---|---|
| text* | string | Text to type |
| selector* | string | CSS selector of the input element |
| session_id* | string | Session ID returned by browser_navigate |
| clear_first | boolean | null | Clear existing content before typing (default false) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector",
"text"
],
"properties": {
"text": {
"type": "string",
"description": "Text to type"
},
"selector": {
"type": "string",
"description": "CSS selector of the input element"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"clear_first": {
"type": [
"boolean",
"null"
],
"description": "Clear existing content before typing (default false)"
}
},
"additionalProperties": false
}Uncheck a checkbox, found by CSS selector, in a browser session.
| Argument | Type | Description |
|---|---|---|
| selector* | string | CSS selector of the checkbox element |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector"
],
"properties": {
"selector": {
"type": "string",
"description": "CSS selector of the checkbox element"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}Wait for a fixed duration. browser_wait_for_selector waits only until an element appears.
| Argument | Type | Description |
|---|---|---|
| ms* | integer | Milliseconds to wait (max 30000) |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"ms"
],
"properties": {
"ms": {
"type": "integer",
"maximum": 30000,
"minimum": 0,
"description": "Milliseconds to wait (max 30000)"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}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).
| Argument | Type | Description |
|---|---|---|
| session_id* | string | Session ID returned by browser_navigate |
| timeout_ms | any | How long to wait in milliseconds (default 30000, max 60000) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
},
"timeout_ms": {
"anyOf": [
{
"type": "integer",
"maximum": 60000,
"minimum": 1000
},
{
"type": "null"
}
],
"description": "How long to wait in milliseconds (default 30000, max 60000)"
}
},
"additionalProperties": false
}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).
| Argument | Type | Description |
|---|---|---|
| visible | boolean | null | Also require the element to be visible, not just present in the DOM (default false) |
| selector* | string | CSS selector to wait for |
| session_id* | string | Session ID returned by browser_navigate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id",
"selector"
],
"properties": {
"visible": {
"type": [
"boolean",
"null"
],
"description": "Also require the element to be visible, not just present in the DOM (default false)"
},
"selector": {
"type": "string",
"description": "CSS selector to wait for"
},
"session_id": {
"type": "string",
"description": "Session ID returned by browser_navigate"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| crawl_id* | string | Crawl id returned by crawl_create (c_…) |
| max_chars | any | Max characters of the page to return (default 20000) |
| content_id* | string | A content id (ct_…), or content_url from a crawl_results row; its last path segment is the id |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"crawl_id",
"content_id"
],
"properties": {
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
},
"max_chars": {
"anyOf": [
{
"type": "integer",
"maximum": 10000000,
"minimum": 1000
},
{
"type": "null"
}
],
"description": "Max characters of the page to return (default 20000)"
},
"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"
}
},
"additionalProperties": false
}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. 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.
| Argument | Type | Description |
|---|---|---|
| url* | string | Start URL: a public http(s) page, such as a listing or category page |
| depth | any | 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. |
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.
| Argument | Type | Description |
|---|---|---|
| path | any | File to write, relative to ~/.zenrows/crawls (default <crawl_id>.jsonl) |
| crawl_id* | string | Crawl id returned by crawl_create (c_…) |
| overwrite | boolean | null | Replace the file if it exists (default false) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"crawl_id"
],
"properties": {
"path": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"description": "File to write, relative to ~/.zenrows/crawls (default <crawl_id>.jsonl)"
},
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
},
"overwrite": {
"type": [
"boolean",
"null"
],
"description": "Replace the file if it exists (default false)"
}
},
"additionalProperties": false
}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), 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.
| Argument | Type | Description |
|---|---|---|
| limit | any | Results in this page (default 100, max 10000) |
| cursor | string | null | next_cursor from a previous crawl_get call, to continue from there |
| crawl_id* | string | Crawl id returned by crawl_create (c_…) |
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.
| Argument | Type | Description |
|---|---|---|
| limit | any | Crawls per page (default 20, max 100) |
| cursor | string | null | next_cursor from a previous crawl_list call |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"anyOf": [
{
"type": "integer",
"maximum": 100,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Crawls per page (default 20, max 100)"
},
"cursor": {
"type": [
"string",
"null"
],
"description": "next_cursor from a previous crawl_list call"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| limit | any | Max results to return in this call (default 100, max 10000) |
| cursor | string | null | next_cursor from a previous crawl_results call, to continue from there |
| crawl_id* | string | Crawl id returned by crawl_create (c_…) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"crawl_id"
],
"properties": {
"limit": {
"anyOf": [
{
"type": "integer",
"maximum": 10000,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Max results to return in this call (default 100, max 10000)"
},
"cursor": {
"type": [
"string",
"null"
],
"description": "next_cursor from a previous crawl_results call, to continue from there"
},
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| crawl_id* | string | Crawl id returned by crawl_create (c_…) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"crawl_id"
],
"properties": {
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| timeout | any | Max wait in seconds (default 50). Many MCP clients cancel a call after 60 s. |
| crawl_id* | string | Crawl id returned by crawl_create (c_…) |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"crawl_id"
],
"properties": {
"timeout": {
"anyOf": [
{
"type": "integer",
"maximum": 3600,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Max wait in seconds (default 50). Many MCP clients cancel a call after 60 s."
},
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
}
},
"additionalProperties": false
}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 (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.
| Argument | Type | Description |
|---|---|---|
| url* | string | The webpage URL to extract from |
| mode | any | Extraction mode: auto (extract=auto, default), css (requires css_extractor), or the deprecated autoparse |
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: real pages you want extracted, one per page kind (for example one product page and one listing page). 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.
| Argument | Type | Description |
|---|---|---|
| domain* | string | The host to prepare, e.g. shop.example.com (a URL is accepted; a leading www. is dropped) |
| example_urls* | array | 1 to 5 full URLs of real pages on this domain that you want to extract, one per page kind |
| idempotency_key | string | null | Optional. Resending the same key with the same body returns the original submission |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"domain",
"example_urls"
],
"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"
},
"maxItems": 5,
"minItems": 1,
"description": "1 to 5 full URLs of real pages on this domain that you want to extract, one per page kind"
},
"idempotency_key": {
"type": [
"string",
"null"
],
"description": "Optional. Resending the same key with the same body returns the original submission"
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| domain* | string | The domain passed to prepare_domain, e.g. example.com |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"minLength": 1,
"description": "The domain passed to prepare_domain, e.g. example.com"
}
},
"additionalProperties": false
}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 }
| Argument | Type | Description |
|---|---|---|
| url* | string | The webpage URL to scrape |
| wait | any | 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. |
| outputs | string | null | 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. |
| wait_for | string | null | 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 | boolean | null | If true, poll before returning until the run ends or pauses, or wait_timeout passes; a timeout returns the current state with ok:true |
| tasks | any | Tasks (each needs a url), up to 100,000. Prefer this over urls when you need per-task params. |
| js_render | boolean | null | Force js_render on all tasks (5 credits each). Overrides automatic mode (mode=auto), which already renders when needed. |
| mode_auto | boolean | null | Automatic mode (mode=auto) is on by default; leave unset. False sends plain requests without it. |
| wait_timeout | any | Max wait in seconds when wait=true (default 50). Many MCP clients cancel a call after 60 s. |
| premium_proxy | boolean | null | 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. |
| proxy_country | string | null | Job-level ISO country code. Works in automatic mode (mode=auto); with js_render alone it requires premium_proxy. |
| response_type | any | Job-level output format. Leave unset for the raw HTML, the default. |
| zenrows_params | any | 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 | any | 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_timeout_ms | any | Deprecated: the same wait in milliseconds. Use the seconds parameter instead. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"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."
},
"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"
},
"tasks": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Target URL for this task: http or https, up to 2,048 characters"
},
"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."
},
"method": {
"anyOf": [
{
"enum": [
"GET",
"POST"
],
"type": "string"
},
{
"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."
},
"metadata": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"pattern": "^[A-Za-z0-9._-]+$",
"maxLength": 64,
"minLength": 1
},
"additionalProperties": {
"type": "string",
"maxLength": 1024
}
},
{
"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."
},
"external_id": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z0-9._-]+$",
"maxLength": 128
},
{
"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."
},
"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."
}
},
"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.",
"additionalProperties": true
},
"maxItems": 100000
},
{
"type": "null"
}
],
"description": "Tasks (each needs a url), up to 100,000. Prefer this over urls when you need per-task params."
},
"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."
},
"mode_auto": {
"type": [
"boolean",
"null"
],
"description": "Automatic mode (mode=auto) is on by default; leave unset. False sends plain requests without it."
},
"wait_timeout": {
"anyOf": [
{
"type": "integer",
"maximum": 3600,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Max wait in seconds when wait=true (default 50). Many MCP clients cancel a call after 60 s."
},
"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."
},
"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": [
{
"enum": [
"markdown",
"plaintext",
"pdf"
],
"type": "string"
},
{
"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",
"maxLength": 128,
"minLength": 1
},
{
"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_timeout_ms": {
"anyOf": [
{
"type": "integer",
"maximum": 3600000,
"minimum": 1000
},
{
"type": "null"
}
],
"description": "Deprecated: the same wait in milliseconds. Use the seconds parameter instead."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"job_id"
],
"properties": {
"limit": {
"anyOf": [
{
"type": "integer",
"maximum": 1000,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Max rows to return (default 100, max 1000)"
},
"cursor": {
"type": [
"string",
"null"
],
"description": "next_cursor from a previous batch_results call"
},
"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": [
{
"enum": [
"successful",
"failed",
"processing",
"all"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter rows by status (default all). processing = tasks not finished yet. successful also returns expired rows."
}
},
"additionalProperties": false
}| discovery | any | 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. |
| max_items | any | Stop once this many URLs are kept (default 100) |
| max_pages | any | Stop once this many pages are fetched, each billed as one scrape (default 100). With output_format, every kept URL's page counts too. |
| output_format | any | 'html' or 'markdown' also stores each kept URL's page for crawl_content, as fetched or converted to Markdown. Omit for URLs only. |
| idempotency_key | any | Sent as the Idempotency-Key header. Reusing a key returns the crawl it created; reusing it with a different body is CRAWL_INVALID_REQUEST. |
| exclude_patterns | any | Drop URLs containing any of these substrings, even if they match include_patterns |
| include_patterns | any | Keep only URLs containing at least one of these substrings, e.g. ["/product/"] |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url"
],
"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."
},
"discovery": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"links"
],
"type": "string"
},
"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."
},
"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."
},
"output_format": {
"anyOf": [
{
"enum": [
"html",
"markdown"
],
"type": "string"
},
{
"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."
},
"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."
},
"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"
},
"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/\"]"
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"crawl_id"
],
"properties": {
"limit": {
"anyOf": [
{
"type": "integer",
"maximum": 10000,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Results in this page (default 100, max 10000)"
},
"cursor": {
"type": [
"string",
"null"
],
"description": "next_cursor from a previous crawl_get call, to continue from there"
},
"crawl_id": {
"type": "string",
"description": "Crawl id returned by crawl_create (c_…)"
}
},
"additionalProperties": false
}| wait | any | Milliseconds to wait after load. Requires js_render=true; without it, including in automatic mode, it may be ignored. |
| wait_for | string | null | CSS selector to wait for before extracting. Requires js_render=true; without it, including in automatic mode, it may be ignored. |
| js_render | boolean | null | Force JS rendering on every request. Overrides automatic mode (mode=auto), which already renders when needed. |
| mode_auto | boolean | null | Automatic mode (mode=auto) is on by default; leave unset. False sends a plain request without it. |
| include_html | boolean | null | mode=auto only: also return the full page HTML. Default false; the HTML is most of the response size. |
| css_extractor | string | null | Required when mode=css. JSON map of field→selector, e.g. '{"title":"h1","price":".price"}' |
| premium_proxy | boolean | null | 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 | ISO 3166-1 alpha-2 country code. Works in automatic mode (mode=auto); with js_render or mode_auto=false it requires premium_proxy. |
| fallback_autoparse | boolean | null | Deprecated, has no effect: Extract no longer falls back to autoparse. Prepare the domain with prepare_domain instead. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The webpage URL to extract from"
},
"mode": {
"anyOf": [
{
"enum": [
"auto",
"autoparse",
"css"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "auto",
"description": "Extraction mode: auto (extract=auto, default), css (requires css_extractor), or the deprecated autoparse"
},
"wait": {
"anyOf": [
{
"type": "integer",
"maximum": 30000,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Milliseconds to wait after load. Requires js_render=true; without it, including in automatic mode, it may be ignored."
},
"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."
},
"js_render": {
"type": [
"boolean",
"null"
],
"description": "Force JS rendering on every request. Overrides automatic mode (mode=auto), which already renders when needed."
},
"mode_auto": {
"type": [
"boolean",
"null"
],
"description": "Automatic mode (mode=auto) is on by default; leave unset. False sends a plain request without it."
},
"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."
},
"css_extractor": {
"type": [
"string",
"null"
],
"description": "Required when mode=css. JSON map of field→selector, e.g. '{\"title\":\"h1\",\"price\":\".price\"}'"
},
"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."
},
"fallback_autoparse": {
"type": [
"boolean",
"null"
],
"description": "Deprecated, has no effect: Extract no longer falls back to autoparse. Prepare the domain with prepare_domain instead."
}
},
"additionalProperties": false
}| autoparse | boolean | null | Deprecated: general-purpose structured JSON from the page. Prefer the extract tool (extract=auto on a prepared domain, or css_extractor). |
| js_render | boolean | null | 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. |
| screenshot | boolean | null | Capture an above-the-fold screenshot of the page. Returns an image instead of text content. Useful for visual verification or debugging. |
| css_extractor | string | null | 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. |
| premium_proxy | boolean | null | 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 | 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 | 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. |
| js_instructions | string | null | 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"}] |
| screenshot_fullpage | boolean | null | Capture a full-page screenshot including content below the fold. Returns an image instead of text content. |
| screenshot_selector | string | null | Capture a screenshot of a specific element using a CSS selector. Example: ".product-card". Returns an image instead of text content. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "The webpage URL to scrape"
},
"wait": {
"anyOf": [
{
"type": "integer",
"maximum": 30000,
"minimum": 0
},
{
"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."
},
"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."
},
"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."
},
"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)."
},
"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."
},
"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."
},
"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."
},
"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": [
{
"enum": [
"markdown",
"plaintext",
"pdf",
"html"
],
"type": "string"
},
{
"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."
},
"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\"}]"
},
"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."
}
},
"additionalProperties": false
}