# Stealth Browser Agent (`shelvick/stealth-browser-agent`) Actor Stealth browser agent for bot-defended websites. Send a URL and a natural language task — the agent navigates, clicks, fills forms, and extracts structured results with anti-detection fingerprinting and residential proxy. Designed for AI agents that need to interact with defended sites. - **URL**: https://apify.com/shelvick/stealth-browser-agent.md - **Developed by:** [Scott Helvick](https://apify.com/shelvick) (community) - **Categories:** AI, Agents, Automation - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $17.00 / 1,000 step completeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Stealth Browser Agent AI agents need to interact with web pages that block automation. This Actor provides hosted stealth browser infrastructure — send a URL and a natural language task, and an LLM-driven browser clicks, types, navigates, and extracts structured JSON from bot-defended sites. ### What this does - **Stealth browsing** — anti-detection fingerprinting passes real-world bot detection systems. Pages see a genuine browser, not automation tooling. - **Residential proxy** — optional geo-targeted routing through residential IPs. Datacenter IPs are a fingerprint signal; residential routing eliminates that vector. - **LLM-driven interaction** — an AI copilot reads screenshots, plans actions, and drives browser tools (click, type, navigate, scroll, select, wait). No automation scripts to write. - **Structured extraction** — the agent returns results as JSON. Provide an output schema and the result conforms to it; omit it and the agent returns best-effort JSON. - **Action log + screenshot** — every run produces a step-by-step action log and a final screenshot for debugging and audit. Use cases: - Extract product data from bot-defended e-commerce pages - Fill and submit multi-step forms on behalf of an agent workflow - Navigate paginated catalogs — click through pages, extract across them - Scrape structured data from JavaScript-heavy SPAs that block HTTP fetchers - Verify page state after interaction (confirmation pages, submission results) ### Why stealth matters Most browser automation works fine on cooperative sites. But a growing share of the web uses bot detection — fingerprinting browser characteristics, checking IP reputation, analyzing interaction patterns. Standard headless browsers get flagged on first request. The subtler problem: even when requests succeed, bot-detection systems serve degraded content to suspected bots. Different prices, missing inventory, placeholder text. Your agent extracts data that looks correct but isn't. This Actor runs a browser with realistic fingerprinting that passes detection systems in production. Pages see a real browser session. When combined with residential proxy routing, the browser's network fingerprint matches its claimed identity — no datacenter IP giving away the automation. ### How it compares to alternatives | Approach | Stealth | Interaction | Structured output | Cost model | |---|---|---|---|---| | Headless browser (self-hosted) | None — detected immediately | Full (you write scripts) | Manual extraction | Your infrastructure | | Stealth fetch service | Anti-detection | None — page content only | Raw HTML/markdown | Per-page | | Browser-as-a-service (no stealth) | None | Full (LLM-driven) | LLM-extracted | Per-step or flat | | **Stealth Browser Agent** | Anti-detection + residential proxy | Full (LLM-driven) | Structured JSON | Per-step | Stealth fetch services return rendered content from defended pages but can't interact — if you need to click a button before the data appears, you're stuck. Browser-as-a-service tools provide LLM-driven interaction but use standard browsers that get fingerprinted on defended sites. This Actor combines both: stealth browsing with LLM-driven interaction and structured extraction. ### Input | Field | Type | Required | Default | Description | |---|---|---|---|---| | `url` | string | Yes | -- | Starting URL. The agent navigates here first, then executes the task. Must be a public, unauthenticated page. | | `task` | string | Yes | -- | What to do on the page, in plain language. Can include interaction steps (click, fill, navigate) and extraction goals. The agent plans and executes actions, then returns structured results. | | `outputSchema` | object | No | -- | JSON Schema for the desired result shape. When provided, the agent structures its extraction to match. When omitted, returns best-effort JSON. | | `maxSteps` | integer | No | `30` | Maximum browser actions. Safety cap — the primary cost cap is `maxTotalChargeUsd`. Each tool call counts as one step. | | `timeoutSeconds` | integer | No | `120` | Hard deadline in seconds. If the agent hasn't finished, it returns whatever it has with status `timeout`. | | `proxyGeo` | string | No | -- | ISO 3166-1 alpha-2 country code (e.g. `US`, `DE`). Routes through a residential proxy in that country. Leave empty for default routing. | ### Output Each run produces one dataset record: ```json { "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html", "task": "Click the first book, extract its title and price.", "status": "completed", "result": { "title": "A Light in the Attic", "price": "£51.77" }, "steps": [ {"step": 1, "tool": "click_element", "args": {"selector": "article h3 a"}, "success": true}, {"step": 2, "tool": "get_text", "args": {"selector": ".product_main"}, "success": true} ], "screenshotUrl": "https://api.apify.com/v2/key-value-stores/abc123/records/screenshot" } ```` | Field | Type | Description | |---|---|---| | `url` | string | Final URL after all navigation and redirects | | `task` | string | Echo of the input task | | `status` | string | `completed`, `failed`, `timeout`, or `max_steps_reached` | | `result` | object | Structured extraction — shaped by `outputSchema` if provided | | `steps` | array | Ordered action log: step number, tool name, arguments, success flag | | `screenshotUrl` | string | Public URL of the final page screenshot | | `error` | string | Error message when status is not `completed` (null otherwise) | ### Example ```json { "url": "https://books.toscrape.com", "task": "Click the first book, then extract its title, price, and availability. Return JSON with fields title, price, and in_stock.", "maxSteps": 10 } ``` **curl:** ```bash curl -X POST "https://api.apify.com/v2/acts/shelvick~stealth-browser-agent/run-sync-get-dataset-items?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"url":"https://books.toscrape.com","task":"Click the first book, extract its title and price.","maxSteps":10}' ``` **Python SDK:** ```python from apify_client import ApifyClient client = ApifyClient("YOUR_TOKEN") run = client.actor("shelvick/stealth-browser-agent").call( run_input={ "url": "https://books.toscrape.com", "task": "Click the first book, extract its title and price.", "maxSteps": 10, } ) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item["result"]) ``` ### Calling from an AI agent #### Apify MCP server The Actor is available as a callable tool via `mcp.apify.com`. The input schema is self-documenting — an LLM can construct correct calls from the tool description and field names alone. Agentic payment is supported via x402 USDC on Base or Skyfire managed tokens. #### Apify SDK (Python) ```python from apify_client import ApifyClient client = ApifyClient("YOUR_TOKEN") run = client.actor("shelvick/stealth-browser-agent").call( run_input={ "url": "https://example.com", "task": "Extract the main heading and all links on the page.", } ) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item["status"], item["result"]) ``` #### REST API **Synchronous** (blocks until complete, returns dataset items directly): ``` POST https://api.apify.com/v2/acts/shelvick~stealth-browser-agent/run-sync-get-dataset-items?token=YOUR_TOKEN ``` **Asynchronous** (starts run, poll for completion): ``` POST https://api.apify.com/v2/acts/shelvick~stealth-browser-agent/runs?token=YOUR_TOKEN GET https://api.apify.com/v2/actor-runs/{runId}/dataset/items?token=YOUR_TOKEN ``` The synchronous endpoint has a 5-minute cap. For complex tasks that may exceed this, use the async endpoint. ### Pricing Charged per step — each browser action (click, type, navigate, extract) counts as one billable step. Two tiers: - **Standard step** — no proxy routing. Covers the planning call and browser action execution. - **Proxy step** — residential proxy routing included. Activates when `proxyGeo` is set. Higher per-step cost covers residential bandwidth. Failed steps (browser errors) and failed planning calls are never charged. Only successful tool executions are billed. The extraction step (when the agent returns its final result) counts as one step. The primary cost cap is the run's `maxTotalChargeUsd` setting. The `maxSteps` input is a secondary safety net. See the **Pricing** tab on this Store page for the current per-event rates and any active subscriber discounts. ### Behavior **Failure modes:** - `failed` — the agent could not accomplish the task (page requires authentication, target element not found, page is blank or broken) - `timeout` — the hard deadline (`timeoutSeconds`) was reached before completion. Partial results may be present in `result`. - `max_steps_reached` — the step limit was hit before completion. Increase `maxSteps` or simplify the task. The `error` field contains a human-readable explanation on non-`completed` runs. **Run-level failures** (rare): invalid input (missing `url` or `task`, malformed `outputSchema`) causes immediate failure before any steps execute. No steps are charged. **Performance expectations:** - Simple extraction (1-2 steps): 15-30 seconds - Multi-step interaction (3-5 steps): 30-60 seconds - Complex multi-page flows (8-15 steps): 60-120 seconds - Each step includes LLM planning (~2-5s) plus browser action execution (~1-3s) - Residential proxy adds ~1-2 seconds latency per navigation ### FAQ **What if the page requires a login?** The agent refuses to enter credentials or authenticate. If the page redirects to a login wall, the agent returns `status: failed` with an error message. This is a deliberate safety boundary. **Am I charged if the task fails?** Steps that completed successfully before the failure are charged. The failing step itself is not. If the run fails before any steps execute (invalid input, unreachable URL), nothing is charged beyond the platform start event. **How do I control costs on complex tasks?** Set `maxTotalChargeUsd` in the run configuration. This is the hard ceiling — the run stops when the charge limit is reached, regardless of `maxSteps`. For tighter control, lower `maxSteps` and simplify the task instruction. **Can I use this for batch scraping?** This Actor handles one URL per run. For batch work, start multiple runs in parallel via the API or SDK. Each run is independent with its own browser session. ### What this doesn't do - **No authentication.** The agent will not log in, enter passwords, or handle session tokens. Public, unauthenticated pages only. - **No CAPTCHA solving.** Sites requiring interactive CAPTCHAs (puzzle, image selection) will fail. Invisible scoring CAPTCHAs (reCAPTCHA v3) are handled by the stealth fingerprint. - **No file downloads.** The agent interacts with page content but does not download PDFs, images, or other files. - **No persistent sessions.** Each run starts a fresh browser — no cookies, local storage, or session state carries over between runs. For authenticated browsing or session management, use a browser-automation Actor with credential support. For bulk page fetching without interaction (no clicking or form filling), a batch fetcher is more cost-effective. For CAPTCHA-heavy sites requiring human solving, use a CAPTCHA-solving service upstream and pass the unlocked URL to this Actor. *** Design notes: [www.scotthelvick.com/tools/stealth-browser-agent](https://www.scotthelvick.com/tools/stealth-browser-agent) # Actor input Schema ## `url` (type: `string`): The web page to start on. The agent navigates here first, then executes the task. Must be a public, unauthenticated page. ## `task` (type: `string`): What to do on the page, in plain language. Can include interaction steps (click, fill, navigate) and extraction goals (find prices, collect links). The agent plans and executes actions to accomplish this task, then returns structured results. ## `outputSchema` (type: `object`): Optional JSON Schema describing the desired shape of the result object. When provided, the agent structures its final extraction to match this schema. When omitted, the agent returns a best-effort JSON object. ## `maxSteps` (type: `integer`): Maximum number of browser actions the agent may take. Safety cap to prevent runaway loops — the primary cost cap is maxTotalChargeUsd. Each tool call (click, type, navigate, extract, etc.) counts as one step. ## `timeoutSeconds` (type: `integer`): Hard deadline for the entire task. If the agent hasn't finished by this time, it returns whatever it has with status 'timeout'. ## `proxyGeo` (type: `string`): ISO 3166-1 alpha-2 country code for geo-targeted browsing. Routes the browser through a residential proxy in this country. Leave empty for default routing. ## Actor input object example ```json { "url": "https://example.com", "task": "Find the main heading and any links on the page. Return them as a JSON object with fields 'heading' and 'links'.", "outputSchema": {}, "maxSteps": 30, "timeoutSeconds": 120 } ``` # Actor output Schema ## `results` (type: `string`): Dataset items for this run. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "url": "https://example.com", "task": "Find the main heading and any links on the page. Return them as a JSON object with fields 'heading' and 'links'.", "outputSchema": {}, "maxSteps": 30, "timeoutSeconds": 120, "proxyGeo": "" }; // Run the Actor and wait for it to finish const run = await client.actor("shelvick/stealth-browser-agent").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "url": "https://example.com", "task": "Find the main heading and any links on the page. Return them as a JSON object with fields 'heading' and 'links'.", "outputSchema": {}, "maxSteps": 30, "timeoutSeconds": 120, "proxyGeo": "", } # Run the Actor and wait for it to finish run = client.actor("shelvick/stealth-browser-agent").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "url": "https://example.com", "task": "Find the main heading and any links on the page. Return them as a JSON object with fields '\''heading'\'' and '\''links'\''.", "outputSchema": {}, "maxSteps": 30, "timeoutSeconds": 120, "proxyGeo": "" }' | apify call shelvick/stealth-browser-agent --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=shelvick/stealth-browser-agent", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Stealth Browser Agent", "description": "Stealth browser agent for bot-defended websites. Send a URL and a natural language task — the agent navigates, clicks, fills forms, and extracts structured results with anti-detection fingerprinting and residential proxy. Designed for AI agents that need to interact with defended sites.", "version": "0.0", "x-build-id": "bp8lQSF80fCngNyFc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/shelvick~stealth-browser-agent/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-shelvick-stealth-browser-agent", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/shelvick~stealth-browser-agent/runs": { "post": { "operationId": "runs-sync-shelvick-stealth-browser-agent", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/shelvick~stealth-browser-agent/run-sync": { "post": { "operationId": "run-sync-shelvick-stealth-browser-agent", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "url", "task" ], "properties": { "url": { "title": "Starting URL", "type": "string", "description": "The web page to start on. The agent navigates here first, then executes the task. Must be a public, unauthenticated page." }, "task": { "title": "Task", "type": "string", "description": "What to do on the page, in plain language. Can include interaction steps (click, fill, navigate) and extraction goals (find prices, collect links). The agent plans and executes actions to accomplish this task, then returns structured results." }, "outputSchema": { "title": "Output Schema", "type": "object", "description": "Optional JSON Schema describing the desired shape of the result object. When provided, the agent structures its final extraction to match this schema. When omitted, the agent returns a best-effort JSON object." }, "maxSteps": { "title": "Max Steps", "type": "integer", "description": "Maximum number of browser actions the agent may take. Safety cap to prevent runaway loops — the primary cost cap is maxTotalChargeUsd. Each tool call (click, type, navigate, extract, etc.) counts as one step.", "default": 30 }, "timeoutSeconds": { "title": "Timeout (seconds)", "type": "integer", "description": "Hard deadline for the entire task. If the agent hasn't finished by this time, it returns whatever it has with status 'timeout'.", "default": 120 }, "proxyGeo": { "title": "Proxy Country", "type": "string", "description": "ISO 3166-1 alpha-2 country code for geo-targeted browsing. Routes the browser through a residential proxy in this country. Leave empty for default routing." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```