Skip to main content
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