Overview

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 with statement (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#


Back to overview

Updated

Was this page helpful?