> ## 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](https://skyvern.com/docs/sdk-reference/overview.md#request-options).

***

## create\_browser\_session

Create a browser session that persists across multiple runs

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

**Parameters**

**url** `str | None`

Optional URL to open when the standalone browser session starts.

Sent only when you pass it

**timeout** `int | None`

Timeout in minutes for the session. Timeout is applied after the session is started. Must be between 5 and 240. Defaults to 60.

Sent only when you pass it

**proxy\_location** `CreateBrowserSessionRequestProxyLocation | None`

Geographic Proxy location to route the browser traffic through. This is only available in Skyvern Cloud.

Sent only when you pass it

**proxy\_session\_id** `str | None`

Opaque Skyvern-managed proxy sticky-session id for pinned Residential ISP sessions.

Sent only when you pass it

**extensions** `Sequence[Extensions] | None`

A list of extensions to install in the browser session.

Sent only when you pass it

**browser\_type** `PersistentBrowserType | None`

The type of browser to use for the session.

Sent only when you pass it

**browser\_profile\_id** `str | None`

ID of a browser profile to load into this session (restores cookies, localStorage, etc.). browser\_profile\_id starts with `bp_`.

Sent only when you pass it

**generate\_browser\_profile** `bool | None`

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.

Sent only when you pass it

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

> [accordion] 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 |

**Example**

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

***

## get\_browser\_session

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

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

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

**Parameters**

**browser\_session\_id** `str` *required*

The ID of the browser session. browser\_session\_id starts with `pbs_`

TypeScript: `browserSessionId`

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

> [accordion] 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 |

**Example**

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

***

## get\_browser\_sessions

Get all active browser sessions for the organization

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

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

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

> [accordion] 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 |

**Example**

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

***

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

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

**Parameters**

**browser\_session\_id** `str` *required*

The ID of the browser session. browser\_session\_id starts with `pbs_`

TypeScript: `browserSessionId`

**generate\_browser\_profile** `bool` *required*

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

**Example**

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

***

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

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

```typescript TypeScript theme={null}
skyvern.extendBrowserSession(browserSessionId: string, request: ExtendBrowserSessionRequest): Promise<BrowserSessionResponse>
```

**Parameters**

**browser\_session\_id** `str` *required*

The ID of the browser session. browser\_session\_id starts with `pbs_`

TypeScript: `browserSessionId`

**additional\_minutes** `int` *required*

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` · TypeScript `Promise<BrowserSessionResponse>`

> [accordion] 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 |

**Example**

```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())
```

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

const skyvern = new Skyvern({ apiKey: "YOUR_API_KEY" });
const result = await skyvern.extendBrowserSession("pbs_123", { additional_minutes: 60 });
console.log(result);
```

***

## close\_browser\_session

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

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

**Parameters**

**browser\_session\_id** `str` *required*

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_`

TypeScript: `browserSessionId`

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

**Example**

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


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