> ## 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.

# Starting a Chromium Session

> Initiate a Chromium browser using Hyperbeam

## Parameters

**start\_url** `string` (default: about:blank)

The initial URL that is set in the browser. If unset, and a profile is loaded,
tabs from the profile are restored

**kiosk** `boolean` (default: false)

Flag to enable kiosk mode, which hides the browser navigation UI

**timeout** `object`

Timeouts determine when a session will be automatically terminated.
Also, when a timeout (or timeout warning) is triggered, a webhook event will be sent to the URL specified by the `webhook` timeout parameter.

> [!TIP]
>
> You can reset these values for live sessions by hitting the \<embed\_url>/timeout endpoint. [See example.](https://github.com/hyperbeam/examples/tree/master/timeout)

**absolute** `number`

The amount of time (in seconds) since creation, after which the session will terminate.

**inactive** `number`

The amount of time (in seconds) since the last user input, after which the session will terminate.

**offline** `number` (default: 3600)

The amount of time (in seconds) that no users are connected, after which the session will terminate. Resets when a user connects.

**warning** `number` (default: 60)

The amount of time (in seconds) before the session is terminated due to another timeout.

**webhook** `object`

**url** `string`

The URL to send the timeout webhook event to.

**bearer** `string`

The Bearer Token to send with the webhook.

**touch\_gestures** `object`

Enables touch gestures, such as pinch to zoom for touch screen devices

**swipe** `boolean` (default: false)

Enables switch gestures, which enables features such as swipe left or right for browser history navigation.

**pinch** `boolean` (default: false)

Enables the pinch gestures, which enables features such as pinch to zoom. The zoom can be reset on desktop by pressing the `Escape` key or refreshing the browser page.

You will need to disable viewport scaling to enable pinch-to-zoom on the virtual browser. Include the following meta tag in your HTML:
`<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />`

**tenant\_id** `string`

Custom ID provided for keeping track of usage on a per-tenant basis. See [Get Usage](https://docs.hyperbeam.com/rest-api/dispatch/get-usage.md) for more information.

**control\_disable\_default** `boolean` (default: false)

If true, users cannot control the browser by default, and need to be manually
granted access by an admin user

**region** `string` (default: NA)

The server region: `NA` → North America, `EU` → Europe, `AS` → Asia

**profile** `boolean | string | object`

Used to save and load Chrome profiles including bookmarks, history, passwords,
cookies etc. `true` will create a new profile, while passing in a session ID
of an existing profile will load and update the profile. For advanced usage,
you can provide an object that specifies the session IDs of the profile you
wish to load and the profile you wish to overwrite:

**load** `string`

ID of the session you want to load in the cloud browser (a profile is
encrypted browser state from a previous session, with the profile ID being
its `session_id`, see [response body](#response)).

**save** `boolean | string` (default: false)

`save` = `true` creates a new persisted profile you can load from. If a
session ID is provided, then the profile associated with the session ID
will be overwritten.

**adblock** `boolean` (default: false)

Flag to install an adblock extension on the cloud browser

**ublock** `boolean` *deprecated* (default: false)

Deprecated. See the `adblock` flag. Flag to install an adblock extension on the cloud browser

**draw** `boolean` (default: false)

Flag to install a drawing and annotation extension on the cloud browser

**extension** `object`

Used to [install custom Chrome extensions.](https://docs.hyperbeam.com/guides/install-chrome-extension.md)
(Max Size 1MB).

**field** `string`

Contains the path to your custom Chrome extension.

**webgl** `boolean` (default: false)

Enables WebGL. Some games and interactive activities require WebGL

**width** `number` (default: 1280)

Width of the browser in pixels. If set, height must be set as well.

The max number of pixels (width height) is capped at 1920\*1080.

**height** `number` (default: 720)

Height of the browser in pixels. If set, width must be set as well.

The max number of pixels (width height) is capped at 1920\*1080.

**fps** `number` (default: 24)

Integer frame rate of the browser. Must be in the range \[24, 60]

**hide\_cursor** `boolean` (default: false)

Hides the system cursor. Useful if you want to implement a multi-cursor user
interface.

**search\_engine** `string | object` (default: duckduckgo)

Sets the default search engine that Chromium uses: `“duckduckgo”` | `“ecosia”` | `“google”` | `“startpage”` | `“brave”`

> [accordion] How to use custom search engine
>
> You can use a custom search engine by passing in an object as follows:
> `{
>             “name”: “foo”,
>             “keyword”: “f”,
>             “url”: “https://foo.com/search?q={searchTerms}”,
>             “suggestions_url”: “https://foo.com/suggest?q={searchTerms}”
>           }`

**user\_agent** `string`

Sets the user agent to a preset value. Currently only `"chrome_android"` is supported.

**dark** `boolean` (default: false)

Enables dark mode

**tag** `string`

The `tag` property enforces uniqueness. If a session with tag `"A"` is already
running and you attempt to make another session with tag `"A"`, the endpoint
will not create a new instance and will instead return the `session_id` and
`embed_url` of the existing session.

**quality** `object`

Used to toggle between **sharp**, **smooth**, and **blocky** quality modes.
Sharp mode is ideal for situations where reading small text is important.
Smooth mode is ideal for anything involving movement (e.g. videos, dynamic activities).
Blocky mode is ideal for clients with poor internet connectivity.

**mode** `string` (default: smooth)

Possible values are `"sharp"`, `"smooth"`, and `"blocky"`.
\[!WARNING] Enabling sharp mode triples the required bandwidth. You can view our bandwidth recommendations in the [Streaming FAQ](https://docs.hyperbeam.com/home/faq.md#streaming).

**locale** `object`

Set the browser's locale and country.

**language** `string`

A comma-delimited list of languages, see the [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) header.

**country** `string`

The [ISO 3166 A-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code, e.g. US for the United States, CA for Canada. You can retrieve the user's country by using an IP database like [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data).

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

## Response

**session\_id** `string`

The ID of the cloud computer session

**embed\_url** `string`

A URL you can load into the [web client](https://docs.hyperbeam.com/client-sdk/javascript) on your
website

**admin\_token** `string`

A token that grants access to an exclusive subset of the client-side web SDK.
Needed for setting permissions and programmatic navigation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.