Massive

Use Massive residential proxies with Notte sessions

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

• A Notte API key (get one here)
• A Massive account with proxy credentials — sign up at partners.joinmassive.com

Setup

1. Get your Massive credentials

Log in to your Massive dashboard and grab your proxy username and password. Then choose a protocol:

Protocol	Port	Use case
HTTP	65534	Recommended for most use cases
HTTPS	65535	For encrypted proxy connections
SOCKS5	65533	For 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