---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/stealth/get-past-bot-detection
markdown_url: https://steel.dev/docs/stealth/get-past-bot-detection.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Get past bot detection
description: Choose a setup for a site that blocks your session, based on what you see and on your plan, and check that it worked.
summary: Choose a setup for a site that blocks your session, based on what you see and on your plan, and check that it worked.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/stealth.md
related:
  - https://steel.dev/docs/stealth.md
  - https://steel.dev/docs/stealth/proxies.md
  - https://steel.dev/docs/stealth/dedicated-ips.md
  - https://steel.dev/docs/stealth/captcha-solving.md
  - https://steel.dev/docs/stealth/fingerprints.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Get past bot detection

When a site blocks your session, change one thing at a time, in this order: the IP address, the CAPTCHA, the fingerprint, and the browser. Each change costs more or changes more than the one before it, so stop at the first one that works. [How stealth works](https://steel.dev/docs/stealth) explains what sites check and why.

No setting gets past every site. A site can still block a session, ask for a login, or forbid automation in its terms.

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable, and install the Steel SDK and Playwright with `npm install steel-sdk playwright` or with `pip install steel-sdk playwright` in a [virtual environment](https://steel.dev/docs/reference/sdks/python#install).

## Choose a setup

Find what the site does to your session, and try the setup in that row. If you do not know what blocked you, [find out](https://steel.dev/docs/stealth/get-past-bot-detection#find-out-what-blocked-you) first.

| What you see | What to use | How to check that it worked |
| - | - | - |
| "Access denied", a `403`, or an empty page | A [Steel proxy](https://steel.dev/docs/stealth/proxies) (`useProxy`) | The page loads, and `proxySource` is `steel`. |
| Content for the wrong country | A Steel proxy [in that country](https://steel.dev/docs/stealth/proxies#target-a-location) (`geolocation`) | `https://steel.dev/practice/country` shows that country. |
| A new sign-in check in each session, or a site that allows only known addresses | A [dedicated IP](https://steel.dev/docs/stealth/dedicated-ips) | `https://steel.dev/practice/ip` shows an address from the dashboard's Network page. |
| A CAPTCHA, or `captcha_encountered` | [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving) (`solveCaptcha`) | The [CAPTCHA status](https://steel.dev/docs/stealth/captcha-solving#check-the-status) is `solved`. |
| A block after your code clicks or types | [Human-like input](https://steel.dev/docs/stealth/fingerprints#make-input-human-like) (`humanizeInteractions`) | Several runs end without `bot_detection_triggered`. |
| A block that stays even with a proxy and CAPTCHA solving | A [mobile device](https://steel.dev/docs/sessions/devices#emulate-a-mobile-device) (`deviceConfig`) | Several runs end without `bot_detection_triggered`. |
| A block that stays after all of these | [Stealth Browser](https://steel.dev/docs/stealth/stealth-browser) (`useStealthBrowser`) | `browserMode` is `stealth`, and several runs end without `bot_detection_triggered`. |

[What each plan includes](https://steel.dev/docs/platform/pricing#what-each-plan-includes) shows which plans have each setup. In every setup, leave Steel's [fingerprint](https://steel.dev/docs/stealth/fingerprints#how-fingerprints-are-set) on.

## Find out what blocked you

Run the task once with no stealth options, and read what Steel saw. When a session ends, Steel adds signals to it within a few seconds. Look for `bot_detection_triggered`, which marks a block or a challenge that the browser did not get past, and `captcha_encountered`, which marks a CAPTCHA. [Signals reference](https://steel.dev/docs/reference/signals) lists the others.

This program opens the page that blocks you, prints its title, releases the session, and prints the signals. Set `TARGET_URL` to that page's URL.

**TypeScript**

```ts file=check-site.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create({
  metadata: { check: "bot-detection", attempt: 1 },
});

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto(process.env.TARGET_URL!);
  console.log(`Title: ${await page.title()}`);
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

await new Promise((resolve) => setTimeout(resolve, 10000));
const { signals } = await client.sessions.retrieve(session.id);
console.log(`Signals: ${JSON.stringify(signals)}`);
console.log(`Recording: ${session.sessionViewerUrl}`);
```

**Python**

```python file=check_site.py
import os
import time

from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()
session = client.sessions.create(
    metadata={"check": "bot-detection", "attempt": 1},
)

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto(os.environ["TARGET_URL"])
        print(f"Title: {page.title()}")
        browser.close()
finally:
    client.sessions.release(session.id)

time.sleep(10)
signals = client.sessions.retrieve(session.id).signals
print(f"Signals: {signals}")
print(f"Recording: {session.session_viewer_url}")
```

Run the program:

**TypeScript**

```sh
npx tsx check-site.mts
```

**Python**

```sh
python check_site.py
```

The output of a blocked run looks like this:

**TypeScript**

```text nocopy
Title: Just a moment...
Signals: ["bot_detection_triggered"]
Recording: https://app.steel.dev/sessions/2f7b7701-6017-45cc-8138-e90aeb0610ae
```

**Python**

```text nocopy
Title: Just a moment...
Signals: ['bot_detection_triggered']
Recording: https://app.steel.dev/sessions/b9bceea9-c168-41e7-87c0-5cfce1110f6d
```

Open the recording URL to see the page that the browser saw. Do this even when the list of signals is empty, because signals do not catch every block.

Then find what you see in [Choose a setup](https://steel.dev/docs/stealth/get-past-bot-detection#choose-a-setup). The next sections add the most common setups to this program, in the order to try them: [a proxy](https://steel.dev/docs/stealth/get-past-bot-detection#add-a-proxy), [CAPTCHA solving](https://steel.dev/docs/stealth/get-past-bot-detection#solve-the-captcha) and [a mobile device](https://steel.dev/docs/stealth/get-past-bot-detection#try-a-mobile-device).

## Add a proxy

Many sites block data center IP addresses, and a session uses one by default. A Steel proxy gives it a residential address instead. Change the `create` call in the program:

**TypeScript**

```ts
const session = await client.sessions.create({
  useProxy: true,
  metadata: { check: "bot-detection", attempt: 2 },
});
```

**Python**

```python
session = client.sessions.create(
    use_proxy=True,
    metadata={"check": "bot-detection", "attempt": 2},
)
```

**Go**

```go
import "github.com/steel-dev/sdk/go/shared"

session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	UseProxy: steel.F[any](true),
	Metadata: steel.F(map[string]steel.SessionNewParamsMetadataUnion{
		"check":   shared.UnionString("bot-detection"),
		"attempt": shared.UnionFloat(2),
	}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        use_proxy: Some(serde_json::Value::Bool(true)),
        metadata: Some(std::collections::HashMap::from([
            (
                "check".to_owned(),
                steel_rs::SessionCreateParamsMetadata::String("bot-detection".to_owned()),
            ),
            (
                "attempt".to_owned(),
                steel_rs::SessionCreateParamsMetadata::Number(2.0),
            ),
        ])),
        ..Default::default()
    })
    .await?;
```

In Rust, this code needs `cargo add serde_json`.

On Launch, a Steel proxy needs a verified account. You verify it once, with $10 of paid credits. Until you verify it, `create` fails with `deposit_required`. See [Verify a Launch account](https://steel.dev/docs/platform/pricing#verify-a-launch-account).

If the site serves one country, target that country with `useProxy: { geolocation: { country: "DE" } }`. A Steel proxy also adds a bandwidth charge. To use a proxy that you run yourself, see [Proxies](https://steel.dev/docs/stealth/proxies). To keep one address from run to run, use a [dedicated IP](https://steel.dev/docs/stealth/dedicated-ips).

## Solve the CAPTCHA

A proxy makes CAPTCHAs less frequent, but it does not stop them. Set `solveCaptcha` to `true`, and Steel finds and solves CAPTCHAs on each page while your code waits. Keep the proxy:

**TypeScript**

```ts
const session = await client.sessions.create({
  useProxy: true,
  solveCaptcha: true,
  metadata: { check: "bot-detection", attempt: 3 },
});
```

**Python**

```python
session = client.sessions.create(
    use_proxy=True,
    solve_captcha=True,
    metadata={"check": "bot-detection", "attempt": 3},
)
```

**Go**

```go
import "github.com/steel-dev/sdk/go/shared"

session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	UseProxy:     steel.F[any](true),
	SolveCaptcha: steel.F(true),
	Metadata: steel.F(map[string]steel.SessionNewParamsMetadataUnion{
		"check":   shared.UnionString("bot-detection"),
		"attempt": shared.UnionFloat(3),
	}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        use_proxy: Some(serde_json::Value::Bool(true)),
        solve_captcha: Some(true),
        metadata: Some(std::collections::HashMap::from([
            (
                "check".to_owned(),
                steel_rs::SessionCreateParamsMetadata::String("bot-detection".to_owned()),
            ),
            (
                "attempt".to_owned(),
                steel_rs::SessionCreateParamsMetadata::Number(3.0),
            ),
        ])),
        ..Default::default()
    })
    .await?;
```

On Launch, CAPTCHA solving needs a verified account too, so an unverified account gets `deposit_required` here as well.

A solve takes time, so after `page.goto`, wait for an element that you need before the next action. Give the wait a timeout that leaves room for the solve. Each solve has a charge. Steel does not solve some kinds of challenge. [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving) lists them, and shows how to read each solve's status and how to solve only when you choose to.

## Try a mobile device

Steel gives each session a fingerprint that matches a real desktop browser, unless you set `userAgent` or start from a profile, as [Fingerprints](https://steel.dev/docs/stealth/fingerprints#how-fingerprints-are-set) explains. Do not turn it off. If a site still blocks the session, a mobile device gives it a different fingerprint, and many sites serve a simpler page to mobile devices.

**TypeScript**

```ts
const session = await client.sessions.create({
  useProxy: true,
  solveCaptcha: true,
  deviceConfig: { device: "mobile" },
  metadata: { check: "bot-detection", attempt: 4 },
});
```

**Python**

```python
session = client.sessions.create(
    use_proxy=True,
    solve_captcha=True,
    device_config={"device": "mobile"},
    metadata={"check": "bot-detection", "attempt": 4},
)
```

**Go**

```go
import "github.com/steel-dev/sdk/go/shared"

session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	UseProxy:     steel.F[any](true),
	SolveCaptcha: steel.F(true),
	DeviceConfig: steel.F(steel.SessionNewParamsDeviceConfig{
		Device: steel.F(steel.SessionNewParamsDeviceConfigDeviceMobile),
	}),
	Metadata: steel.F(map[string]steel.SessionNewParamsMetadataUnion{
		"check":   shared.UnionString("bot-detection"),
		"attempt": shared.UnionFloat(4),
	}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        use_proxy: Some(serde_json::Value::Bool(true)),
        solve_captcha: Some(true),
        device_config: Some(steel_rs::SessionCreateParamsDeviceConfig {
            device: Some(steel_rs::SessionCreateParamsDeviceConfigDevice::Mobile),
        }),
        metadata: Some(std::collections::HashMap::from([
            (
                "check".to_owned(),
                steel_rs::SessionCreateParamsMetadata::String("bot-detection".to_owned()),
            ),
            (
                "attempt".to_owned(),
                steel_rs::SessionCreateParamsMetadata::Number(4.0),
            ),
        ])),
        ..Default::default()
    })
    .await?;
```

A mobile session sets its own screen size. If you also pass `dimensions`, they must be at least 508 by 1074 pixels. To make the mouse move more like a person's, add `stealthConfig: { humanizeInteractions: true }`. [Fingerprints](https://steel.dev/docs/stealth/fingerprints) and [Set the device and viewport](https://steel.dev/docs/sessions/devices) have the other options.

On Enterprise, if the site still blocks the session, run it on [Stealth Browser](https://steel.dev/docs/stealth/stealth-browser), Steel's own Chromium fork. Add `useStealthBrowser` to `experimentalFeatures`, and keep the proxy and CAPTCHA solving.

If the site blocks every combination, a person can do the step in the live view. See [Hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human).

## Check the signals

One good run does not prove that a setting works. Run the task several times with the same settings, then compare the results. Each attempt in this guide has its own `attempt` value in the metadata, so you can list the sessions that were still blocked in one attempt:

**TypeScript**

```ts
for await (const session of client.sessions.list({
  metadata: { check: "bot-detection", attempt: "3" },
  signal: ["bot_detection_triggered"],
})) {
  console.log(session.id, session.signals);
}
```

**Python**

```python
for session in client.sessions.list(
    metadata={"check": "bot-detection", "attempt": "3"},
    signal=["bot_detection_triggered"],
):
    print(session.id, session.signals)
```

**Go**

```go
iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
	Metadata: steel.F(map[string]string{"check": "bot-detection", "attempt": "3"}),
	Signal:   steel.F([]steel.SessionListParamsSignal{steel.SessionListParamsSignalBotDetectionTriggered}),
})
for iter.Next() {
	session := iter.Current()
	fmt.Println(session.ID, session.Signals)
}
if err := iter.Err(); err != nil {
	return err
}
```

**Rust**

```rust
let sessions = client
    .sessions()
    .list_auto_paging(steel_rs::SessionListParams {
        metadata: Some(std::collections::HashMap::from([
            ("check".to_owned(), "bot-detection".to_owned()),
            ("attempt".to_owned(), "3".to_owned()),
        ])),
        signal: Some(vec![
            steel_rs::SessionListParamsSignal::BotDetectionTriggered,
        ]),
        ..Default::default()
    });
let mut sessions = std::pin::pin!(sessions);
while let Some(session) = futures_util::StreamExt::next(&mut sessions).await {
    let session = session?;
    println!("{} {:?}", session.id, session.signals);
}
```

In Rust, this code needs `cargo add futures-util`.

Steel stores metadata values as strings, so filter with `"3"`. The code prints each blocked session of that attempt with its signals. An empty result means that no session of the attempt carries the signal.

In production, keep the same check. Tag your sessions with metadata for the job or the site, and list the sessions that carry `bot_detection_triggered` or `captcha_encountered`. A rise in either one can mean that the site changed its checks. [Signals](https://steel.dev/docs/observability/signals) shows more ways to read them.

## Next steps

- [How stealth works](https://steel.dev/docs/stealth): See what each check looks at, and which Steel feature handles it.
- [Hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human): Let a person finish a check that the session cannot pass.
- [Debug a failed session](https://steel.dev/docs/observability/debug-a-failed-session): Find out why a session still failed, from its signals, recording and logs.
