Browser Profiles

Persist browser state across sessions

Profiles let you save and reuse browser state—including cookies, local storage, session storage, and cache—across multiple sessions. This is useful for maintaining login states, preserving user preferences, or building realistic multi-session workflows.

How Profiles Work

A profile is a saved snapshot of a browser’s user data directory. By default, each Notte session uses a fresh browser state to ensure isolation.

When you create a profile and use it in a session with persist=True, Notte saves that session’s browser state. You can then attach the profile to future sessions to restore the saved state.

Create a Profile

Create a profile to store browser state. Optionally, give it a name to keep track of different profiles:

create_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Create a profile with optional name
profile = client.profiles.create(name="my-profile")

print(f"Profile created: {profile.profile_id}")
print(f"Profile name: {profile.name}")

Use a Profile in a Session

Attach a profile to a session to load saved browser state:

use_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Use an existing profile in a session
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
    # Session loads saved browser state from the profile
    session.execute(type="goto", url="https://example.com")

Persist Changes

The persist parameter controls whether session changes are saved back to the profile:

• True - Save browser state to the profile when the session ends
• False (default) - Use the profile as read-only; don’t save changes

Set persist=True the first time you use a new profile to save the initial browser state. After that, you can use persist=False to reuse the profile without modifying it.

Profile Login Example

Step 1: Login and Save to Profile

First, create a profile and perform a login. When the session ends with persist=True, all cookies and browser state are saved to the profile:

persist_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Create a new profile
profile = client.profiles.create(name="github-login")

# Use profile with persist=True to save browser state
with client.Session(profile={"id": profile.profile_id, "persist": True}) as session:
    # Navigate and perform login
    session.execute(type="goto", url="https://github.com/login")
    session.execute(type="fill", selector='input[name="login"]', value="username")
    session.execute(type="fill", selector='input[name="password"]', value="password")
    session.execute(type="click", selector='input[type="submit"]')
    # Browser state is saved to profile when session ends

Step 2: Reuse the Saved Profile

Use the saved profile in a new session. The browser automatically loads the saved state, so you’re already authenticated:

reuse_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Reuse a previously saved profile (read-only)
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
    # Navigate directly - already authenticated!
    session.execute(type="goto", url="https://github.com")

    # Perform actions as logged-in user
    obs = session.observe()
    print(f"Page title: {obs.metadata.title}")

What happens:

1. A new session is created using the same profile ID
2. The browser loads saved cookies and state from the profile
3. You navigate directly without needing to log in again
4. The session picks up right where the previous one left off

This pattern is useful for:

• Avoiding repeated logins across automation runs
• Testing authenticated user flows
• Managing multiple accounts with separate profiles
• Maintaining session state over time

Using Profiles with Agents

Profiles work seamlessly with Notte Agents. An agent running with a pre-authenticated profile can access authenticated resources immediately:

profile_with_agent.py

from notte_sdk import NotteClient

client = NotteClient()

# Use a profile with an agent
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
    agent = client.Agent(session=session, max_steps=10)

    # Agent runs with pre-authenticated session
    response = agent.run(
        task="Go to my GitHub notifications and summarize them", url="https://github.com/notifications"
    )

    print(f"Agent response: {response.answer}")

Managing Profiles

List Profiles

Retrieve all your profiles with optional filtering:

list_profiles.py

from notte_sdk import NotteClient

client = NotteClient()

# List all profiles
profiles = client.profiles.list()

for profile in profiles:
    print(f"- {profile.name}: {profile.profile_id}")

# Filter by name
filtered = client.profiles.list(name="github")
print(f"Found {len(filtered)} profiles matching 'github'")

Get Profile Details

Retrieve information about a specific profile:

get_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Get profile details
profile = client.profiles.get("notte-profile-abc123")

print(f"Profile ID: {profile.profile_id}")
print(f"Profile Name: {profile.name}")
print(f"Created At: {profile.created_at}")

Delete a Profile

Delete a profile when you no longer need it:

delete_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Delete a profile
deleted = client.profiles.delete("notte-profile-abc123")

if deleted:
    print("Profile deleted successfully")

Read-Only Profile Usage

Load a profile without saving changes by setting persist=False:

use_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Use an existing profile in a session
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
    # Session loads saved browser state from the profile
    session.execute(type="goto", url="https://example.com")

Use cases for read-only profiles:

• Test workflows without affecting saved state
• Run parallel sessions with the same profile safely
• Maintain a clean baseline profile for repeated use

By default, persist is False, so you don’t have to explicitly specify it for read-only access.

Best Practices

Profile Management

• Use descriptive names to identify profiles by their purpose (e.g., github-login, twitter-bot-1)
• Create separate profiles for different accounts or services
• Periodically verify that saved sessions are still valid

Security

• Profiles contain sensitive session data; treat profile IDs as secrets
• Delete profiles for accounts that are no longer needed
• Use separate profiles for production and development environments

Performance

• Profiles with large caches may take longer to load
• Consider creating fresh profiles periodically if performance degrades

Comparison: Profiles vs Cookies

Feature	Profiles	Cookies
Scope	Full browser state (cookies, storage, cache)	Cookies only
Storage	Managed by Notte	JSON file you manage
Persistence	Automatic on session end	Manual export/import
Use case	Long-term state preservation	Quick cookie injection

Use profiles when you need complete browser state preservation. Use cookies when you only need to inject specific authentication tokens.

Next Steps

Session Lifecycle

Manage session lifecycle

Cookies

Manual cookie management

Vaults

Secure credential storage

Session Configuration

All session options