Profiles

Profiles let you save and reuse browser state, which includes cookies, local storage, session storage, and cache, across multiple sessions. Perfect for maintaining login states, preserving user preferences, or building realistic multi session workflows.

How Profiles Work

A profile is essentially a saved snapshot of a browser’s user data directory. By default, each Hyperbrowser session uses a fresh user data directory to ensure isolation. When you create a profile and then use and persist it in a new session, Hyperbrowser saves that session’s user data directory. You can then attach the profile to future sessions.

Create a Profile

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

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

// Create a profile with optional name
const profile = await client.profiles.create({
  name: "my-profile",
});

console.log("Profile created:", profile.id);
console.log("Profile name:", profile.name);

from hyperbrowser import Hyperbrowser
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

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

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

from hyperbrowser import Hyperbrowser
from hyperbrowser.models import CreateProfileParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

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

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

curl -X POST https://api.hyperbrowser.ai/api/profile \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-profile"
  }'

Use a Profile in a Session

Attach a profile to a session to load and save browser state:

const session = await client.sessions.create({
  profile: {
    id: profile.id,
    // Optional: Persist changes made to the profile during the session
    // Set to true for the first session of a new profile
    // persistChanges: true,
  },
});

console.log("Session created with profile:", session.id);

session = client.sessions.create(
    params={
        "profile": {
            "id": profile.id,
            # Optional: Persist changes made to the profile during the session
            # Set to True for the first session of a new profile
            # "persist_changes": True,
        }
    }
)

print(f"Session created with profile: {session.id}")

from hyperbrowser.models import CreateSessionParams, CreateSessionProfile

session = client.sessions.create(
    params=CreateSessionParams(
        profile=CreateSessionProfile(
            id=profile.id,
            # Optional: Persist changes made to the profile during the session
            # Set to True for the first session of a new profile
            # persist_changes=True,
        )
    )
)

print(f"Session created with profile: {session.id}")

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "id": "profile-id-here",
      "persistChanges": true
    }
  }'

Persist Changes

The persistChanges parameter controls whether session changes are saved. You will need to do this for the first time you use a new profile in a session so it can be used in subsequent sessions.

true - Persist changes made to the profile during the session
false (default) - Use the profile as read-only; don’t persist changes made to the profile during the session

Once whatever changes to the profile have been made, the session should be safely closed to ensure that the profile is saved. After that unless the “persistChanges”: true option is passed to the session again, the profile will be immutable.

When using browser automation libraries like Playwright or Puppeteer, it is important to always use the default context in order for profiles to work properly.

Persist Network Cache

The persistNetworkCache parameter controls whether the browser’s network cache (HTTP cache) is persisted along with other profile data when persisting changes.

true - Persist network cache
false (default) - Don’t persist network cache

Persisting Network Cache requires the persistChanges parameter to be set to true.

Here’s a minimal example of creating a session with network cache persistence enabled:

const session = await client.sessions.create({
  profile: {
    id: profile.id,
    persistChanges: true,
    persistNetworkCache: true,
  },
});

session = client.sessions.create(
    params={
        "profile": {
            "id": profile.id,
            "persist_changes": True,
            "persist_network_cache": True,
        }
    }
)

from hyperbrowser.models import CreateSessionParams, CreateSessionProfile

session = client.sessions.create(
    params=CreateSessionParams(
        profile=CreateSessionProfile(
            id=profile.id,
            persist_changes=True,
            persist_network_cache=True,
        )
    )
)

Persisting Network Cache is currently available by request. Please contact us at info@hyperbrowser.ai or on our support chat to enable network cache persistence for your team.

First, create a profile and perform a login. When the session ends, all cookies and browser state are automatically saved to the profile.

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function loginAndSaveProfile() {
  // 1. Create a profile
  const profile = await client.profiles.create({
    name: "hackernews-profile",
  });
  console.log("Profile created:", profile.id);

  // 2. Create session with profile
  const session = await client.sessions.create({
    profile: {
      id: profile.id,
      persistChanges: true, // Save browser state to profile
    },
  });

  const HACKER_NEWS_USERNAME = "your_username";
  const HACKER_NEWS_PASSWORD = "your_password";

  try {
    const browser = await chromium.connectOverCDP(session.wsEndpoint);
    const defaultContext = browser.contexts()[0];
    const page = defaultContext.pages()[0];

    // 3. Log in to Hacker News
    await page.goto("https://news.ycombinator.com/login");
    await page.fill('input[name="acct"]', HACKER_NEWS_USERNAME);
    await page.fill('input[name="pw"]', HACKER_NEWS_PASSWORD);
    await page.click('input[type="submit"]');
    await page.waitForLoadState("networkidle");

    const pageUrl = page.url();
    const isLoggedIn = pageUrl === "https://news.ycombinator.com/";

    if (isLoggedIn) {
      console.log("Logged in successfully to Hacker News");
    } else {
      console.error("Failed to log in to Hacker News");
    }
  } catch (err) {
    console.error("Error logging in to Hacker News:", err);
  } finally {
    // 4. Stop session - profile now contains login cookies
    await client.sessions.stop(session.id);
  }

  return profile.id;
}

