Skip to main content
POST
/
task
curl -X POST "https://api.smooth.sh/api/v1/task" \
     -H "Content-Type: application/json" \
     -H "apikey: YOUR_API_KEY" \
     -d '{
       "task": "Go to hacker news and get the top 5 stories.",
       "device": "desktop",
       "max_steps": 32,
       "enable_recording": true
     }'
{
  "id": "<string>",
  "status": "waiting",
  "output": "<any>",
  "credits_used": 123,
  "credits_balance": 123,
  "device": "desktop",
  "live_url": "<string>",
  "recording_url": "<string>",
  "downloads_url": "<string>",
  "created_at": 123
}

Authorizations

​
apikey
string
header
required

Body

application/json

Run task request model.

​
task
string
required

The task to run.

​
response_model
object

If provided, the JSON schema describing the desired output structure.

​
url
string<uri> | null

The starting URL for the task. If not provided, the agent will start from a blank page.

​
metadata
object

A dictionary containing variables or parameters that will be passed to the agent.

​
agent
enum<string>
default:smooth

The agent to use for the task.

Available options:
smooth
​
max_steps
integer
default:32

Maximum number of steps the agent can take (min 2, max 128).

Required range: 2 <= x <= 128
​
device
enum<string>
default:desktop

Device type for the task. Default is mobile.

Available options:
desktop,
mobile
​
allowed_urls
string<uri>[]

List of URL patterns using wildcard syntax (e.g., https://*example.com/*) the agent is allowed to visit. If not provided, the agent can visit any URL.

​
enable_recording
boolean
default:true

Enable video recording of the task execution. Default is False

​
profile_id
string | null

Browser profile ID to use. Each profile maintains its own state, such as login credentials.

​
profile_read_only
boolean
default:false

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.

​
stealth_mode
boolean
default:true

Run the browser in stealth mode.

​
proxy_server
string | null

Proxy server address to route browser traffic through.

​
proxy_username
string | null

Proxy server username.

​
proxy_password
string | null

Proxy server password.

​
certificates
Certificates · object[]

List of client certificates to use when accessing secure websites.

​
use_adblock
boolean
default:true

Enable ad-blocking in the browser to improve performance and reduce distractions.

​
experimental_features
object

A dictionary of experimental features to enable or disable.

​
extensions
string[] | null

List of extension IDs to load into the browser for this task.

Response

Task successfully submitted. The initial response may have a status of 'waiting'.

Task response model.

​
id
string
required

The ID of the task.

​
status
enum<string>
required

The status of the task.

Available options:
waiting,
running,
done,
failed,
cancelled
​
output
any

The output of the task.

​
credits_used
integer | null

The amount of credits used to perform the task.

​
credits_balance
integer | null

The amount of credits remaining on the account.

​
device
enum<string> | null

The device type used for the task.

Available options:
desktop,
mobile
​
live_url
string | null

The URL to view and interact with the task execution.

​
recording_url
string | null

The URL to view the task recording.

​
downloads_url
string | null

The URL to download files generated during the task.

​
created_at
integer | null

The timestamp when the task was created.