Create Browser

const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    browserProfileId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    screenWidth: 123,
    screenHeight: 123,
    customProxy: {
      host: '<string>',
      port: 32768,
      username: '<string>',
      password: '<string>',
      ignoreCertErrors: false
    },
    enableRecording: false,
    timeout: 60
  })
};

fetch('https://api-staging-ufcbwvyv9yifyyvc3.browser-use.com/api/v1/browsers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api-staging-ufcbwvyv9yifyyvc3.browser-use.com/api/v1/browsers \
  --header 'Content-Type: application/json' \
  --header 'X-Browser-Use-API-Key: <api-key>' \
  --data '
{
  "browserProfileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "screenWidth": 123,
  "screenHeight": 123,
  "customProxy": {
    "host": "<string>",
    "port": 32768,
    "username": "<string>",
    "password": "<string>",
    "ignoreCertErrors": false
  },
  "enableRecording": false,
  "timeout": 60
}
'

import requests

url = "https://api-staging-ufcbwvyv9yifyyvc3.browser-use.com/api/v1/browsers"

payload = {
    "browserProfileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "screenWidth": 123,
    "screenHeight": 123,
    "customProxy": {
        "host": "<string>",
        "port": 32768,
        "username": "<string>",
        "password": "<string>",
        "ignoreCertErrors": False
    },
    "enableRecording": False,
    "timeout": 60
}
headers = {
    "X-Browser-Use-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "cdpUrl": "<string>",
  "liveViewUrl": "<string>",
  "agentSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

browsers

Create Browser

const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    browserProfileId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    screenWidth: 123,
    screenHeight: 123,
    customProxy: {
      host: '<string>',
      port: 32768,
      username: '<string>',
      password: '<string>',
      ignoreCertErrors: false
    },
    enableRecording: false,
    timeout: 60
  })
};

fetch('https://api-staging-ufcbwvyv9yifyyvc3.browser-use.com/api/v1/browsers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api-staging-ufcbwvyv9yifyyvc3.browser-use.com/api/v1/browsers \
  --header 'Content-Type: application/json' \
  --header 'X-Browser-Use-API-Key: <api-key>' \
  --data '
{
  "browserProfileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "screenWidth": 123,
  "screenHeight": 123,
  "customProxy": {
    "host": "<string>",
    "port": 32768,
    "username": "<string>",
    "password": "<string>",
    "ignoreCertErrors": false
  },
  "enableRecording": false,
  "timeout": 60
}
'

import requests

url = "https://api-staging-ufcbwvyv9yifyyvc3.browser-use.com/api/v1/browsers"

payload = {
    "browserProfileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "screenWidth": 123,
    "screenHeight": 123,
    "customProxy": {
        "host": "<string>",
        "port": 32768,
        "username": "<string>",
        "password": "<string>",
        "ignoreCertErrors": False
    },
    "enableRecording": False,
    "timeout": 60
}
headers = {
    "X-Browser-Use-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "cdpUrl": "<string>",
  "liveViewUrl": "<string>",
  "agentSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

X-Browser-Use-API-Key

string

header

required

Body

application/json

Provision a browser. All fields optional; sensible defaults.

browserProfileId

string<uuid> | null

Start logged-in with this saved profile.

proxyCountryCode

enum<string> | null

Residential proxy country, e.g. 'us', 'de'. Null disables the proxy.

Available options:

ad,

ae,

af,

ag,

ai,

al,

am,

an,

ao,

aq,

ar,

as,

at,

au,

aw,

az,

ba,

bb,

bd,

be,

bf,

bg,

bh,

bi,

bj,

bl,

bm,

bn,

bo,

bq,

br,

bs,

bt,

bv,

bw,

by,

bz,

ca,

cc,

cd,

cf,

cg,

ch,

ci,

ck,

cl,

cm,

co,

cr,

cs,

cu,

cv,

cw,

cx,

cy,

cz,

de,

dj,

dk,

dm,

do,

dz,

ec,

ee,

eg,

eh,

er,

es,

et,

fi,

fj,

fk,

fm,

fo,

fr,

ga,

gd,

ge,

gf,

gg,

gh,

gi,

gl,

gm,

gn,

gp,

gq,

gr,

gs,

gt,

gu,

gw,

gy,

hk,

hm,

hn,

hr,

ht,

hu,

id,

ie,

il,

im,

in,

iq,

ir,

is,

it,

je,

jm,

jo,

jp,

ke,

kg,

kh,

ki,

km,

kn,

kp,

kr,

kw,

ky,

kz,

la,

lb,

lc,

li,

lk,

lr,

ls,

lt,

lu,

lv,

ly,

ma,

mc,

md,

me,

mf,

mg,

mh,

mk,

ml,

mm,

mn,

mo,

mp,

mq,

mr,

ms,

mt,

mu,

mv,

mw,

mx,

my,

mz,

na,

nc,

ne,

nf,

ng,

ni,

nl,

no,

np,

nr,

nu,

nz,

om,

pa,

pe,

pf,

pg,

ph,

pk,

pl,

pm,

pn,

pr,

ps,

pt,

pw,

py,

qa,

re,

ro,

rs,

ru,

rw,

sa,

sb,

sc,

sd,

se,

sg,

sh,

si,

sj,

sk,

sl,

sm,

sn,

so,

sr,

ss,

st,

sv,

sx,

sy,

sz,

tc,

td,

tf,

tg,

th,

tj,

tk,

tl,

tm,

tn,

to,

tr,

tt,

tv,

tw,

tz,

ua,

ug,

uk,

us,

uy,

uz,

va,

vc,

ve,

vg,

vi,

vn,

vu,

wf,

ws,

xk,

ye,

yt,

za,

zm,

zw

screenWidth

integer | null

Viewport width in px.

screenHeight

integer | null

Viewport height in px.

customProxy

StrictCustomProxy · object | null

Your own proxy; overrides proxyCountryCode.

Show child attributes

enableRecording

boolean

default:false

Record the session as an mp4.

timeout

integer

default:60

Minutes before auto-stop (max 240). Billed upfront, unused time refunded on stop.

Required range: 1 <= x <= 240

Response

Successful Response

string<uuid>

required

status

enum<string>

required

'active' (running) or 'stopped'.

Available options:

active,

stopped

createdAt

string<date-time>

required

cdpUrl

string | null

Chrome DevTools Protocol endpoint. Null until the browser is booted.

liveViewUrl

string | null

Watch the browser live in a tab. Null until booted.

agentSessionId

string<uuid> | null

The agent session that used this browser, if any.

Cancel Browsercode Queued Turn

List Browsers

⌘I

Overview

Agents

Browsers

Agent Workspaces (Files)

Account

Create Browser

Authorizations

Body

Response