// Save the profile ID for later use
loginAndSaveProfile().then((profileId) => {
  console.log("Saved profile ID:", profileId);
});

from hyperbrowser import Hyperbrowser
from playwright.sync_api import sync_playwright
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def login_and_save_profile():
    # 1. Create a profile
    profile = client.profiles.create(params={"name": "hackernews-profile"})
    print(f"Profile created: {profile.id}")

    # 2. Create session with profile
    session = client.sessions.create(
        params={
            "profile": {
                "id": profile.id,
                "persist_changes": True,  # Save browser state to profile
            }
        }
    )

    HACKER_NEWS_USERNAME = "your_username"
    HACKER_NEWS_PASSWORD = "your_password"

    try:
        with sync_playwright() as p:
            browser = p.chromium.connect_over_cdp(session.ws_endpoint)
            default_context = browser.contexts[0]
            page = default_context.pages[0]

            # 3. Log in to Hacker News
            page.goto("https://news.ycombinator.com/login")
            page.fill('input[name="acct"]', HACKER_NEWS_USERNAME)
            page.fill('input[name="pw"]', HACKER_NEWS_PASSWORD)
            page.click('input[type="submit"]')
            page.wait_for_load_state("networkidle", timeout=5000)

            page_url = page.url
            is_logged_in = page_url == "https://news.ycombinator.com/"

            if is_logged_in:
                print("Logged in successfully to Hacker News")
            else:
                print("Failed to log in to Hacker News")
    except Exception as e:
        print(f"Error logging in to Hacker News: {e}")
    finally:
        # 4. Stop session - profile now contains login cookies
        client.sessions.stop(session.id)

    return profile.id


# Save the profile ID for later use
profile_id = login_and_save_profile()
print(f"Saved profile ID: {profile_id}")

from hyperbrowser import Hyperbrowser
from hyperbrowser.models import (
    CreateSessionParams,
    CreateProfileParams,
    CreateSessionProfile,
)
from playwright.sync_api import sync_playwright
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def login_and_save_profile():
    # 1. Create a profile
    profile = client.profiles.create(
        params=CreateProfileParams(name="hackernews-profile")
    )
    print(f"Profile created: {profile.id}")

    # 2. Create session with profile
    session = client.sessions.create(
        params=CreateSessionParams(
            profile=CreateSessionProfile(
                id=profile.id,
                persist_changes=True,  # Save browser state to profile
            )
        )
    )

    HACKER_NEWS_USERNAME = "your_username"
    HACKER_NEWS_PASSWORD = "your_password"

    try:
        with sync_playwright() as p:
            browser = p.chromium.connect_over_cdp(session.ws_endpoint)
            default_context = browser.contexts[0]
            page = default_context.pages[0]

            # 3. Log in to Hacker News
            page.goto("https://news.ycombinator.com/login")
            page.fill('input[name="acct"]', HACKER_NEWS_USERNAME)
            page.fill('input[name="pw"]', HACKER_NEWS_PASSWORD)
            page.click('input[type="submit"]')
            page.wait_for_load_state("networkidle", timeout=5000)

            page_url = page.url
            is_logged_in = page_url == "https://news.ycombinator.com/"

            if is_logged_in:
                print("Logged in successfully to Hacker News")
            else:
                print("Failed to log in to Hacker News")
    except Exception as e:
        print(f"Error logging in to Hacker News: {e}")
    finally:
        # 4. Stop session - profile now contains login cookies
        client.sessions.stop(session.id)

    return profile.id


# Save the profile ID for later use
profile_id = login_and_save_profile()
print(f"Saved profile ID: {profile_id}")

A new profile will be created that stores your login credentials and can be used to in future sessions. You can view and manage your profiles in the Profiles page in the dashboard.

Profiles can take a few seconds after the browser session is closed to completely save.

Step 2: Reuse the Saved Profile

