Skip to main content

​
Setting up

Get your free API key and start running tasks in minutes.

Get your free API key

Unlock your free welcome credits. No credit card required.

​
Launch a task using the Python SDK

Launch your first task in 4 lines of code. 
# pip install smooth-py
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run("Go to google flights and find the cheapest flight from London to Paris today")

print(f"Live URL: {task.live_url()}")
print(f"Agent response: {task.result()}")
If Python is not your language of choice, check out our API Reference.

​
Request

All parameters available when running a task.
​
task
string
required
The task for the agent to execute.Example: Go to Google Flights and find the cheapest flight from London to Paris today
​
response_model
dict | BaseModel
If provided, enforces a structured output schema. It can be a dictionary describing a JSON schema or a Pydantic Model. Default: None.Example:
{
  "type": "object",
  "properties": {
    "output": {
      "type": "integer",
      "description": "The integer part of the result of the calculation"
    }
  }
}
​
agent
string
The agent that will run the task. Currently, only smooth is available. Default: smooth.Example: smooth
​
max_steps
int
The upper limit on the number of steps the agent can take during task execution. The range is from 2 to 128. Default: 32.Example: 64
​
device
string
The type of device for the task execution. Choose between mobile or desktop. Default: mobile.Example: desktop
​
enable_recording
boolean
Toggles the option to record a video of the task execution. Default: True.Example: True

​
Advanced Parameters

​
url
string
The starting URL for the task. If not provided, the agent will infer it from the task.Example: https://amazon.com
​
allowed_urls
list
List of allowed URL patterns using wildcard syntax. If None, all URLs are allowed.Example: [“google.com/*”, “*mydomain.*/*”]
​
metadata
dict
A dictionary containing variables or parameters that will be passed to the agent.Example: {"username": "my_username"}
​
files
list
A list of file ids to be passed to the agent.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 task will not be saved back to the profile. Default: False.
​
use_adblock
boolean
Enable adblock for the browser session. Default is True.
​
stealth_mode
boolean
Activates stealth mode for the browser, which helps in avoiding detection. Default: True.Example: True
​
proxy_server
string
The hostname or IP address of the proxy server that will be used for the session.Example: proxy.example.com
​
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.
task = client.run(
 ...,
 certificates=[{
   "file": open("my_cert.p12", "rb"),
   "password": "my_password"
 }]
)
​
additional_tools
dict
Additional tools to enable for the task. 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.
task = client.run(
 ...,
 additional_tools={
   "screenshot": {"full_page": True},
   "hover": None
 }
)
​
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.
​
experimental_features
dict
Experimental features to enable for the task.

​
Response

Returns a TaskHandle with the following attributes.
​
id()
method
Returns the ID of the task.
​
live_url()
method
Returns a live URL where you can see the agent in action.Set interactive=True to get an interactive view.Set embed=True to get an embeddable view (ideal for iframes).
​
result()
method
Waits for the task completion and returns a TaskResponse upon completion.
​
recording_url()
method
Waits for the task completion and returns a recording URL upon completion if enable_recording was enabled. You can use this link to download the video recording of the task. The video will be ready shortly after the task completes.
​
downloads_url()
method
Waits for the task completion and returns a URL of the archive containing the files downloaded during the execution. If no file was downloaded raises ApiError.
​
stop()
method
Cancel the task execution.

​
Waiting for task completion

Use result() to wait for task completion. 
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run("Go to google flights and find the cheapest flight from London to Paris today")

task_result = task.result()  # Waits for the agent response

if task_result.status == "done":
  print(f"Agent response: {task_result.output}")
  print(f"Total cost: ${task_result.credits_used * 0.01}")
else:
  print(f"There was an error: {task_result.error}")
Returns a TaskResponse with the following attributes.
​
id
string
The ID of the task.
​
status
string
The status of the task. One of: [“waiting”, “running”, “done”, “failed”]
​
output
any
The final response from the agent.
​
credits_used
int
The number of credits used. 1 credit corresponds to $0.01.
​
device
string
The device type used for the task. One of: [“mobile”, “desktop”]
​
created_at
number
The timestamp when the task was created.

​
Cancelling a running task

Use stop() to cancel a running task. 
from smooth import SmoothClient

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run("Go to google flights and find the cheapest flight from London to Paris today")

task.stop()  # Cancel the task execution

task_result = task.result()  # Waits for the agent response

assert task_result.status == "cancelled"