Profiles

Hyperbrowser profiles allow you to reuse browser state like cookies, local storage, and network cache across multiple sessions. This can improve performance and enable seamless workflows requiring persistent data.

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 to pick up where you left off.

Common use cases for profiles include:

• Reusing authenticated sessions

• Improving page load times with a primed cache

• Preserving application state across sessions

Using Profiles

1. Create a Profile

First, create a new profile using the Profiles API. Note the returned id - you'll need this to attach the profile to sessions.

const profile = await client.profiles.create();
console.log("profile", profile.id);

profile = client.profiles.create()
print("profile", profile.id)

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

2. Attach Profile to Session

When creating a new session with the Sessions API, include the id in the profile field:

const session = await client.sessions.create({
  profile: {
    id: "<PROFILE_ID>",
    persistChanges: true, // set to true for the first session of a new profile
  },
});

session = client.sessions.create(
    params=CreateSessionParams(
        profile=CreateSessionProfile(
            id="<PROFILE_ID>",
            # set to true for the first session of a new profile
            persist_changes=True,
        ),
    )
)

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

Set "persistChanges": true in the profile object if you want the session to update the profile with any changes to cookies, cache, etc. 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.

3. Reuse Profile

Attach the same id to additional sessions to reuse browser state. Created profiles are reusable until you delete them.

const session = await client.sessions.create({
  profile: {
    id: "<PROFILE_ID>",
  },
});

session = client.sessions.create(
    params=CreateSessionParams(
        profile=CreateSessionProfile(
            id="<PROFILE_ID>",
        ),
    )
)

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

Now, this new session will reuse the browser state that is persisted to this profile.

Getting Profiles

You can get a specific profile via an id or list profiles you have created with query params. You can check out the Profiles API Reference to view full schema and params.

// Get single profile
const profile = await client.profiles.get("<PROFILE_ID>");
console.log("profile", profile);

// Get profile list
const profiles = await client.profiles.list();
console.log("profiles", profiles);

# Get single profile
profile = client.profiles.get("<PROFILE_ID>")
print("profile", profile.model_dump_json())

# Get profile list
from hyperbrowser.models import ProfileListParams
profiles = client.profiles.list()

# Optional ProfileListParams
# profiles = await client.profiles.list(ProfileListParams(limit=10, page=1))
print("profiles", profiles.model_dump_json())

curl -X GET 'https://api.hyperbrowser.ai/api/profile/<PROFILE_ID>' \
-H 'x-api-key: YOUR_API_KEY'

curl -X GETETE 'https://api.hyperbrowser.ai/api/profiles' \
-H 'x-api-key: YOUR_API_KEY'

Deleting Profiles

Delete unused profiles to free up resources. Once deleted, a profile is no longer attachable to sessions.

To delete a profile, send a DELETE request to the Profiles API with the target id:

const response = await client.profiles.delete("<PROFILE_ID>");
console.log("response", response);

response = client.profiles.delete("<PROFILE_ID>")
print("response", response)

curl -X DELETE 'https://api.hyperbrowser.ai/api/profile/<PROFILE_ID>' \
-H 'x-api-key: YOUR_API_KEY'

Deletion is irreversible, so be sure you no longer need a profile before deleting.