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.comstring
The type of device for the session. Choose between
mobile or desktop. Default: mobile.Example: desktopboolean
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_12345boolean
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 selfstring
The username for authenticating with the proxy server, if authentication is required.Example:
user123string
The password for authenticating with the proxy server, if authentication is required.Example:
password123list
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 aSessionHandle with the following methods.
Session Methods
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
Theresult() 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 thewith 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.