A browser session is a persistent browser instance that stays alive between API calls. Use sessions to chain multiple tasks in the same browser without losing cookies, local storage, or login state.
For conceptual background, see Browser Sessions.
Python uses snake_case (e.g., create_browser_session); TypeScript uses camelCase (e.g., createBrowserSession). Parameter tables show Python names. TypeScript names are the camelCase equivalents.
session = await client.create_browser_session(timeout=60)
print(session.browser_session_id) # pbs_abc123
Parameters
| Parameter | Type | Required | Default | Description |
|---|
timeout | int | No | 60 | Session timeout in minutes (5–1440). Timer starts after the session is ready. |
proxy_location | ProxyLocation | No | None | Route browser traffic through a geographic proxy. |
extensions | list[Extensions] | No | None | Browser extensions to install. Options: "ad-blocker", "captcha-solver". |
browser_type | PersistentBrowserType | No | None | Browser type. Options: "chrome", "msedge". |
browser_profile_id | str | No | None | Load a browser profile (cookies, localStorage) into this session. ID starts with bpf_. |
request_options | RequestOptions | No | | Per-request configuration (see below). |
Returns BrowserSessionResponse
| Field | Type | Description |
|---|
browser_session_id | str | Unique ID. Starts with pbs_. |
status | str | None | Current session status. |
browser_address | str | None | CDP address for connecting to the browser. |
app_url | str | None | Link to the live browser view in the Cloud UI. |
timeout | int | None | Configured timeout in minutes. |
started_at | datetime | None | When the session became ready. |
created_at | datetime | When the session was requested. |
Example: Chain multiple tasks in one session
session = await client.create_browser_session()
# Step 1: Log in
await client.run_task(
prompt="Log in with username demo@example.com",
url="https://app.example.com/login",
browser_session_id=session.browser_session_id,
wait_for_completion=True,
)
# Step 2: Extract data (same browser, already logged in)
result = await client.run_task(
prompt="Go to the invoices page and extract all invoice numbers",
browser_session_id=session.browser_session_id,
wait_for_completion=True,
)
print(result.output)
# Clean up
await client.close_browser_session(session.browser_session_id)
Request options
Override timeout, retries, or headers for this call by passing request_options (Python) or a second options argument (TypeScript).
from skyvern.client.core import RequestOptions
request_options=RequestOptions(
timeout_in_seconds=120,
max_retries=3,
additional_headers={"x-custom-header": "value"},
)
| Option (Python) | Option (TypeScript) | Type | Description |
|---|
timeout_in_seconds | timeoutInSeconds | int / number | HTTP timeout in seconds. |
max_retries | maxRetries | int / number | Retry count. |
additional_headers | headers | dict / Record<string, string> | Extra headers. |
additional_query_parameters | - | dict | Extra query parameters. |
additional_body_parameters | - | dict | Extra body parameters. |
| - | abortSignal | AbortSignal | Signal to cancel the request. |
| - | apiKey | string | Override API key. |