After waiting a couple seconds, now use the saved profile in a new session. The browser will automatically load the saved cookies, so you’re already logged in without needing to authenticate again.

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function useExistingProfile(profileId) {
  // Use the same profile in a new session
  const session = await client.sessions.create({
    profile: {
      id: profileId,
    },
  });

  try {
    const browser = await chromium.connectOverCDP(session.wsEndpoint);
    const defaultContext = browser.contexts()[0];
    const page = defaultContext.pages()[0];

    // Navigate directly to Hacker News - already logged in!
    await page.goto("https://news.ycombinator.com/", {
      waitUntil: "networkidle",
    });

    try {
      await page.waitForSelector("#me", { timeout: 7_000 });
    } catch {
      console.error("Timed out waiting for selector #me");
    }

    const username = await page.$eval("#me", (el) =>
      el ? el.textContent : null
    );

    if (username) {
      console.log("Still logged in as:", username);
    } else {
      console.error("Not logged in to Hacker News");
    }
  } catch (err) {
    console.error("Error using existing profile:", err);
  } finally {
    await client.sessions.stop(session.id);
  }
}

useExistingProfile("your-profile-id").then(() => {
  console.log("Finished reusing profile!");
});

from hyperbrowser import Hyperbrowser
from playwright.sync_api import sync_playwright
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def use_existing_profile(profile_id):
    session = client.sessions.create(
        params={
            "profile": {
                "id": profile_id,
            }
        }
    )

    try:
        with sync_playwright() as p:
            browser = p.chromium.connect_over_cdp(session.ws_endpoint)
            default_context = browser.contexts[0]
            page = default_context.pages[0]

            page.goto("https://news.ycombinator.com/", wait_until="networkidle")

            try:
                page.wait_for_selector("#me", timeout=7_000)
            except:
                print("Timed out waiting for selector #me")

            username = page.evaluate("""
                () => {
                    const meElement = document.querySelector('#me');
                    return meElement ? meElement.textContent : null;
                }
            """)
            if username:
                print("Still logged in as:", username)
            else:
                print("Not logged in to Hacker News")
    except Exception as e:
        print(f"Error using existing profile: {e}")
    finally:
        client.sessions.stop(session.id)


use_existing_profile("your-profile-id")

from hyperbrowser import Hyperbrowser
from hyperbrowser.models import CreateSessionParams, CreateSessionProfile
from playwright.sync_api import sync_playwright
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


def use_existing_profile(profile_id):
    session = client.sessions.create(
        params=CreateSessionParams(
            profile=CreateSessionProfile(
                id=profile_id,
            )
        )
    )

    try:
        with sync_playwright() as p:
            browser = p.chromium.connect_over_cdp(session.ws_endpoint)
            default_context = browser.contexts[0]
            page = default_context.pages[0]

            page.goto("https://news.ycombinator.com/", wait_until="networkidle")

            try:
                page.wait_for_selector("#me", timeout=7_000)
            except:
                print("Timed out waiting for selector #me")

            username = page.evaluate("""
                () => {
                    const meElement = document.querySelector('#me');
                    return meElement ? meElement.textContent : null;
                }
            """)
            if username:
                print("Still logged in as:", username)
            else:
                print("Not logged in to Hacker News")
    except Exception as e:
        print(f"Error using existing profile: {e}")
    finally:
        client.sessions.stop(session.id)


use_existing_profile("your-profile-id")

What happens here:

A new session is created using the same profile ID
The browser automatically loads the saved cookies and state from the profile
You can navigate directly to Hacker News and you’re already authenticated
No login required - the session picks up right where you left off

This pattern is useful for scenarios where you need to:

Avoid repeated logins across multiple automation runs
Test authenticated user flows
Manage multiple accounts with separate profiles
Maintain session state over time

Forking Profiles

Forking lets you create an independent copy of a profile. This is useful when you want to start from an existing authenticated state but save new changes to a separate profile — for example, adding a second login without modifying the original. Use profiles.fork() to create a standalone copy of a profile at any time. The original profile is never modified.

// Fork profile A into a new independent profile B
const forkedProfile = await client.profiles.fork(profileA.id, {
  name: "profile-b",
});

console.log("Forked profile:", forkedProfile.id);

// Use the forked profile in a new session
const session = await client.sessions.create({
  profile: {
    id: forkedProfile.id,
    persistChanges: true,
  },
});

# Fork profile A into a new independent profile B
forked_profile = client.profiles.fork(
    profile_a.id,
    params={"name": "profile-b"},
)

print(f"Forked profile: {forked_profile.id}")

# Use the forked profile in a new session
session = client.sessions.create(
    params={
        "profile": {
            "id": forked_profile.id,
            "persist_changes": True,
        }
    }
)

from hyperbrowser.models import (
    ForkProfileParams,
    CreateSessionParams,
    CreateSessionProfile,
)

