POST
/
api
/
v1
/
run-task
import requests

url = "https://api.browser-use.com/api/v1/run-task"

payload = {
    "task": "<string>",
    "secrets": {},
    "allowed_domains": ["<string>"],
    "save_browser_data": True,
    "structured_output_json": "<string>",
    "llm_model": "gpt-4o",
    "use_adblock": True,
    "use_proxy": True,
    "proxy_country_code": "us",
    "highlight_elements": True,
    "included_file_names": ["<string>"],
    "browser_viewport_width": 123,
    "browser_viewport_height": 123,
    "max_agent_steps": 123,
    "enable_public_share": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

{
  "id": "task_1234567890abcdef"
}

Creates a new browser automation task and returns the task ID that can be used to track progress.

​
Request Body

​
task
string
required

Instructions for what the agent should do. You can try it out at https://cloud.browser-use.com/

​
secrets
object

Dictionary of secrets to be used by the agent. Secrets are safely encrypted before storing in the database.

​
allowed_domains
array

List of domains that the agent is allowed to visit. If not set, the agent will be allowed to visit all domains (not recommended if you are using secrets).

​
save_browser_data
boolean
default:"false"

If set to True, the browser cookies and other data will be saved. Cookies are safely encrypted before storing in the database.

​
structured_output_json
string

If set, the agent will use this JSON schema as the output model (see example here: https://docs.browser-use.com/cloud/implementation#structured-output-example).

​
llm_model
string
default:"gpt-4.1"

LLM model to use. Available options:

  • gpt-4o
  • gpt-4o-mini
  • gpt-4.1
  • gpt-4.1-mini
  • gemini-2.5-flash
  • claude-sonnet-4-20250514
​
use_adblock
boolean
default:"true"

If set to True, the agent will use an adblocker.

​
use_proxy
boolean
default:"true"

If set to True, the agent will use a (mobile) proxy. Note that proxy is required for captcha solving, so if you disable proxy, you will not be able to solve captchas.

​
proxy_country_code
string
default:"us"

Country code for residential proxy. Must be one of: ‘us’, ‘fr’, ‘it’, ‘jp’, ‘au’, ‘de’, ‘fi’, ‘ca’. Default is ‘us’.

​
highlight_elements
boolean
default:"true"

If set to True, the agent will highlight the elements on the page.

​
included_file_names
array

File names to include in the task (note: use uploads/presigned-url endpoint to upload the files first!). E.g. [‘file1.txt’, ‘file2.csv’]

​
browser_viewport_width
integer
default:"1280"

Width of the browser viewport in pixels. Default is 1280.

​
browser_viewport_height
integer
default:"960"

Height of the browser viewport in pixels. Default is 960.

​
max_agent_steps
integer
default:"75"

Maximum number of agent steps to take. Default is 75. Maximum is 200.

​
enable_public_share
boolean
default:"false"

If set to True, enables public sharing of the task execution. When enabled, a public_share_url will be generated that allows others to view the task results without authentication.

​
Response

​
id
string

The unique identifier for the created task.

import requests

url = "https://api.browser-use.com/api/v1/run-task"

payload = {
    "task": "<string>",
    "secrets": {},
    "allowed_domains": ["<string>"],
    "save_browser_data": True,
    "structured_output_json": "<string>",
    "llm_model": "gpt-4o",
    "use_adblock": True,
    "use_proxy": True,
    "proxy_country_code": "us",
    "highlight_elements": True,
    "included_file_names": ["<string>"],
    "browser_viewport_width": 123,
    "browser_viewport_height": 123,
    "max_agent_steps": 123,
    "enable_public_share": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

{
  "id": "task_1234567890abcdef"
}