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

# Browser sessions

> Create and manage persistent cloud browser sessions.

A browser session is a cloud browser that stays open between runs, so tasks and agents can share cookies and page state. Pass its `browser_session_id` (`pbs_…`) to `run_task` or `run_workflow`.

Every method here also accepts `request_options` (Python) or a final `requestOptions` argument (TypeScript) to override the timeout, retries or headers for one call; see [request options](/docs/sdk-reference/overview#request-options).

***

## create\_browser\_session

Create a browser session that persists across multiple runs

<CodeGroup>
  ```python Python theme={null}
  await skyvern.create_browser_session(
      *,
      url: str | None = ...,
      timeout: int | None = ...,
      proxy_location: CreateBrowserSessionRequestProxyLocation | None = ...,
      proxy_session_id: str | None = ...,
      extensions: Sequence[Extensions] | None = ...,
      browser_type: PersistentBrowserType | None = ...,
      browser_profile_id: str | None = ...,
      generate_browser_profile: bool | None = ...,
  ) -> BrowserSessionResponse
  ```

  ```typescript TypeScript theme={null}
  skyvern.createBrowserSession(request?: CreateBrowserSessionRequest): Promise<BrowserSessionResponse>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `url` | `url` | `str \| None` | No | — | Optional URL to open when the standalone browser session starts. |
| `timeout` | `timeout` | `int \| None` | No | — | Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240. Defaults to 60. |
| `proxy_location` | `proxy_location` | `CreateBrowserSessionRequestProxyLocation \| None` | No | — | Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud. |
| `proxy_session_id` | `proxy_session_id` | `str \| None` | No | — | Opaque Skyvern-managed proxy sticky-session id for pinned Residential ISP sessions. |
| `extensions` | `extensions` | `Sequence[Extensions] \| None` | No | — | A list of extensions to install in the browser session. |
| `browser_type` | `browser_type` | `PersistentBrowserType \| None` | No | — | The type of browser to use for the session. |
| `browser_profile_id` | `browser_profile_id` | `str \| None` | No | — | ID of a browser profile to load into this session (restores cookies, localStorage, etc.). browser\_profile\_id starts with `bp_`. |
| `generate_browser_profile` | `generate_browser_profile` | `bool \| None` | No | — | When true, the session's browser profile (cookies, localStorage, etc.) is saved to storage when the session ends so it can be turned into a reusable browser profile. Defaults to false to avoid storing profiles for sessions that never need them. Sessions started with a browser\_profile\_id always persist their profile regardless of this flag. |

**Returns** `BrowserSessionResponse` · TypeScript `Promise<BrowserSessionResponse>`

<Accordion title="BrowserSessionResponse fields">
  | Field | Type | Description |
  | - | - | - |
  | `browser_session_id` | `str` | Unique identifier for the browser session. browser\_session\_id starts with `pbs_`. |
  | `organization_id` | `str` | ID of the organization that owns this session |
  | `status` | `str \| None` | Current status of the browser session |
  | `runnable_type` | `str \| None` | Type of the current runnable associated with this session (workflow, task etc) |
  | `runnable_id` | `str \| None` | ID of the current runnable |
  | `timeout` | `int \| None` | Timeout in minutes for the session. Timeout is applied after the session is started. Defaults to 60 minutes. |
  | `browser_address` | `str \| None` | Url for connecting to the browser |
  | `app_url` | `str \| None` | Url for the browser session page |
  | `extensions` | `list["ad-blocker" \| "captcha-solver" \| Any] \| None` | A list of extensions installed in the browser session. |
  | `browser_type` | `"msedge" \| "chrome" \| "stealth-chromium" \| None` | The type of browser used for the session. |
  | `browser_profile_id` | `str \| None` | ID of the browser profile loaded into this session, if any. browser\_profile\_id starts with `bp_`. |
  | `generate_browser_profile` | `bool \| None` | Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile. |
  | `vnc_streaming_supported` | `bool \| None` | Whether the browser session supports VNC streaming |
  | `download_path` | `str \| None` | The path where the browser session downloads files |
  | `downloaded_files` | `list[FileInfo] \| None` | The list of files downloaded by the browser session |
  | `recordings` | `list[FileInfo] \| None` | The list of video recordings from the browser session |
  | `started_at` | `datetime \| None` | Timestamp when the session was started |
  | `completed_at` | `datetime \| None` | Timestamp when the session was completed |
  | `created_at` | `datetime` | Timestamp when the session was created (the timestamp for the initial request) |
  | `modified_at` | `datetime` | Timestamp when the session was last modified |
  | `deleted_at` | `datetime \| None` | Timestamp when the session was deleted, if applicable |
</Accordion>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import asyncio

  from skyvern import Skyvern


  async def main() -> None:
      skyvern = Skyvern(api_key="YOUR_API_KEY")
      result = await skyvern.create_browser_session()
      print(result)


  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { Skyvern } from "@skyvern/client";

  const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
  const result = await skyvern.createBrowserSession();
  console.log(result);
  ```
</CodeGroup>

***

## get\_browser\_session

Get details about a specific browser session, including the browser address for cdp connection.

<CodeGroup>
  ```python Python theme={null}
  await skyvern.get_browser_session(browser_session_id: str) -> BrowserSessionResponse
  ```

  ```typescript TypeScript theme={null}
  skyvern.getBrowserSession(browserSessionId: string): Promise<BrowserSessionResponse>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `browser_session_id` | `browserSessionId` | `str` | Yes | — | The ID of the browser session. browser\_session\_id starts with `pbs_` |

**Returns** `BrowserSessionResponse` · TypeScript `Promise<BrowserSessionResponse>`

<Accordion title="BrowserSessionResponse fields">
  | Field | Type | Description |
  | - | - | - |
  | `browser_session_id` | `str` | Unique identifier for the browser session. browser\_session\_id starts with `pbs_`. |
  | `organization_id` | `str` | ID of the organization that owns this session |
  | `status` | `str \| None` | Current status of the browser session |
  | `runnable_type` | `str \| None` | Type of the current runnable associated with this session (workflow, task etc) |
  | `runnable_id` | `str \| None` | ID of the current runnable |
  | `timeout` | `int \| None` | Timeout in minutes for the session. Timeout is applied after the session is started. Defaults to 60 minutes. |
  | `browser_address` | `str \| None` | Url for connecting to the browser |
  | `app_url` | `str \| None` | Url for the browser session page |
  | `extensions` | `list["ad-blocker" \| "captcha-solver" \| Any] \| None` | A list of extensions installed in the browser session. |
  | `browser_type` | `"msedge" \| "chrome" \| "stealth-chromium" \| None` | The type of browser used for the session. |
  | `browser_profile_id` | `str \| None` | ID of the browser profile loaded into this session, if any. browser\_profile\_id starts with `bp_`. |
  | `generate_browser_profile` | `bool \| None` | Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile. |
  | `vnc_streaming_supported` | `bool \| None` | Whether the browser session supports VNC streaming |
  | `download_path` | `str \| None` | The path where the browser session downloads files |
  | `downloaded_files` | `list[FileInfo] \| None` | The list of files downloaded by the browser session |
  | `recordings` | `list[FileInfo] \| None` | The list of video recordings from the browser session |
  | `started_at` | `datetime \| None` | Timestamp when the session was started |
  | `completed_at` | `datetime \| None` | Timestamp when the session was completed |
  | `created_at` | `datetime` | Timestamp when the session was created (the timestamp for the initial request) |
  | `modified_at` | `datetime` | Timestamp when the session was last modified |
  | `deleted_at` | `datetime \| None` | Timestamp when the session was deleted, if applicable |
</Accordion>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import asyncio

  from skyvern import Skyvern


  async def main() -> None:
      skyvern = Skyvern(api_key="YOUR_API_KEY")
      result = await skyvern.get_browser_session(browser_session_id="pbs_123")
      print(result)


  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { Skyvern } from "@skyvern/client";

  const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
  const result = await skyvern.getBrowserSession("pbs_123");
  console.log(result);
  ```
</CodeGroup>

***

## get\_browser\_sessions

Get all active browser sessions for the organization

<CodeGroup>
  ```python Python theme={null}
  await skyvern.get_browser_sessions() -> list[BrowserSessionResponse]
  ```

  ```typescript TypeScript theme={null}
  skyvern.getBrowserSessions(): Promise<BrowserSessionResponse[]>
  ```
</CodeGroup>

**Returns** `list[BrowserSessionResponse]` · TypeScript `Promise<BrowserSessionResponse[]>`

<Accordion title="BrowserSessionResponse fields">
  | Field | Type | Description |
  | - | - | - |
  | `browser_session_id` | `str` | Unique identifier for the browser session. browser\_session\_id starts with `pbs_`. |
  | `organization_id` | `str` | ID of the organization that owns this session |
  | `status` | `str \| None` | Current status of the browser session |
  | `runnable_type` | `str \| None` | Type of the current runnable associated with this session (workflow, task etc) |
  | `runnable_id` | `str \| None` | ID of the current runnable |
  | `timeout` | `int \| None` | Timeout in minutes for the session. Timeout is applied after the session is started. Defaults to 60 minutes. |
  | `browser_address` | `str \| None` | Url for connecting to the browser |
  | `app_url` | `str \| None` | Url for the browser session page |
  | `extensions` | `list["ad-blocker" \| "captcha-solver" \| Any] \| None` | A list of extensions installed in the browser session. |
  | `browser_type` | `"msedge" \| "chrome" \| "stealth-chromium" \| None` | The type of browser used for the session. |
  | `browser_profile_id` | `str \| None` | ID of the browser profile loaded into this session, if any. browser\_profile\_id starts with `bp_`. |
  | `generate_browser_profile` | `bool \| None` | Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile. |
  | `vnc_streaming_supported` | `bool \| None` | Whether the browser session supports VNC streaming |
  | `download_path` | `str \| None` | The path where the browser session downloads files |
  | `downloaded_files` | `list[FileInfo] \| None` | The list of files downloaded by the browser session |
  | `recordings` | `list[FileInfo] \| None` | The list of video recordings from the browser session |
  | `started_at` | `datetime \| None` | Timestamp when the session was started |
  | `completed_at` | `datetime \| None` | Timestamp when the session was completed |
  | `created_at` | `datetime` | Timestamp when the session was created (the timestamp for the initial request) |
  | `modified_at` | `datetime` | Timestamp when the session was last modified |
  | `deleted_at` | `datetime \| None` | Timestamp when the session was deleted, if applicable |
</Accordion>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import asyncio

  from skyvern import Skyvern


  async def main() -> None:
      skyvern = Skyvern(api_key="YOUR_API_KEY")
      result = await skyvern.get_browser_sessions()
      print(result)


  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { Skyvern } from "@skyvern/client";

  const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
  const result = await skyvern.getBrowserSessions();
  console.log(result);
  ```
</CodeGroup>

***

## update\_browser\_session

Update a live browser session. Currently supports toggling generate\_browser\_profile, which is read when the session ends to decide whether to save its browser profile.

<CodeGroup>
  ```python Python theme={null}
  await skyvern.update_browser_session(
      browser_session_id: str,
      *,
      generate_browser_profile: bool,
  ) -> BrowserSessionResponse
  ```

  ```typescript TypeScript theme={null}
  skyvern.updateBrowserSession(browserSessionId: string, request: UpdateBrowserSessionRequest): Promise<BrowserSessionResponse>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `browser_session_id` | `browserSessionId` | `str` | Yes | — | The ID of the browser session. browser\_session\_id starts with `pbs_` |
| `generate_browser_profile` | `generate_browser_profile` | `bool` | Yes | — | Enable or disable saving this session's browser profile when it ends. Can be toggled while the session is still alive; the value is read at session teardown. |

**Returns** `BrowserSessionResponse` · TypeScript `Promise<BrowserSessionResponse>`

<Accordion title="BrowserSessionResponse fields">
  | Field | Type | Description |
  | - | - | - |
  | `browser_session_id` | `str` | Unique identifier for the browser session. browser\_session\_id starts with `pbs_`. |
  | `organization_id` | `str` | ID of the organization that owns this session |
  | `status` | `str \| None` | Current status of the browser session |
  | `runnable_type` | `str \| None` | Type of the current runnable associated with this session (workflow, task etc) |
  | `runnable_id` | `str \| None` | ID of the current runnable |
  | `timeout` | `int \| None` | Timeout in minutes for the session. Timeout is applied after the session is started. Defaults to 60 minutes. |
  | `browser_address` | `str \| None` | Url for connecting to the browser |
  | `app_url` | `str \| None` | Url for the browser session page |
  | `extensions` | `list["ad-blocker" \| "captcha-solver" \| Any] \| None` | A list of extensions installed in the browser session. |
  | `browser_type` | `"msedge" \| "chrome" \| "stealth-chromium" \| None` | The type of browser used for the session. |
  | `browser_profile_id` | `str \| None` | ID of the browser profile loaded into this session, if any. browser\_profile\_id starts with `bp_`. |
  | `generate_browser_profile` | `bool \| None` | Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile. |
  | `vnc_streaming_supported` | `bool \| None` | Whether the browser session supports VNC streaming |
  | `download_path` | `str \| None` | The path where the browser session downloads files |
  | `downloaded_files` | `list[FileInfo] \| None` | The list of files downloaded by the browser session |
  | `recordings` | `list[FileInfo] \| None` | The list of video recordings from the browser session |
  | `started_at` | `datetime \| None` | Timestamp when the session was started |
  | `completed_at` | `datetime \| None` | Timestamp when the session was completed |
  | `created_at` | `datetime` | Timestamp when the session was created (the timestamp for the initial request) |
  | `modified_at` | `datetime` | Timestamp when the session was last modified |
  | `deleted_at` | `datetime \| None` | Timestamp when the session was deleted, if applicable |
</Accordion>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import asyncio

  from skyvern import Skyvern


  async def main() -> None:
      skyvern = Skyvern(api_key="YOUR_API_KEY")
      result = await skyvern.update_browser_session(
          browser_session_id="pbs_123",
          generate_browser_profile=True,
      )
      print(result)


  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { Skyvern } from "@skyvern/client";

  const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
  const result = await skyvern.updateBrowserSession("pbs_123", { generate_browser_profile: true });
  console.log(result);
  ```
</CodeGroup>

***

## extend\_browser\_session

Extend a live browser session by a number of minutes. Sessions are created with a timeout of at most 240 minutes and can be extended, one or more times, up to a total lifetime of 360 minutes (6 hours). The minutes are added to the session's current deadline. A request for more than the remaining headroom is granted the remainder, and the response carries a warning. The response's `timeout` is the session's new total budget in minutes, counted from when the session started.

<Note>Python only: the TypeScript SDK has no equivalent.</Note>

<CodeGroup>
  ```python Python theme={null}
  await skyvern.extend_browser_session(
      browser_session_id: str,
      *,
      additional_minutes: int,
  ) -> BrowserSessionResponse
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `browser_session_id` | — | `str` | Yes | — | The ID of the browser session. browser\_session\_id starts with `pbs_` |
| `additional_minutes` | — | `int` | Yes | — | Minutes to add to the session's current deadline. A session can be extended, one or more times, up to a total lifetime of 360 minutes (6 hours) counted from when it started; a request for more than the remaining headroom is granted the remainder and the response carries a warning. |

**Returns** `BrowserSessionResponse`

<Accordion title="BrowserSessionResponse fields">
  | Field | Type | Description |
  | - | - | - |
  | `browser_session_id` | `str` | Unique identifier for the browser session. browser\_session\_id starts with `pbs_`. |
  | `organization_id` | `str` | ID of the organization that owns this session |
  | `status` | `str \| None` | Current status of the browser session |
  | `runnable_type` | `str \| None` | Type of the current runnable associated with this session (workflow, task etc) |
  | `runnable_id` | `str \| None` | ID of the current runnable |
  | `timeout` | `int \| None` | Timeout in minutes for the session. Timeout is applied after the session is started. Defaults to 60 minutes. |
  | `browser_address` | `str \| None` | Url for connecting to the browser |
  | `app_url` | `str \| None` | Url for the browser session page |
  | `extensions` | `list["ad-blocker" \| "captcha-solver" \| Any] \| None` | A list of extensions installed in the browser session. |
  | `browser_type` | `"msedge" \| "chrome" \| "stealth-chromium" \| None` | The type of browser used for the session. |
  | `browser_profile_id` | `str \| None` | ID of the browser profile loaded into this session, if any. browser\_profile\_id starts with `bp_`. |
  | `generate_browser_profile` | `bool \| None` | Whether this session's browser profile will be saved when it ends so it can become a reusable browser profile. |
  | `vnc_streaming_supported` | `bool \| None` | Whether the browser session supports VNC streaming |
  | `download_path` | `str \| None` | The path where the browser session downloads files |
  | `downloaded_files` | `list[FileInfo] \| None` | The list of files downloaded by the browser session |
  | `recordings` | `list[FileInfo] \| None` | The list of video recordings from the browser session |
  | `started_at` | `datetime \| None` | Timestamp when the session was started |
  | `completed_at` | `datetime \| None` | Timestamp when the session was completed |
  | `created_at` | `datetime` | Timestamp when the session was created (the timestamp for the initial request) |
  | `modified_at` | `datetime` | Timestamp when the session was last modified |
  | `deleted_at` | `datetime \| None` | Timestamp when the session was deleted, if applicable |
</Accordion>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import asyncio

  from skyvern import Skyvern


  async def main() -> None:
      skyvern = Skyvern(api_key="YOUR_API_KEY")
      result = await skyvern.extend_browser_session(
          browser_session_id="pbs_123",
          additional_minutes=60,
      )
      print(result)


  asyncio.run(main())
  ```
</CodeGroup>

***

## close\_browser\_session

Close a session. Once closed, the session cannot be used again.

<CodeGroup>
  ```python Python theme={null}
  await skyvern.close_browser_session(browser_session_id: str) -> Any | None
  ```

  ```typescript TypeScript theme={null}
  skyvern.closeBrowserSession(browserSessionId: string): Promise<unknown>
  ```
</CodeGroup>

**Parameters**

| Parameter | TypeScript | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `browser_session_id` | `browserSessionId` | `str` | Yes | — | The ID of the browser session to close. completed\_at will be set when the browser session is closed. browser\_session\_id starts with `pbs_` |

**Returns** `Any \| None` · TypeScript `Promise<unknown>`

**Example**

<CodeGroup>
  ```python Python theme={null}
  import asyncio

  from skyvern import Skyvern


  async def main() -> None:
      skyvern = Skyvern(api_key="YOUR_API_KEY")
      result = await skyvern.close_browser_session(browser_session_id="pbs_123")
      print(result)


  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { Skyvern } from "@skyvern/client";

  const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
  const result = await skyvern.closeBrowserSession("pbs_123");
  console.log(result);
  ```
</CodeGroup>


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