Profiles

Hyperbrowser Browser 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.

Node

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

Python

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

cURL

curl -X POST 'https://app.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:

Node

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

Python

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

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

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.

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:

Node

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

Python

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

cURL

curl -X DELETE 'https://app.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.