# Stealth Browser Agent — AI Browser Automation (`shelvick/stealth-browser-agent`) Actor

Stealth web automation agent that bypasses bot detection on defended websites. Send a URL and a plain-language task; the AI browser agent navigates, clicks, fills and submits forms, and automates multi-step flows, returning structured JSON — with anti-detection fingerprinting and residential proxy.

- **URL**: https://apify.com/shelvick/stealth-browser-agent.md
- **Developed by:** [Scott Helvick](https://apify.com/shelvick) (community)
- **Categories:** AI, Agents, Automation
- **Stats:** 54 total users, 30 monthly users, 100.0% runs succeeded, 0 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 a hosted stealth browser that bypasses bot detection — send a URL and a natural-language task, and an LLM-driven browser navigates, clicks, types, fills and submits forms, and automates multi-step flows, extracting 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. |
| `modelTier` | string | No | `basic` | How much reasoning the agent applies when planning each step. `basic` handles ordinary navigation, form filling and extraction. `premium` plans with deeper reasoning for complex, ambiguous or heavily defended multi-step flows, at a higher per-step rate. |
| `maxSteps` | integer | No | `100` | Hard cap on billable steps in one run (1–100). The primary cost cap is `maxTotalChargeUsd` — the agent stops when the next step would exceed your budget — so lower `maxSteps` only if you want a tighter runaway guard than your budget already gives you. |
| `timeoutSeconds` | integer | No | `270` | Budget for the agent's work on the page, starting when the browser is ready. Browser bring-up (typically 10–90 s) does not count against it. |
| `stepTimeoutSeconds` | integer | No | `45` | Per-action stall guard. Protects your budget from a single hung browser action burning `maxTotalChargeUsd`. A stalled step is logged and the agent tries a different approach. |
| `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`, `budget_exhausted`, or `max_steps_reached` |
| `result` | object | Structured extraction — shaped by `outputSchema` if provided |
| `resultComplete` | boolean | `true` only when `status` is `completed`. When `false`, `result` is either empty or a best-effort partial from a capped run — check this before trusting `result` as a full answer |
| `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) |
| `errorClass` | string | Machine-routable failure class; `null` on success |

**Failure taxonomy:** `source_error` is a temporary target-site problem and is retryable; `source_walled` is an access challenge and may succeed on retry; `budget_exhausted` is retryable with a larger budget. `no_content`, `malformed_input`, and `agent_error` require changing the page, input, or task rather than retrying unchanged.

### 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 things move the per-step rate:

- **Capability tier** (`modelTier`) — `basic` is the default and the cheaper rate; `premium` applies deeper reasoning to each planning decision and costs more per step. If you never set `modelTier`, you stay on the basic rate.
- **Proxy routing** (`proxyGeo`) — setting a country routes the browser through a residential proxy, and the higher per-step rate for that covers the residential bandwidth.

That gives four per-step rates: basic and premium, each with and without proxy.

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 `maxTotalChargeUsd` — the agent checks the remaining budget before each step and stops if the next step would push spend past your cap. A single hung browser action can't burn the rest of the budget either, thanks to the per-step stall guard (`stepTimeoutSeconds`). `maxSteps` caps billable steps at 100 per run on top of those two.

Premium costs meaningfully more per step, so it is worth reaching for when a task is genuinely hard — ambiguous multi-page flows, heavily defended sites, decisions that depend on reading the page carefully — and worth leaving alone when it isn't.

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)
- `budget_exhausted` — `maxTotalChargeUsd` would be exceeded by the next step. Raise the budget to continue further.
- `timeout` — the agent-work budget (`timeoutSeconds`) was reached after browser bring-up. Partial results may be present in `result`.
- `max_steps_reached` — the run hit its `maxSteps` cap (100 by default) before finishing. Raise `maxSteps` if you lowered it; at 100 the task needs splitting into smaller runs.

**Partial results on capped runs.** When a run hits `maxSteps` or `maxTotalChargeUsd` after collecting data, the agent makes one final synthesis pass over what it already gathered and delivers it in `result` as an honest partial: fields it has no data for are `null`, `resultComplete` is `false`, and the status keeps the cap value — a partial is never presented as a completed run. The synthesis pass itself is never charged. Use the partial as-is, or re-run with a higher cap for the full answer; the step-by-step transcript is available at `stepTranscriptUrl` either way.

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:**

- The stealth browser session takes ~30-90 seconds to launch and load the target before the first step runs. Hardened sites take the longest — heavily defended pages can push bring-up toward two minutes.
- Once the browser is ready, steps after that typically run a few seconds each (planning plus the browser action).
- A simple 1-2 step extraction usually completes in about a minute end to end; multi-step interactions and multi-page flows scale up from there.
- Residential proxy routing adds a little latency per navigation.

**Telemetry:** to improve reliability and coverage, this Actor reports anonymous usage metrics and diagnostic events to the developer — run outcome counts, the target site's hostname, and, only when something goes wrong, the relevant input fields. No account identifiers are collected, and telemetry never affects a run.

### 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. The agent enforces this as a real bound — it stops before charging a step that would push spend past your cap (status: `budget_exhausted`). No need to also fiddle with step or time caps for cost control; the budget is the ceiling.

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

### Related Actors

| Actor | Use it when |
|---|---|
| [Smart Page Fetcher](https://apify.com/shelvick/smart-page-fetcher) | you only need page content fetched — no interaction with the page |
| [Structured Data Extractor — URL to JSON](https://apify.com/shelvick/structured-extractor) | you have the URLs already and just need schema-validated JSON out of them |

***

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

## `modelTier` (type: `string`):

How much reasoning the agent applies when planning each step. 'basic' handles ordinary navigation, form filling and extraction, and is the right default for most tasks. 'premium' plans with deeper reasoning for complex, ambiguous or heavily defended multi-step flows, and is charged at a higher per-step rate — see the Pricing tab. Leave unset for basic.

## `maxSteps` (type: `integer`):

Hard cap on billable steps in one run, between 1 and 100. Defaults to 100. The primary cost cap is still maxTotalChargeUsd — the agent stops automatically when the next step would exceed your budget — so lower maxSteps only if you want a tighter runaway guard than your budget already provides.

## `timeoutSeconds` (type: `integer`):

Budget for the agent's work on the page, starting when the browser is ready. Browser bring-up (typically 10–90 s) does not count against it. Maximum 900 s. The agent records 'timeout' status and returns what it has.

## `stepTimeoutSeconds` (type: `integer`):

Per-action timeout. Protects your budget from a single hung browser action (frozen page, network stuck) burning maxTotalChargeUsd. A stalled step is logged as an error and the agent tries a different approach. Default 45 s.

## `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": {},
  "modelTier": "basic",
  "maxSteps": 100,
  "timeoutSeconds": 270,
  "stepTimeoutSeconds": 45
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset items for this run.

## `screenshot` (type: `string`):

Full-page PNG of the final page state, written when the agent captures one (every successful run). Also linked from the dataset record's screenshotUrl.

## `step_transcript` (type: `string`):

Capped full step transcript (JSON), written on incomplete runs after at least one step. Also linked from the dataset record's stepTranscriptUrl.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_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": {},
    "modelTier": "basic",
    "maxSteps": 100,
    "timeoutSeconds": 270,
    "stepTimeoutSeconds": 45,
    "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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# 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": {},
    "modelTier": "basic",
    "maxSteps": 100,
    "timeoutSeconds": 270,
    "stepTimeoutSeconds": 45,
    "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(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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": {},
  "modelTier": "basic",
  "maxSteps": 100,
  "timeoutSeconds": 270,
  "stepTimeoutSeconds": 45,
  "proxyGeo": ""
}' |
apify call shelvick/stealth-browser-agent --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,shelvick/stealth-browser-agent"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5N7h2iK0C5d4Zd47R/builds/999H0UogubUMS8di4/openapi.json