> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperbeam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Persist Session State

The Hyperbeam profile API allows you to persist session state including bookmarks, history,
passwords, and cookies which can be loaded into another session at a later time. This
allows you to resume sessions without requiring the user to open up web pages or
authenticate again.

<Note>
  Want to jump into the code? See our [persistence
  example.](https://github.com/hyperbeam/examples/tree/master/persistence)
</Note>

## Basic Usage

In order to save a session, the `profile` parameter must be set to `true` when
[starting a Chromium session](/rest-api/dispatch/start-chromium-session).

<Warning>Saved sessions that have not been accessed for three months expire and are deleted automatically</Warning>

#### Example Request

```curl theme={null}
curl --request POST \
     --url https://engine.hyperbeam.com/v0/vm \
     --header 'Authorization: Bearer AUTH_VALUE' \
     --header 'Content-Type: application/json' \
     --data '{
 "profile": true
}'
```

After the session is created, the response object will contain a `session_id` property that you must save
in order to load the session state again afterwards.

#### Example Response

```json theme={null}
{
  "session_id": "52f968cb-6739-4197-83d7-2305fe5d6f54",
  "embed_url": "https://vwdrccwgpv181powg61ggyvy.hyperbeam.com/Uvloy2c5QZeD1yMF_l1vVA?token=c8iw3SmQglOU0ugfLr3dWY2LalSKI_WOGUldEt8knbw",
  "admin_token": "51JOZEEcMp4trCwbpTS3jjQc0lSmeAZpPfxioDqe73U"
}
```

In order to load and update a previous session, the `profile` parameter must be set to the `session_id` you would like to resume
when [starting a Chromium session](/rest-api/dispatch/start-chromium-session).

```curl theme={null}
curl --request POST \
     --url https://engine.hyperbeam.com/v0/vm \
     --header 'Authorization: Bearer AUTH_VALUE' \
     --header 'Content-Type: application/json' \
     --data '{
 "profile": <session_id>
}'
```

This will load the profile associated with `<session_id>` and update its contents when the new session is terminated. Below is a code snippet that showcases a simple profile integration:

```js theme={null}
app.get("/computer", async (req, res) => {
  // Get the session ID from a query parameter
  // In a real application you want to authenticate the user retrieve the session ID from your database
  let { session_id } = req.query; 
  let profile = true; // profile = true will create a new profile
  if (session_id) {
    try {
      await db.get(session_id);
      profile = session_id; // if session_id is valid, load and update the profile tied to that id
    } catch (e) {
      res.status(400);
      return;
    }
  }
  const settings = {
    profile,
    timeout: {
      offline: 10,
    },
    ublock: true,
  };
  const headers = {
    Authorization: `Bearer ${process.env.HB_API_KEY}`,
  };
  let resp;
  try {
    resp = await axios.post("https://engine.hyperbeam.com/v0/vm", settings, {
      headers,
    });
  } catch (e) {
    console.error(e);
    res.status(501);
    res.send({ message: e.message });
    return;
  }
  const computer = resp.data;
  // if session_id was not defined, then a new profile was created and we want to store the session id tied to the new profile
  // otherwise use the old session id
  session_id = session_id || computer.session_id; 
  await db.put(session_id, {
    session_id,
    sites: [],
  });
  res.send(computer);
});
```

## Advanced Usage

For more granular control, you can specify separate profiles to load and overwrite. This is useful if you wish to create a new profile from an existing profile, without altering the original.

```curl theme={null}
curl --request POST \
     --url https://engine.hyperbeam.com/v0/vm \
     --header 'Authorization: Bearer AUTH_VALUE' \
     --header 'Content-Type: application/json' \
     --data '{
 "profile": {
  "save": <session_id_1>,
  "load": <session_id_2>
 }
}'
```

## How Do We Persist Sessions?

When `profile` is set to `true`, we encrypt and store the Chrome profile of the session in Amazon S3.

This Chrome profile is associated with the `session_id` that was returned to you on session creation.

When `profile` is set to a session ID, we look for a stored Chrome profile that corresponds to that `session_id`, and decrypt and
load the Chrome profile if there is a match.

This results in bookmarks, history, cookies, and passwords being persisted.

<Note>
  Looking for more detailed examples? See our [persistence
  example.](https://github.com/hyperbeam/examples/tree/master/persistence)
</Note>