io.github.ZenRows/zenrows-mcp

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.

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.

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.

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. Schedule…

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.

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.

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.

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.

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.

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.

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.

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.

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.

Check a checkbox or radio button.

Clear all cookies for the current browser session.

Delete every localStorage entry in the current page context.

Click an element on the page using a CSS selector.

Close a browser session and free all associated resources, including the concurrency slot it holds.

Drag an element from its current position to a target element.

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.

Clear an input field and set its value, replacing what was there (browser_type appends instead).

Move focus to an element, triggering focus-dependent UI changes.

Render the current page as a PDF document.

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.

Get the value of a specific attribute on an element.

Get all cookies for the current page.

Get the HTML source of an element or the full page.

Read one localStorage value in the current page context.

Get the visible text content of an element or the entire page body.

Get the title of the current page.

Get the current URL of the browser session.

Navigate back to the previous page in the browser history.

Navigate forward to the next page in the browser history.

Move the mouse cursor over an element to trigger hover effects.

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)

Open a new browser tab. Returns a tab_id to use with browser_switch_tab.

Press a keyboard key. Examples: "Enter", "Tab", "Escape", "ArrowDown", "Control+a".

Find all elements matching a CSS selector and return their text, HTML, and attributes.

Reload the current page of a browser session.

Take a screenshot of the current page or a specific element. Use for visual verification or when the accessibility tree is not sufficient.

Scroll the page in a given direction.

Select an option from a <select> dropdown element.

Set one or more cookies in the browser session. A cookie with the same name, domain and path replaces the existing one.

Write one localStorage value in the current page context. An existing value under the same key is replaced.

Switch focus to a different browser tab.

Type text into an input element. Appends to existing content unless clear_first is set.

Uncheck a checkbox, found by CSS selector, in a browser session.

Wait for a fixed duration. browser_wait_for_selector waits only until an element appears.

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).

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).