> ## 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.
# Browser Sessions
> Cloud-hosted browser instances for automation
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.
Sessions are isolated browser instances running in the cloud that you can control programmatically. Think of them as headless Chrome browsers, but managed, scalable, and equipped with anti-detection, proxies, and captcha solving out of the box.
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:
```python Python theme={null}
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")
```
```javascript JavaScript theme={null}
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;
if (!cdpUrl) {
throw new Error('Session did not return a 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();
}
});
```
We strongly recommend using the `with` statement (context manager) to ensure sessions are automatically stopped when done. This prevents orphaned sessions and unexpected costs. See [Session Lifecycle](/features/sessions/lifecycle) for manual management options.
## 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 |
```python Python theme={null}
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)
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await client.Session().use(async (page) => {
const url = 'https://www.linkedin.com/';
// Observe page and take a step
await page.execute({ type: 'goto', url });
let actions = await page.observe({ instructions: "click 'jobs'" });
let result = await page.execute(actions[0]);
console.log(result.message);
// Another one
actions = await page.observe({ instructions: 'dismiss the sign in check' });
result = await page.execute(actions[0]);
console.log(result.message);
});
```
## Session Capabilities
Sessions come with powerful built-in capabilities:
Route traffic through residential proxies for geo-targeting
Automatically solve reCAPTCHA and hCaptcha
Evade bot detection with fingerprint randomization
Record sessions for debugging and replay
Watch sessions execute in real-time
Persist browser state across sessions
## Next Steps
Create, manage, and stop sessions
All configuration options
Complete action reference
Use Playwright via CDP