POST
/
api
/
v1
/
run-task
curl --request POST \
  --url https://api.browser-use.com/api/v1/run-task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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
}'
{
  "id": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

task: What should the agent do. You can try it out at https://cloud.browser-use.com/

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

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

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

use_proxy: 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: Country code for residential proxy. Must be one of: 'us', 'fr', 'it', 'jp', 'au', 'de', 'fi', 'ca'. Default is 'us'.

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

included_file_names: 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: Width of the browser viewport in pixels. Default is 1280.

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

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

Response

200
application/json

Successful Response

The response is of type object.