Browser Sessions
Cloud-hosted browser instances for automation
Every operation in Notte, whether you're running an AI agent, scraping data, or automating a workflow, happens within a session.
Quick Start#
Create a session and start automating:
from playwright.sync_api import sync_playwright
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(open_viewer=True) as session:
cdp_url = session.cdp_url()
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(cdp_url)
page = browser.contexts[0].pages[0]
page.goto("https://www.google.com")
page.screenshot(path="screenshot.png")import { chromium } from 'playwright-core';
import { NotteClient } from 'notte-sdk';
const notte = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await notte.Session({ open_viewer: true }).use(async (session) => {
const status = await session.status();
const cdpUrl = status.cdp_url;
const browser = await chromium.connectOverCDP(cdpUrl);
try {
const page = browser.contexts()[0].pages()[0];
await page.goto('https://news.ycombinator.com');
const topStories = await page.locator('.titleline > a').allInnerTexts();
console.log('Top 5 Hacker News stories:');
topStories.slice(0, 5).forEach((title, index) => {
console.log(`${index + 1}. ${title}`);
});
} finally {
await browser.close();
}
});Tip: We strongly recommend using the
withstatement (context manager) to ensure sessions are automatically stopped when done. This prevents orphaned sessions and unexpected costs.
Core Operations#
Sessions provide three methods for interacting with the browser:
| Method | Purpose |
|---|---|
observe() |
Get the current page state and available actions |
execute() |
Perform an action on the page |
scrape() |
Extract structured data from the page |
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as page:
url = "https://www.linkedin.com/"
# observe page and take a step
page.execute(type="goto", url=url)
actions = page.observe(instructions="click 'jobs'")
res = page.execute(actions[0])
print(res.message)
# another one
actions = page.observe(instructions="dismiss the sign in check")
res = page.execute(actions[0])
print(res.message)Session Capabilities#
Sessions come with powerful built-in capabilities:
-
Proxies — Route traffic through residential proxies for geo-targeting
-
Captcha Solving — Automatically solve reCAPTCHA and hCaptcha
-
Stealth Mode — Evade bot detection with fingerprint randomization
-
Recordings — Record sessions for debugging and replay
-
Live View — Watch sessions execute in real-time
-
Browser Profiles — Persist browser state across sessions
Next Steps#
-
Session Lifecycle — Create, manage, and stop sessions
-
Session Configuration — All configuration options
-
Browser Controls — Complete action reference
-
Connect with Playwright — Use Playwright via CDP