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

from smooth import SmoothClient

client = SmoothClient()

with client.session() as session:
    session.run_task("Search for flights from NYC to LA")
    data = session.extract(schema)
    session.run_task("Select the cheapest option")
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.
​
url
string
The starting URL for the session. If not provided, the browser will start on a blank page.Example: https://amazon.com
​
device
string
The type of device for the session. Choose between mobile or desktop. Default: mobile.Example: desktop
​
enable_recording
boolean
Toggles the option to record a video of the session. Default: True.
​
agent
string
The agent that will run tasks in this session. Currently, only smooth is available. Default: smooth.

​
Advanced Parameters

​
allowed_urls
list
List of allowed URL patterns using wildcard syntax. If None, all URLs are allowed.Example: ["google.com/*", "*mydomain.*//*"]
​
files
list
A list of file ids to be passed to the session.Check out our guide on File uploads.
​
profile_id
string
The browser profile ID to be utilized. Each profile retains its own state, including login credentials and cookies.Example: profile_12345
​
profile_read_only
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.
​
use_adblock
boolean
Enable adblock for the browser session. Default: True.
​
stealth_mode
boolean
Activates stealth mode for the browser, which helps in avoiding detection. Default: False.
​
proxy_server
string
The hostname or IP address of the proxy server that will be used for the session.Set to "self" to route traffic through your own IP address. See Use My IP for details.Example: proxy.example.com or self
​
proxy_username
string
The username for authenticating with the proxy server, if authentication is required.Example: user123
​
proxy_password
string
The password for authenticating with the proxy server, if authentication is required.Example: password123
​
certificates
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.
with client.session(
   certificates=[{
     "file": open("my_cert.p12", "rb"),
     "password": "my_password"
   }]
) as session:
   ...
​
additional_tools
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.
with client.session(
   additional_tools={
     "screenshot": {"full_page": True},
     "hover": None
   }
) as session:
   ...
​
custom_tools
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.
​
extensions
list
A list of browser extension paths to load into the session.See the Custom Extensions page for more details.
​
show_cursor
boolean
Show the cursor in the browser during the session. Useful for debugging or recordings. Default: False.
​
experimental_features
dict
Experimental features to enable for the session.

​
Response

Returns a SessionHandle with the following methods.

​
Session Methods

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

​
Status Methods

​
id()
method
Returns the ID of the session.
​
live_url()
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).
​
recording_url()
method
Returns a recording URL if enable_recording was enabled. You can use this link to download the video recording of the session.
​
downloads_url()
method
Returns a URL of the archive containing the files downloaded during the session. If no file was downloaded raises ApiError.
​
result()
method
Returns a SessionResponse with session information.

​
Session Response

The result() method returns an object with the following attributes.
​
id
string
The ID of the session.
​
status
string
The status of the session.
​
credits_used
int
The number of credits used. 1 credit corresponds to $0.01.
​
created_at
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: 
from smooth import SmoothClient

client = SmoothClient()

with client.session(url="https://flights.example.com") as session:
    # Step 1: Let the agent search for flights
    session.run_task("Search for one-way flights from NYC to LA on March 15")

    # Step 2: Extract the results
    flights = session.extract({
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "airline": {"type": "string"},
                "price": {"type": "number"}
            }
        }
    })

    # Step 3: Use the data to guide the next action
    cheapest = min(flights, key=lambda f: f["price"])
    session.run_task(f"Select the {cheapest['airline']} flight for ${cheapest['price']}")

    # Step 4: Get session info
    print(f"Credits used: {session.result().credits_used}")

​
Manual Session Management

If you’re not using the with statement, you must close the session manually. 
from smooth import SmoothClient

client = SmoothClient()

session = client.session()

try:
    session.run_task("Do something")
    session.run_task("Do something else")
finally:
    session.close()  # Always close the session

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