Skip to main content
POST
/
browsers
Create Browser Session
const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    profileId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    proxyCountryCode: 'ad',
    timeout: 60,
    browserScreenWidth: 3232,
    browserScreenHeight: 1888,
    allowResizing: false,
    customProxy: {host: '<string>', port: 32768, username: '<string>', password: '<string>'}
  })
};

fetch('https://api.browser-use.com/api/v2/browsers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "active",
  "timeoutAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "liveUrl": "<string>",
  "cdpUrl": "<string>",
  "finishedAt": "2023-11-07T05:31:56Z",
  "proxyUsedMb": "0",
  "proxyCost": "0",
  "browserCost": "0"
}

Authorizations

​
X-Browser-Use-API-Key
string
header
required

Body

application/json

Request model for creating a browser session.

​
profileId
string<uuid> | null

The ID of the profile to use for the session

​
proxyCountryCode
enum<string> | null

Country code for proxy location.

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,
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
​
timeout
integer
default:60

The timeout for the session in minutes. All users can use up to 240 minutes (4 hours). Pay As You Go users are charged $0.06/hour, subscribers get 50% off.

​
browserScreenWidth
integer | null

Custom screen width in pixels for the browser.

Required range: 320 <= x <= 6144
​
browserScreenHeight
integer | null

Custom screen height in pixels for the browser.

Required range: 320 <= x <= 3456
​
allowResizing
boolean
default:false

Whether to allow the browser to be resized during the session (not recommended since it reduces stealthiness).

​
customProxy
CustomProxy · object

Request model for creating a custom proxy.

Response

Successful Response

View model for representing a browser session in list views.

​
id
string<uuid>
required

Unique identifier for the session

​
status
enum<string>
required

Current status of the session (active/stopped)

Available options:
active,
stopped
​
timeoutAt
string<date-time>
required

Timestamp when the session will timeout

​
startedAt
string<date-time>
required

Timestamp when the session was created and started

​
liveUrl
string | null

URL where the browser can be viewed live in real-time

​
cdpUrl
string | null

Chrome DevTools Protocol URL for browser automation

​
finishedAt
string<date-time> | null

Timestamp when the session was stopped (None if still active)

​
proxyUsedMb
string
default:0

Amount of proxy data used in MB

​
proxyCost
string
default:0

Cost of proxy usage in USD

​
browserCost
string
default:0

Cost of browser session hosting in USD