Simple Task

For complex multi-step workflows or when you need more control, see Session Workflows.

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. Under the hood, client.run() creates a browser session, runs the task, and returns the result.

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

string

required

The task for the agent to execute.Example: Go to Google Flights and find the cheapest flight from London to Paris today

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"
    }
  }
}

string

The agent that will run the task. Currently, only smooth is available. Default: smooth.Example: smooth

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

string

The type of device for the task execution. Choose between mobile or desktop. Default: mobile.Example: desktop

boolean

Toggles the option to record a video of the task execution. Default: True.Example: True

Advanced Parameters

string

The starting URL for the task. If not provided, the agent will infer it from the task.Example: https://amazon.com

list

List of allowed URL patterns using wildcard syntax. If None, all URLs are allowed.Example: [“google.com/*”, “*mydomain.*/*”]

dict

A dictionary containing variables or parameters that will be passed to the agent.Example: {"username": "my_username"}

list

A list of file ids to be passed to the agent.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 task will not be saved back to the profile. Default: False.

boolean

Enable adblock for the browser session. Default is True.

boolean

Activates stealth mode for the browser, which helps in avoiding detection. Default: True.Example: True

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.

task = client.run(
 ...,
 certificates=[{
   "file": open("my_cert.p12", "rb"),
   "password": "my_password"
 }]
)

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
 }
)

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.

dict

Experimental features to enable for the task.

Response

Returns a TaskHandle with the following attributes.

method

Returns the ID of the task.

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

method

Waits for the task completion and returns a TaskResponse upon completion.

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.

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.

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.

string

The ID of the task.

string

The status of the task. One of: [“waiting”, “running”, “done”, “failed”]

any

The final response from the agent.

int

The number of credits used. 1 credit corresponds to $0.01.

string

The device type used for the task. One of: [“mobile”, “desktop”]

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"

Getting started

Automation SDK

Browser Profiles

Tools

Features

Use cases

Setting up

Get your free API key

Launch a task using the Python SDK

Request

Advanced Parameters

Response

Waiting for task completion

Cancelling a running task

​Setting up

Get your free API key

​Launch a task using the Python SDK

​Request

​Advanced Parameters

​Response

​Waiting for task completion

​Cancelling a running task

Setting up

Launch a task using the Python SDK

Request

Advanced Parameters

Response

Waiting for task completion

Cancelling a running task