> ## 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.
# Massive
> Use Massive residential proxies with Notte sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/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.
[Massive](https://www.joinmassive.com/) 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`](/features/sessions/proxies#custom-proxies) 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](https://console.notte.cc))
* A Massive account with proxy credentials — sign up at [partners.joinmassive.com](https://partners.joinmassive.com/create-account)
## Setup
### 1. Get your Massive credentials
Log in to your [Massive dashboard](https://partners.joinmassive.com) 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
```bash theme={null}
pip install notte-sdk
```
### 3. Connect Massive to your Notte session
Pass your Massive proxy as an `ExternalProxy` when creating a session:
{/* @sniptest testers/integrations/massive_basic.py */}
```python massive_basic.py theme={null}
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:
{/* @sniptest testers/integrations/massive_geo.py */}
```python massive_geo.py theme={null}
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](https://www.joinmassive.com/guides/notte).
## Complete example
A production-ready script using Massive proxies with a Notte agent:
{/* @sniptest testers/integrations/massive_complete.py */}
```python massive_complete.py theme={null}
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:
```bash theme={null}
MASSIVE_USERNAME=your-massive-username
MASSIVE_PASSWORD=your-massive-password
NOTTE_API_KEY=your-notte-api-key
```