Create Session

Create a session and/or dispatch a task.

• Without session_id, without task: creates a new idle session (e.g. for file uploads).
• Without session_id, with task: creates a new session and dispatches the task.
• With session_id, with task: dispatches the task to an existing idle session.
• With session_id, without task: 422 — task is required when targeting an existing session.

If keep_alive is false (default), the session auto-stops when the task finishes. If keep_alive is true, the session stays idle after the task, ready for follow-ups.

POST /sessions

Create Session

JavaScript

const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    task: '<string>',
    model: 'bu-mini',
    sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    keepAlive: false,
    maxCostUsd: 123,
    profileId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    workspaceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    proxyCountryCode: 'us',
    outputSchema: {},
    enableScheduledTasks: false,
    enableRecording: false,
    skills: true,
    agentmail: true
  })
};

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

201

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "created",
  "model": "bu-mini",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "title": "<string>",
  "output": null,
  "outputSchema": {},
  "stepCount": 0,
  "lastStepSummary": "<string>",
  "isTaskSuccessful": true,
  "liveUrl": "<string>",
  "recordingUrls": [],
  "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "proxyCountryCode": "ad",
  "maxCostUsd": "<string>",
  "totalInputTokens": 0,
  "totalOutputTokens": 0,
  "proxyUsedMb": "0",
  "llmCostUsd": "0",
  "proxyCostUsd": "0",
  "browserCostUsd": "0",
  "totalCostUsd": "0",
  "screenshotUrl": "<string>",
  "agentmailEmail": "<string>"
}

Authorizations

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

Body

application/json

Unified request for creating a session or dispatching a task.

• Without session_id + without task: creates a new idle session (for file uploads, etc.)
• Without session_id + with task: creates a new session and dispatches the task
• With session_id + with task: dispatches the task to an existing idle session
• With session_id + without task: 422 (task required when dispatching to existing session)

task · string | null

model · enum<string> · default: bu-mini

Available options: bu-mini, bu-max, bu-ultra

sessionId · string<uuid> | null

keepAlive · boolean · default: false

maxCostUsd · number string

profileId · string<uuid> | null

workspaceId · string<uuid> | null

proxyCountryCode · enum<string> | null · default: us

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

outputSchema · Outputschema · object

enableScheduledTasks · boolean · default: false

enableRecording · boolean · default: false

skills · boolean · default: true

agentmail · boolean · default: true

Response

201

application/json

Successful Response

id · string<uuid> · required

status · enum<string> · required

Available options: created, idle, running, stopped, timed_out, error

model · enum<string> · required

Available options: bu-mini, bu-max, bu-ultra

createdAt · string<date-time> · required

updatedAt · string<date-time> · required

title · string | null

output · unknown

outputSchema · Outputschema · object

stepCount · integer · default: 0

lastStepSummary · string | null

isTaskSuccessful · boolean | null

liveUrl · string | null

recordingUrls · string[]

profileId · string<uuid> | null

workspaceId · string<uuid> | null

proxyCountryCode · enum<string> | null

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

maxCostUsd · string | null

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

totalInputTokens · integer · default: 0

totalOutputTokens · integer · default: 0

proxyUsedMb · string · default: 0

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

llmCostUsd · string · default: 0

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

proxyCostUsd · string · default: 0

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

browserCostUsd · string · default: 0

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

totalCostUsd · string · default: 0

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

screenshotUrl · string | null

agentmailEmail · string | null