Session Lifecycle

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Every Notte session follows a predictable lifecycle from creation to termination. Understanding this lifecycle helps you build reliable automation workflows and manage resources effectively.

Session States

Sessions transition through these states:

active - Session is running and ready to accept operations
closed - Session has been terminated normally
error - Session encountered an error and terminated unexpectedly
timed_out - Session exceeded its timeout duration

Creating a Session

Create a new session using the context manager pattern (recommended):

# Recommended: Use context manager for automatic cleanup
with client.Session(viewport_width=1920, viewport_height=1080) as session:
    print(f"Session {session.session_id} is active")

    # Access Playwright page
    page = session.page
    page.goto("https://example.com")
    print(f"Page title: {page.title()}")

// Recommended: Use .use() for automatic cleanup.
await client
  .Session({ viewport_width: 1920, viewport_height: 1080 })
  .use(async (session) => {
    console.log(`Session ${session.getId()} is active`);

    // Access the session’s Playwright page.
    status = await session.status();
    const page = await session.page();
    await page.goto('https://example.com');
    title = await page.title();
    console.log(`Page title: ${title}`);
  });
// Automatically stopped here.

session = client.Session()
session.start()
try:
    print(f"Session {session.session_id} is active")
    status = session.status()
    if status.status != "active":
        raise RuntimeError("Session is not active")
    page = session.page
    page.goto("https://example.com")
    title = page.title()
finally:
    # Always stop the session
    session.stop()

const session = client.Session();
await session.start();
try {
  console.log(`Session ${session.getId()} is active`);
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
  const page = await session.page();
  await page.goto('https://example.com');
  title = await page.title();
} finally {
  // Always stop the session
  await session.stop();
}

Use Python’s with statement or TypeScript’s session.use() to stop sessions even if errors occur.

Getting Session Details

Retrieve current information about your session:

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Get full session status
    status = session.status()

    print(f"Session ID: {status.session_id}")
    print(f"Status: {status.status}")
    print(f"Created at: {status.created_at}")
    print(f"Last accessed: {status.last_accessed_at}")
    print(f"Timeout: {status.timeout_minutes} minutes")
    print(f"Duration: {status.duration}")

    # Get CDP URL for external connections
    cdp_url = session.cdp_url()
    print(f"CDP WebSocket: {cdp_url}")

string

Unique identifier for the session

string

Current status: active, closed, error, or timed_out

datetime

Session creation timestamp

datetime | None

Session closure timestamp (None if still active)

datetime

Last operation timestamp

integer

Session timeout in minutes

timedelta

Total session duration

Listing Sessions

Query all your active sessions:

from notte_sdk import NotteClient

client = NotteClient()

# List all sessions
sessions = client.sessions.list()
print(f"Total sessions: {len(sessions)}")

for session in sessions:
    print(f"- {session.session_id} ({session.status})")
    print(f"  Created: {session.created_at}")
    print(f"  Duration: {session.duration}")

# Filter by status
active_sessions = client.sessions.list(status="active")
print(f"Active sessions: {len(active_sessions)}")

Stopping a Session

Sessions are automatically stopped when using the context manager, but you can also stop them manually:

session = client.Session()
session.start()
try:
    status = session.status()
    if status.status != "active":
        raise RuntimeError("Session is not active")
finally:
    session.stop()
print("Session stopped successfully")

const session = client.Session();
await session.start();
try {
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
} finally {
  await session.stop();
}
console.log('Session stopped successfully');

Stopping a session is idempotent - you can safely call it multiple times without errors.

Complete Lifecycle Example

Here’s a complete example demonstrating best practices for session management:

import time

from notte_sdk import NotteClient

client = NotteClient()


def run_automation():
    # 1. Create session with configuration
    print("Creating session...")

    with client.Session(
        open_viewer=True,
        timeout_minutes=10,
        cookie_file="cookies.json",  # Auto-load/save cookies
    ) as session:
        print(f"Session created: {session.session_id}")
        print("Live viewer opened in browser")

        # 2. Access Playwright page
        page = session.page

        # 3. Use the session
        print("Navigating to example.com...")
        page.goto("https://example.com")

        title = page.title()
        print(f"Page title: {title}")

        # Take a screenshot
        page.screenshot(path="screenshot.png")
        print("Screenshot saved")

        # Wait before closing
        time.sleep(3)

        # Cookies automatically saved to cookies.json
        print("Session will be stopped and cookies saved...")

    # Session automatically stopped here
    print("Session stopped successfully")


