​
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 specific output structure. It can either 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"
    }
  }
}
If you set response_model, Smooth will see it, no need to include it in task.
​
agent
string
The agent that will run the task. Currently, only smooth is available. Default: smooth.Example: smooth
​
session_id
string
The browser session ID to be utilized. Each session retains its own state, including login credentials and cookies.Example: session_12345
​
max_steps
int
The upper limit on the number of steps the agent can take during task execution. The range is from 2 to 64. Default: 32.Example: 64
​
device
string
The type of device for the task execution. Choose between mobile or desktop. Default: mobile.Example: desktop
​
url
string
The starting URL for the task. If not provided, the agent will infer it from the task.Example: https://amazon.com
​
metadata
dict
A dictionary containing variables or parameters that will be passed to the agent.Example: {"username": "my_username"}
​
agent
string
The agent that will run the task. Currently, only smooth is available. Default: smooth.Example: smooth
​
enable_recording
boolean
Toggles the option to record a video of the task execution. Default: False.Example: True
​
stealth_mode
boolean
Activates stealth mode for the browser, which helps in avoiding detection. Default: False.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

​
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. You can use this link to download the video recording of the task. The video will be ready shortly after the task completes.
TaskResponse contains also live_url and recording_url to be compatible with the API structure. Use TaskHandle.live_url() and TaskHandle.recording_url() as they handle the underlying API polling for you.

​
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”]

​
Structured output

Smooth supports structured output, simply set the response_model field by passing either a Pydantic Model or a JSON schema. 
# pip install smooth-py
from smooth import SmoothClient
from pydantic import BaseModel

class MyStructuredOutput(BaseModel):
  my_output_data: list[int] = Field(description="A list of random numbers.")

smooth_client = SmoothClient(api_key="cmzr-YOUR_API_KEY")
task = smooth_client.run("Output five random numbers.", response_model=MyStructuredOutput)

# or
# ..., response_model = {
#   "type": "object",
#   "properties": {
#     "my_output_data": {
#       "description": "A list of random numbers.",
#       "items": {
#         "type": "integer"
#       },
#       "type": "array"
#     }
#   }
# }

print(f"Agent response: {task.result()}")