Skip to main content
POST
/
sessions
Create Session
const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({persistMemory: true, keepAlive: true})
};

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

Authorizations

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

Body

application/json

Request model for creating a 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
​
startUrl
string | null

URL to navigate to when the session starts.

​
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
​
persistMemory
boolean
default:true

If True (default), tasks in this session share memory and history with each other, allowing follow-up tasks to continue from previous context. If False, each task runs as a standalone task without any previous task context.

​
keepAlive
boolean
default:true

If True (default), the browser session stays alive after tasks complete, allowing follow-up tasks. If False, the session is closed immediately after task completion. Set to False for simple one-off tasks to reduce session idle time.

​
customProxy
CustomProxy · object

Request model for creating a custom proxy.

Response

Successful Response

View model for representing a (browser) session.

​
id
string<uuid>
required

Unique identifier for the session

​
status
enum<string>
required

Current status of the session (active/stopped)

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

Timestamp when the session was created and started

​
persistMemory
boolean
required

Whether tasks in this session share memory and history with each other

​
keepAlive
boolean
required

Whether the browser session stays alive after tasks complete

​
liveUrl
string | null

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

​
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