Session Lifecycle

Manage the lifecycle of your Notte browser sessions

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:

• authenticating - Session was started with Managed Auth connections and login is still in progress
• 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 hit its idle timeout or maximum duration

Creating a Session

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

Python - Context Manager

# 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()}")

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:

Python

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"Idle timeout: {status.idle_timeout_minutes} minutes")
    print(f"Max duration: {status.max_duration_minutes} minutes")
    print(f"Duration: {status.duration}")

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

session_id · string

Unique identifier for the session

status · string

Current status: authenticating, active, closed, error, or timed_out

created_at · datetime

Session creation timestamp

closed_at · datetime | None

Session closure timestamp (None if still active)

last_accessed_at · datetime

Last operation timestamp

idle_timeout_minutes · integer

Idle timeout in minutes. The session closes after this long without any operation.

max_duration_minutes · integer

Maximum session lifetime in minutes, regardless of activity

close_reason · string | None

Why the session closed: manual, idle_timeout, max_duration, error, or unknown (None while active)

duration · timedelta

Total session duration

Listing Sessions

Query all your active sessions:

Python

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:

Python

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")

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:

Python

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,
        idle_timeout_minutes=5,
        max_duration_minutes=30,
        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:

Python

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:

Python - Automatic Cleanup

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.

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:

context_manager.py

from notte_sdk import NotteClient

client = NotteClient()

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

2. Set Appropriate Timeouts

Sessions have two limits:

• idle_timeout_minutes (default 3, max 30) - closes the session after this long without any operation. Each operation resets it.
• max_duration_minutes (default 15, max 1440) - closes the session after this long, regardless of activity.

The idle timeout cannot exceed the maximum duration, so raise max_duration_minutes first for long workflows. Set the idle timeout to cover the longest pause between operations, for example while an agent thinks or a page loads.

timeout_example.py

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

3. Monitor Session State

Check session status before long-running operations:

monitor_state.py

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

    # Continue with operations
    pass

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

Session Lifecycle Diagram

┌─────────────────────────────────────────────────────────┐
│ 1. CREATE                                               │
│    session = client.Session(idle_timeout_minutes=5)     │
│    Status: Not started (response = None)                │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│ 2. START                                                │
│    with session: / session.start()                      │
│    Status: active                                       │
│    - Creates remote browser                             │
│    - Opens viewer if open_viewer=True                   │
│    - Loads cookies from cookie_file                     │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│ 3. ACTIVE OPERATIONS                                    │
│    - session.execute(action)                            │
│    - session.observe()                                  │
│    - session.scrape()                                   │
│    - session.page.goto(url)                             │
│    Status: active                                       │
└────────────────────┬────────────────────────────────────┘
                     │
            ┌────────┴────────┐
            ▼                 ▼
┌──────────────────┐  ┌──────────────────┐
│ 4a. TIMEOUT      │  │ 4b. STOP         │
│ idle or max dur. │  │ session.stop()   │
│ Status: timed_out│  │ Status: closed   │
└──────────────────┘  └──────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│ 5. CLEANUP                                              │
│    - Saves cookies to cookie_file                       │
│    - Closes Playwright connections                      │
│    - Releases cloud resources                           │
└─────────────────────────────────────────────────────────┘

Next Steps

Session Configuration

Configure sessions with advanced options

Recordings

Record and replay session activity

Live View

Watch sessions in real-time

Cookies

Persist authentication across sessions