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>",
      "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.

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": trueoption is passed to the session again, the session will be immutable.

3. Reuse Profile

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

Node

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

Python

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

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>"
    }
}'

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.

Node

// 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);

Python

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

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

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

cURL

Get Profile

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

List Profiles

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

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.