Skip to main content
Browser sessions allow you to run multiple sequential tasks in a single browser instance. This enables you to break complex workflows into smaller, more reliable steps.

Creating a Session

When using the with statement, the session is automatically closed when the block exits. Otherwise, you must call session.close() manually.

Request

All parameters available when creating a session.
string
The starting URL for the session. If not provided, the browser will start on a blank page.Example: https://amazon.com
string
The type of device for the session. Choose between mobile or desktop. Default: mobile.Example: desktop
boolean
Toggles the option to record a video of the session. Default: True.
string
The agent that will run tasks in this session. Currently, only smooth is available. Default: smooth.

Advanced Parameters

list
List of allowed URL patterns using wildcard syntax. If None, all URLs are allowed.Example: ["google.com/*", "*mydomain.*//*"]
list
A list of file ids to be passed to the session.Check out our guide on File uploads.
string
The browser profile ID to be utilized. Each profile retains its own state, including login credentials and cookies. You must create the profile first using client.create_profile(). See Browser Profiles.Example: profile_12345
boolean
If true, the profile specified by profile_id will be loaded in read-only mode. Changes made during the session will not be saved back to the profile. Default: False.
boolean
Enable adblock for the browser session. Default: True.
boolean
Activates stealth mode for the browser, which helps in avoiding detection. Default: False.
string
The hostname or IP address of the proxy server that will be used for the session.Set to "self" to create a P2P tunnel through your machine, routing traffic via your IP and enabling access to localhost. See P2P Tunnel for details.Example: proxy.example.com or self
string
The username for authenticating with the proxy server, if authentication is required.Example: user123
string
The password for authenticating with the proxy server, if authentication is required.Example: password123
list
List of client certificates to use when accessing secure websites. Each certificate is a dictionary with the following fields:
  • file: p12 file object to be uploaded (e.g., open(‘my_cert.p12’, ‘rb’));
  • password (optional): The password for the certificate file, if applicable.
dict
Additional tools to enable for tasks in this session. Each tool is a {tool_name: tool_kwargs} pair. Use tool_kwargs = None for the default configuration of any tool.See the Tools page for a complete list of available tools and their configuration options.
list
A list of custom Python functions that the agent can call during task execution. Custom tools run in your local environment and can be used for OTP handling, human-in-the-loop scenarios, database operations, API integrations, and more.See the Custom Tools page for detailed documentation and examples.
list
A list of browser extension paths to load into the session.See the Custom Extensions page for more details.
boolean
Show the cursor in the browser during the session. Useful for debugging or recordings. Default: False.
dict
Experimental features to enable for the session.

Response

Returns a SessionHandle with the following methods.

Session Methods

method
Run an agent task within the session. See Run Task for full documentation.
method
Navigate to a specific URL deterministically. See Goto for full documentation.
method
Extract structured data from the current page. See Extract for full documentation.
method
Execute JavaScript in the browser context. See Evaluate JS for full documentation.
method
Close the session and save any profile changes. Automatically called when using the with statement.

Status Methods

method
Returns the ID of the session.
method
Returns a live URL where you can see the browser in action.Set interactive=True to get an interactive view.Set embed=True to get an embeddable view (ideal for iframes).
method
Returns a recording URL if enable_recording was enabled. You can use this link to download the video recording of the session.
method
Returns a URL of the archive containing the files downloaded during the session. If no file was downloaded raises ApiError.
method
Returns a SessionResponse with session information.

Session Response

The result() method returns an object with the following attributes.
string
The ID of the session.
string
The status of the session.
int
The number of credits used. 1 credit corresponds to $0.01.
number
The timestamp when the session was created.

Writing Multi-Step Workflow

Here’s an example of a multi-step browser automation workflow using a session:

Manual Session Management

If you’re not using the with statement, you must close the session manually.

Core Session Methods

Run Task

Run an agent task within the session. The agent will perform the task autonomously starting from the current page state.

Goto

Navigate to a specific URL deterministically. Use this when you know exactly where you need to go.

Extract

Extract structured data from the current page. Define a schema and get back typed data.

Evaluate JS

Execute JavaScript in the browser context. Useful for advanced interactions or reading page state.