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

<ParamField body="start_url" type="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
</ParamField>

<ParamField body="kiosk" type="boolean" default={false}>
  Flag to enable kiosk mode, which hides the browser navigation UI
</ParamField>

<ParamField body="timeout" type="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)
  </Tip>

  <Expandable>
    <ParamField body="absolute" type="number">
      The amount of time (in seconds) since creation, after which the session will terminate.
    </ParamField>

    <ParamField body="inactive" type="number">
      The amount of time (in seconds) since the last user input, after which the session will terminate.
    </ParamField>

    <ParamField body="offline" type="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.
    </ParamField>

    <ParamField body="warning" type="number" default={60}>
      The amount of time (in seconds) before the session is terminated due to another timeout.
    </ParamField>

    <ParamField body="webhook" type="object">
      <Expandable>
        <ParamField body="url" type="string">
          The URL to send the timeout webhook event to.
        </ParamField>

        <ParamField body="bearer" type="string">
          The Bearer Token to send with the webhook.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="touch_gestures" type="object">
  Enables touch gestures, such as pinch to zoom for touch screen devices

  <Expandable>
    <ParamField body="swipe" type="boolean" default={false}>
      Enables switch gestures, which enables features such as swipe left or right for browser history navigation.
    </ParamField>

    <ParamField body="pinch" type="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" />`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tenant_id" type="string">
  Custom ID provided for keeping track of usage on a per-tenant basis. See [Get Usage](/rest-api/dispatch/get-usage) for more information.
</ParamField>

<ParamField body="control_disable_default" type="boolean" default={false}>
  If true, users cannot control the browser by default, and need to be manually
  granted access by an admin user
</ParamField>

<ParamField body="region" type="string" default="NA">
  The server region: `NA` → North America, `EU` → Europe, `AS` → Asia
</ParamField>

<ParamField body="profile" type="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:

  <Expandable>
    <ParamField body="load" type="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)).
    </ParamField>

    <ParamField body="save" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="adblock" type="boolean" default={false}>
  Flag to install an adblock extension on the cloud browser
</ParamField>

<ParamField body="ublock" type="boolean" default={false} deprecated={true}>
  Deprecated. See the `adblock` flag. Flag to install an adblock extension on the cloud browser
</ParamField>

<ParamField body="draw" type="boolean" default={false}>
  Flag to install a drawing and annotation extension on the cloud browser
</ParamField>

<ParamField body="extension" type="object">
  Used to [install custom Chrome extensions.](/guides/install-chrome-extension)
  (Max Size 1MB).

  <Expandable>
    <ParamField body="field" type="string">
      Contains the path to your custom Chrome extension.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webgl" type="boolean" default={false}>
  Enables WebGL. Some games and interactive activities require WebGL
</ParamField>

<ParamField body="width" type="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.
</ParamField>

<ParamField body="height" type="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.
</ParamField>

<ParamField body="fps" type="number" default={24}>
  Integer frame rate of the browser. Must be in the range \[24, 60]
</ParamField>

<ParamField body="hide_cursor" type="boolean" default={false}>
  Hides the system cursor. Useful if you want to implement a multi-cursor user
  interface.
</ParamField>

<ParamField body="search_engine" type="string | object" default={"duckduckgo"}>
  Sets the default search engine that Chromium uses: `“duckduckgo”` | `“ecosia”` | `“google”` | `“startpage”` | `“brave”`

  <Accordion title="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}”
              }`
  </Accordion>
</ParamField>

<ParamField body="user_agent" type="string">
  Sets the user agent to a preset value. Currently only `"chrome_android"` is supported.
</ParamField>

<ParamField body="dark" type="boolean" default={false}>
  Enables dark mode
</ParamField>

<ParamField body="tag" type="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.
</ParamField>

<ParamField body="quality" type="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.

  <Expandable>
    <ParamField body="mode" type="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](/home/faq#streaming).</Warning>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="locale" type="object">
  Set the browser's locale and country.

  <Expandable>
    <ParamField body="language" type="string">A comma-delimited list of languages, see the [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) header.</ParamField>
    <ParamField body="country" type="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).</ParamField>
  </Expandable>
</ParamField>

<ResponseExample>
  ```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"
  }
  ```
</ResponseExample>

## Response

<ResponseField name="session_id" type="string">
  The ID of the cloud computer session
</ResponseField>

<ResponseField name="embed_url" type="string">
  A URL you can load into the [web client](/client-sdk/javascript) on your
  website
</ResponseField>

<ResponseField name="admin_token" type="string">
  A token that grants access to an exclusive subset of the client-side web SDK.
  Needed for setting permissions and programmatic navigation
</ResponseField>