# Fork profile A into a new independent profile B
forked_profile = client.profiles.fork(
    profile_a.id,
    params=ForkProfileParams(name="profile-b"),
)

print(f"Forked profile: {forked_profile.id}")

# Use the forked profile in a new session
session = client.sessions.create(
    params=CreateSessionParams(
        profile=CreateSessionProfile(
            id=forked_profile.id,
            persist_changes=True,
        )
    )
)

curl -X POST https://api.hyperbrowser.ai/api/profile/PROFILE_A_ID/fork \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "profile-b"
  }'

Managing Profiles

List Profiles

Retrieve all your profiles with optional pagination and filtering:

const result = await client.profiles.list({
  page: 1,
  name: "hackernews-profile",
});

console.log(`Found ${result.totalCount} profiles`);

result.profiles.forEach((profile) => {
  console.log(`- ${profile.name}: ${profile.id}`);
});

result = client.profiles.list(
    params={
        "page": 1,
        "name": "hackernews-profile",
    }
)

print(f"Found {result.total_count} profiles")

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

from hyperbrowser.models import ProfileListParams

result = client.profiles.list(
    params=ProfileListParams(
        page=1,
        name="hackernews-profile",
    )
)

print(f"Found {result.total_count} profiles")

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

curl -X GET "https://api.hyperbrowser.ai/api/profiles?page=1&name=hackernews-profile" \
  -H "x-api-key: YOUR_API_KEY"

Get Profile Details

Retrieve information about a specific profile:

const profile = await client.profiles.get("your-profile-id");

console.log("Profile ID:", profile.id);
console.log("Profile Name:", profile.name);
console.log("Created At:", profile.createdAt);

profile = client.profiles.get("your-profile-id")

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

curl -X GET https://api.hyperbrowser.ai/api/profile/profile-id \
  -H "x-api-key: YOUR_API_KEY"

Delete a Profile

Delete a profile when you no longer need it:

await client.profiles.delete("profile-id");

console.log("Profile deleted");

client.profiles.delete("profile-id")

print("Profile deleted")

curl -X DELETE https://api.hyperbrowser.ai/api/profile/profile-id \
  -H "x-api-key: YOUR_API_KEY"

Read-Only Profile Usage

Load a previously persisted profile without saving any changes made during this new session:

const session = await client.sessions.create({
  profile: {
    id: "your-profile-id",
    persistChanges: false,  // Don't save changes
  },
});

// Use the session - changes will not be persisted

session = client.sessions.create(
    params={
        "profile": {
            "id": "your-profile-id",
            "persist_changes": False,  # Don't save changes
        }
    }
)

# Use the session - changes will not be persisted

from hyperbrowser.models import CreateSessionParams, CreateSessionProfile

session = client.sessions.create(
    params=CreateSessionParams(
        profile=CreateSessionProfile(
            id="your-profile-id",
            persist_changes=False,  # Don't save changes
        )
    )
)

# Use the session - changes will not be persisted

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "id": "your-profile-id",
      "persistChanges": false
    }
  }'

Use cases for read-only profiles:

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

By default, persistChanges is set to false so you don’t have to explicitly specify it.

Next Steps

Lifecycle Management

Manage session lifecycle

Recordings

Record session activity

Live View

Watch sessions in real-time

Extensions

Load browser extensions

Get Started

Browser Sessions

Session Configuration

Web API

Agents

HyperAgent Usage

Scraping

Integrations

How Profiles Work

Create a Profile

Use a Profile in a Session

Persist Changes

Persist Network Cache

Step 2: Reuse the Saved Profile

Forking Profiles

Managing Profiles

List Profiles

Get Profile Details

Delete a Profile

Read-Only Profile Usage

Next Steps

Lifecycle Management

Recordings

Live View

Extensions

​How Profiles Work

​Create a Profile

​Use a Profile in a Session

​Persist Changes

​Persist Network Cache

​Profile Login Example

​Step 1: Login and Save to Profile

​Step 2: Reuse the Saved Profile

​Forking Profiles

​Managing Profiles

​List Profiles

​Get Profile Details

​Delete a Profile

​Read-Only Profile Usage

​Next Steps

Lifecycle Management

Recordings

Live View

Extensions

How Profiles Work

Create a Profile

Use a Profile in a Session

Persist Changes

Persist Network Cache

Profile Login Example

Step 1: Login and Save to Profile

Step 2: Reuse the Saved Profile

Forking Profiles

Managing Profiles

List Profiles

Get Profile Details

Delete a Profile

Read-Only Profile Usage

Next Steps