Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.notte.cc/llms.txt

Use this file to discover all available pages before exploring further.

STOP. Do not read past this section until you have read and followed /quickstart.md.Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live observe() call, CLI notte page observe output, or generated workflow code. Guessed browser targets fail on real pages.Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with notte sessions workflow-code before using SDK docs or SDK code.SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.

​
Resolving Bot Detection Issues

Bot detection is a common challenge for web agents. This guide provides strategies to bypass these detection mechanisms using Notte’s stealth configuration options. 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. Different proxy configurations can help you appear as legitimate traffic from various locations.

​
Using Default Proxies

Enable Notte’s built-in residential proxies for better anonymity:
default_proxy.py
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/")

​
Country-Specific Proxies

For sites with geographic restrictions, use proxies from specific countries:
country_proxy.py
from notte_sdk.types import NotteProxy

proxies = NotteProxy.from_country("fr")

​
2. Browser Type Selection

Different browsers have varying levels of detection resistance. Experiment with different browser types for your specific use case:
browser_type_selection.py
from typing import Literal

from notte_sdk import NotteClient

client = NotteClient()

# Try different browser types
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")
        print(f"Success with {browser}")
chromium is the default browser type but is the most easily detected.

​
3. CAPTCHA Solving

Enable automatic CAPTCHA solving for sites that use these challenges:
solve_captchas.py
from notte_sdk import NotteClient

client = NotteClient()
with client.Session(solve_captchas=True, open_viewer=True) as session:
    # Navigate to a page with a CAPTCHA
    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",
    )
Not all CAPTCHA types are supported. Some complex CAPTCHAs may still require manual intervention.

​
Complete Stealth Configuration Example

Here’s a comprehensive example combining all stealth techniques:
stealth_configuration.py
from notte_sdk import NotteClient

client = NotteClient()

# Example stealth configuration
# this is just one possible configuration, with an obvious fingerprint
# rotating those values will raise your chances
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")
    print("Success with fallback configuration")

​
Troubleshooting Tips

  1. Start Simple. Begin with basic configurations and gradually add complexity:
    • Try proxies=True first
    • Add solve_captchas=True if needed
    • Experiment with different browser_type values
    • Add custom user_agent if still detected
  2. Test Incrementally. Test each configuration change individually to identify what works:
  3. Monitor for Patterns. Keep track of which configurations work for different types of sites:
    • 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