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.
Notte x Massive integration
Massive is a residential proxy provider offering ethically-sourced IPs across 195+ countries. If you have a Massive account (or are considering one), you can plug their proxies directly into your Notte sessions using the ExternalProxy type. This is useful when you need residential IP rotation, geo-targeted traffic, or want to route your browser automation through a dedicated proxy provider.

​
Prerequisites

​
Setup

​
1. Get your Massive credentials

Log in to your Massive dashboard and grab your proxy username and password. Then choose a protocol:
ProtocolPortUse case
HTTP65534Recommended for most use cases
HTTPS65535For encrypted proxy connections
SOCKS565533For advanced routing needs

​
2. Install the Notte SDK

pip install notte-sdk

​
3. Connect Massive to your Notte session

Pass your Massive proxy as an ExternalProxy when creating a session:
massive_basic.py
from notte_sdk import NotteClient
from notte_sdk.types import ExternalProxy, ProxySettings

client = NotteClient()

# Configure Massive proxy
massive_proxy = ExternalProxy(
    server="http://network.joinmassive.com:65534",
    username="your-username",
    password="your-password",
)

# Create a session routed through Massive
proxies: list[ProxySettings] = [massive_proxy]
with client.Session(proxies=proxies) as session:
    session.observe(url="https://example.com")
That’s it — your session traffic now routes through Massive’s residential network.

​
Geo and device targeting

Massive supports geographic and device-type targeting by appending parameters to your username string. You can target by country, state, city, device type, or any combination:
massive_geo.py
from notte_sdk.types import ExternalProxy

# Target a specific country
us_proxy = ExternalProxy(
    server="http://network.joinmassive.com:65534",
    username="your-username-country-US",
    password="your-password",
)

# Target a specific state
ca_proxy = ExternalProxy(
    server="http://network.joinmassive.com:65534",
    username="your-username-country-US-subdivision-CA",
    password="your-password",
)

# Target a specific city
sf_proxy = ExternalProxy(
    server="http://network.joinmassive.com:65534",
    username="your-username-country-US-subdivision-CA-city-San Francisco",
    password="your-password",
)

# Target mobile devices
mobile_proxy = ExternalProxy(
    server="http://network.joinmassive.com:65534",
    username="your-username-device-mobile",
    password="your-password",
)

# Combine geo + device targeting
combined_proxy = ExternalProxy(
    server="http://network.joinmassive.com:65534",
    username="your-username-country-US-subdivision-NY-city-New York-device-mobile",
    password="your-password",
)
See the full list of targeting parameters in the Massive guide for Notte.

​
Complete example

A production-ready script using Massive proxies with a Notte agent:
massive_complete.py
import os

from dotenv import load_dotenv
from notte_sdk import NotteClient
from notte_sdk.types import ExternalProxy, ProxySettings

load_dotenv()


def main():
    massive_username = os.getenv("MASSIVE_USERNAME")
    massive_password = os.getenv("MASSIVE_PASSWORD")

    client = NotteClient()

    # Configure Massive proxy with US targeting
    massive_proxy = ExternalProxy(
        server="http://network.joinmassive.com:65534",
        username=f"{massive_username}-country-US",
        password=massive_password,
    )

    # Create a session with Massive proxy
    proxies: list[ProxySettings] = [massive_proxy]
    with client.Session(proxies=proxies) as session:
        # Run an agent task through the proxied session
        agent = client.Agent(session=session, max_steps=10)
        result = agent.run(task="extract pricing information from https://www.notte.cc")
        print(f"Task completed: {result.answer}")


if __name__ == "__main__":
    main()
Set the following environment variables in your .env file: 
MASSIVE_USERNAME=your-massive-username
MASSIVE_PASSWORD=your-massive-password
NOTTE_API_KEY=your-notte-api-key