120 lines
3.5 KiB
Plaintext
120 lines
3.5 KiB
Plaintext
|
---
|
|||
|
|
title: Browser Sessions
|
|||
|
|
subtitle: Maintain live browser state between API calls
|
|||
|
|
slug: sdk-reference/browser-sessions
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
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](/optimization/browser-sessions).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## `create_browser_session`
|
|||
|
|
|
|||
|
|
Spin up a new cloud browser session.
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
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"`. |
|
|||
|
|
|
|||
|
|
### 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
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
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)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## `get_browser_session`
|
|||
|
|
|
|||
|
|
Get the status and details of a session.
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
session = await client.get_browser_session("pbs_abc123")
|
|||
|
|
print(session.status, session.browser_address)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Parameters
|
|||
|
|
|
|||
|
|
| Parameter | Type | Required | Description |
|
|||
|
|
|-----------|------|----------|-------------|
|
|||
|
|
| `browser_session_id` | `str` | Yes | The session ID. |
|
|||
|
|
|
|||
|
|
### Returns `BrowserSessionResponse`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## `get_browser_sessions`
|
|||
|
|
|
|||
|
|
List all active browser sessions.
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
sessions = await client.get_browser_sessions()
|
|||
|
|
for s in sessions:
|
|||
|
|
print(f"{s.browser_session_id} — {s.status}")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Returns `list[BrowserSessionResponse]`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## `close_browser_session`
|
|||
|
|
|
|||
|
|
Close a browser session and release its resources.
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
await client.close_browser_session("pbs_abc123")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Parameters
|
|||
|
|
|
|||
|
|
| Parameter | Type | Required | Description |
|
|||
|
|
|-----------|------|----------|-------------|
|
|||
|
|
| `browser_session_id` | `str` | Yes | The session ID to close. |
|
|||
|
|
|
|||
|
|
<Warning>
|
|||
|
|
Closing a session is irreversible. Any unsaved state (cookies, local storage) is lost unless you created a [browser profile](/sdk-reference/browser-profiles) from it.
|
|||
|
|
</Warning>
|