Anti-Detection Playbook

How to avoid CAPTCHAs and bot detection in Notte Sessions

Resolving Bot Detection Issues#

Common Bot Detection Challenges:

• Accessing e-commerce sites with anti-bot measures
• Scraping content from news or social media platforms
• Interacting with banking or financial websites
• Accessing sites with geographic restrictions

Stealth Configuration Strategies#

1. Proxy Configuration#

Proxies are one of the most effective ways to bypass bot detection.

from notte_sdk import NotteClient
 
client = NotteClient()
 
# Start a session with built-in proxies
with client.Session(proxies=True) as session:
    _ = session.observe(url="https://www.notte.cc/")

For sites with geographic restrictions, use proxies from specific countries:

from notte_sdk.types import NotteProxy
 
proxies = NotteProxy.from_country("fr")

2. Browser Type Selection#

Different browsers have varying levels of detection resistance:

from typing import Literal
from notte_sdk import NotteClient
 
client = NotteClient()
 
BrowserType = Literal["chromium", "chrome"]
browsers: list[BrowserType] = ["chromium", "chrome"]
for browser in browsers:
    with client.Session(browser_type=browser, proxies=True, solve_captchas=True) as session:
        result = session.observe(url="https://example.com")

Tip: chromium is the default browser type but is the most easily detected.

3. CAPTCHA Solving#

with client.Session(solve_captchas=True, open_viewer=True) as session:
    agent = client.Agent(session=session, max_steps=5)
    resp = agent.run(
        task=("Try to solve the CAPTCHA using internal tools. If you fail, try to solve it manually."),
        url="https://www.google.com/recaptcha/api2/demo",
    )

Warning: Not all CAPTCHA types are supported. Some complex CAPTCHAs may still require manual intervention.

Complete Stealth Configuration Example#

with client.Session(
    solve_captchas=True,
    proxies="us",
    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    viewport_width=1920,
    viewport_height=1080,
) as session:
    result = session.observe(url="https://example.com")

Troubleshooting Tips#

1. Start Simple. Try proxies=True first, add solve_captchas=True if needed, experiment with different browser_type values, add a custom user_agent if still detected.
2. Test Incrementally. Test each configuration change individually to identify what works.
3. Monitor for Patterns. E-commerce sites often respond well to residential proxies; social media sites may require specific user agents; banking sites may need country-specific proxies.

Best Practices#

1. Rotate Configurations: Don't rely on a single configuration, it makes it easier to track you.
2. Monitor Success Rates: Verify which configurations work best for different site types.
3. Respect Rate Limits: Implement delays between requests to avoid triggering rate limiting.
4. Keep Configurations Updated: Bot detection methods evolve, so regularly test and update your configurations.

Back to overview