if __name__ == "__main__":
    run_automation()

Connecting to Existing Sessions

You can reconnect to an existing session using its session_id:

from notte_sdk import NotteClient

client = NotteClient()

# Connect to existing session
session_id = "550e8400-e29b-41d4-a716-446655440000"

with client.Session(session_id) as session:
    print(f"Connected to session: {session.session_id}")

    # Get current status
    status = session.status()
    print(f"Session status: {status.status}")

    # Continue using the session
    page = session.page
    page.goto("https://example.com")

Error Handling

The context manager automatically handles cleanup, even when errors occur:

session = client.Session()
try:
    with session:
        session_id = session.session_id
        session.page.goto("https://example.com")
        raise ValueError("Example automation failure")
except ValueError as error:
    if str(error) != "Example automation failure":
        raise
    error_message = str(error)
    print(f"Automation failed: {error_message}")
# Cleanup happens even when automation raises.

const session = client.Session();
const expectedError = new Error('Example automation failure');
try {
  await session.use(async () => {
    sessionId = session.getId();
    const status = await session.status();
    const page = await session.page();
    await page.goto('https://example.com');
    throw expectedError;
  });
} catch (error) {
  if (error !== expectedError) throw error;
  errorMessage = expectedError.message;
  console.log(`Automation failed: ${errorMessage}`);
}
// Cleanup happens even when automation throws.

session = client.Session()
try:
    session.start()
    try:
        session_id = session.session_id
        session.page.goto("https://example.com")
        raise ValueError("Example automation failure")
    finally:
        session.stop()
except ValueError as error:
    if str(error) != "Example automation failure":
        raise
    error_message = str(error)
    print(f"Automation failed: {error_message}")
# Cleanup happens even when automation raises.

const session = client.Session();
const expectedError = new Error('Example automation failure');
try {
  await session.start();
  try {
    sessionId = session.getId();
    const status = await session.status();
    const page = await session.page();
    await page.goto('https://example.com');
    throw expectedError;
  } finally {
    await session.stop();
  }
} catch (error) {
  if (error !== expectedError) throw error;
  errorMessage = expectedError.message;
  console.log(`Automation failed: ${errorMessage}`);
}
// Cleanup happens even when automation throws.

Best Practices

Follow these patterns to build reliable, cost-effective automation:

1. Always Use Context Managers

Python’s with statement and TypeScript’s use() callback guarantee cleanup:

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(idle_timeout_minutes=2) as session:
    print(session.session_id)
# Automatically stopped here

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

await client.Session({ idle_timeout_minutes: 2 }).use(async (session) => {
  console.log(session.getId());
});
// Automatically stopped here, including when the callback throws.

2. Set Appropriate Timeouts

Match timeout to task duration with a buffer for delays:

Quick tasks: 3-5 minutes (default is 3)
Data scraping: 10-15 minutes
Long workflows: 20-30 minutes

with client.Session(idle_timeout_minutes=15) as session:
    # Complex automation
    pass

const session = client.Session({ idle_timeout_minutes: 15 });
await session.use(async () => {
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
  console.log(`Status: ${status.status}`);
});
// Automatically stopped here.

3. Monitor Session State

Check session status before long-running operations:

with client.Session() as session:
    status = session.status()
    if status.status != "active":
        raise Exception("Session is no longer active")

    # Continue with operations
    pass

const session = client.Session();
await session.use(async () => {
  status = await session.status();
  if (status.status !== 'active') throw new Error('Session is not active');
  console.log(`Status: ${status.status}`);
});
// Automatically stopped here.

4. Handle Cleanup Gracefully

Even with context managers, handle interrupts:

handle_interrupts.py

import signal
import sys

from notte_sdk import NotteClient

client = NotteClient()


def signal_handler(sig, frame):
    print("Interrupt received, cleaning up...")
    sys.exit(0)


signal.signal(signal.SIGINT, signal_handler)

with client.Session() as session:
    # Your automation
    pass