Create Browser

Provision a standalone browser. Billed upfront for the timeout window; unused time refunded on stop. Faithful port of the v2 create orchestration.

POST /browsers

Create Browser

JavaScript

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)

201

{
  "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

201

application/json

Successful Response

id · 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.