Create Browser Session

Create a new browser session.

Pricing: Browser sessions are charged at $0.02/hour for all users.

The full rate is charged upfront when the session starts. When you stop the session, any unused time is automatically refunded proportionally.

Billing is rounded up to the minute (minimum 1 minute). For example, if you stop a session after 30 minutes, you’ll be refunded half the charged amount.

Session Limits:

All users: Up to 4 hours per session

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: 'us',
    metadata: {},
    timeout: 60,
    browserScreenWidth: 3232,
    browserScreenHeight: 1888,
    allowResizing: false,
    pdfRendererEnabled: true,
    solveCaptchas: true,
    customProxy: {
      host: '<string>',
      port: 32768,
      username: '<string>',
      password: '<string>',
      ignoreCertErrors: false,
      caBundle: '<string>',
      caBundleUrl: '<string>'
    },
    enableRecording: false,
    extensionIds: []
  })
};

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

curl --request POST \
  --url https://api.browser-use.com/api/v3/browsers \
  --header 'Content-Type: application/json' \
  --header 'X-Browser-Use-API-Key: <api-key>' \
  --data '
{
  "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "proxyCountryCode": "us",
  "metadata": {},
  "timeout": 60,
  "browserScreenWidth": 3232,
  "browserScreenHeight": 1888,
  "allowResizing": false,
  "pdfRendererEnabled": true,
  "solveCaptchas": true,
  "customProxy": {
    "host": "<string>",
    "port": 32768,
    "username": "<string>",
    "password": "<string>",
    "ignoreCertErrors": false,
    "caBundle": "<string>",
    "caBundleUrl": "<string>"
  },
  "enableRecording": false,
  "extensionIds": []
}
'

import requests

url = "https://api.browser-use.com/api/v3/browsers"

payload = {
    "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "proxyCountryCode": "us",
    "metadata": {},
    "timeout": 60,
    "browserScreenWidth": 3232,
    "browserScreenHeight": 1888,
    "allowResizing": False,
    "pdfRendererEnabled": True,
    "solveCaptchas": True,
    "customProxy": {
        "host": "<string>",
        "port": 32768,
        "username": "<string>",
        "password": "<string>",
        "ignoreCertErrors": False,
        "caBundle": "<string>",
        "caBundleUrl": "<string>"
    },
    "enableRecording": False,
    "extensionIds": []
}
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",
  "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",
  "agentSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "recordingUrl": "<string>",
  "metadata": {},
  "extensions": []
}

{
  "detail": "<string>"
}

{
  "detail": "Maximum session timeout is 4 hours (240 minutes)."
}

{
  "detail": "Profile not found"
}

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

{
  "detail": "Too many concurrent active sessions. Please wait for one to finish, kill one, or upgrade your plan."
}

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

default:us

Country code for proxy location. Defaults to US. Set to null to disable 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

metadata

Metadata · object | null

Labels for this browser. Up to 10 key-value pairs. Filterable on the browsers list and in the dashboard history.

Show child attributes

timeout

integer

default:60

The timeout for the session in minutes. All users can use up to 240 minutes (4 hours). Browser sessions are charged $0.02/hour.

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).

pdfRendererEnabled

boolean

default:true

Whether Chrome renders PDFs in a tab. Set to false to stop the in-tab render; the file is saved to the session's download directory either way.

solveCaptchas

boolean

default:true

Whether the browser detects and solves CAPTCHAs on its own. Set to false to handle CAPTCHAs yourself. Defaults to true.

customProxy

CustomProxy · object | null

Request model for creating a custom proxy.

Show child attributes

enableRecording

boolean

default:false

If True, enables session recording. Defaults to False.

extensionIds

string<uuid>[]

Up to 3 ready extensions from POST /api/v4/extensions to install before the browser starts.

Maximum array length: 3

Response

Successful Response

View model for representing a browser session in list views.

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

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

proxyCost

string

default:0

Cost of proxy usage in USD

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

browserCost

string

default:0

Cost of browser session hosting in USD

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

agentSessionId

string<uuid> | null

ID of the agent session that created this browser (None for standalone BaaS sessions)

recordingUrl

string | null

Presigned URL to download the session recording. Only populated on GET /browsers/{session_id}; always null in list responses.

metadata

Metadata · object

Caller-supplied labels set when the browser was created.

Show child attributes

extensions

BrowserExtensionView · object[]

Extensions installed in the browser, in the order of extensionIds.

Show child attributes

⌘I

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: 'us',
    metadata: {},
    timeout: 60,
    browserScreenWidth: 3232,
    browserScreenHeight: 1888,
    allowResizing: false,
    pdfRendererEnabled: true,
    solveCaptchas: true,
    customProxy: {
      host: '<string>',
      port: 32768,
      username: '<string>',
      password: '<string>',
      ignoreCertErrors: false,
      caBundle: '<string>',
      caBundleUrl: '<string>'
    },
    enableRecording: false,
    extensionIds: []
  })
};

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

curl --request POST \
  --url https://api.browser-use.com/api/v3/browsers \
  --header 'Content-Type: application/json' \
  --header 'X-Browser-Use-API-Key: <api-key>' \
  --data '
{
  "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "proxyCountryCode": "us",
  "metadata": {},
  "timeout": 60,
  "browserScreenWidth": 3232,
  "browserScreenHeight": 1888,
  "allowResizing": false,
  "pdfRendererEnabled": true,
  "solveCaptchas": true,
  "customProxy": {
    "host": "<string>",
    "port": 32768,
    "username": "<string>",
    "password": "<string>",
    "ignoreCertErrors": false,
    "caBundle": "<string>",
    "caBundleUrl": "<string>"
  },
  "enableRecording": false,
  "extensionIds": []
}
'

import requests

url = "https://api.browser-use.com/api/v3/browsers"

payload = {
    "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "proxyCountryCode": "us",
    "metadata": {},
    "timeout": 60,
    "browserScreenWidth": 3232,
    "browserScreenHeight": 1888,
    "allowResizing": False,
    "pdfRendererEnabled": True,
    "solveCaptchas": True,
    "customProxy": {
        "host": "<string>",
        "port": 32768,
        "username": "<string>",
        "password": "<string>",
        "ignoreCertErrors": False,
        "caBundle": "<string>",
        "caBundleUrl": "<string>"
    },
    "enableRecording": False,
    "extensionIds": []
}
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",
  "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",
  "agentSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "recordingUrl": "<string>",
  "metadata": {},
  "extensions": []
}

{
  "detail": "<string>"
}

{
  "detail": "Maximum session timeout is 4 hours (240 minutes)."
}

{
  "detail": "Profile not found"
}

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

{
  "detail": "Too many concurrent active sessions. Please wait for one to finish, kill one, or upgrade your plan."
}

Get Started

V3 guides and tutorials

Endpoints

Create Browser Session

Authorizations

Body

Response