Browsers

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

Request

  • Base URL: https://api.browser-use.com/api/v4
  • URL: https://api.browser-use.com/api/v4/browsers
  • Auth: API key in header X-Browser-Use-API-Key

Request body

profileIdstring uuid nullable

The ID of the profile to use for the session

proxyCountryCode'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'
metadataobject nullable

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

timeoutinteger

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

browserScreenWidthinteger nullable

Custom screen width in pixels for the browser.

browserScreenHeightinteger nullable

Custom screen height in pixels for the browser.

allowResizingboolean

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

pdfRendererEnabledboolean

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.

solveCaptchasboolean

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

enableRecordingboolean

If True, enables session recording. Defaults to False.

extensionIdsstring[]

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

Response

Successful Response

idstring uuid required

Unique identifier for the session

status'active' | 'stopped' required

Enumeration of possible browser session states

Attributes: ACTIVE: Session is currently active and running (browser is running) STOPPED: Session has been stopped and is no longer active (browser is stopped)

liveUrlstring nullable

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

cdpUrlstring nullable

Chrome DevTools Protocol URL for browser automation

timeoutAtstring date-time required

Timestamp when the session will timeout

startedAtstring date-time required

Timestamp when the session was created and started

finishedAtstring date-time nullable

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

proxyUsedMbstring

Amount of proxy data used in MB

proxyCoststring

Cost of proxy usage in USD

browserCoststring

Cost of browser session hosting in USD

agentSessionIdstring uuid nullable

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

recordingUrlstring nullable

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

metadataobject

Caller-supplied labels set when the browser was created.

Changes

No recorded changes to this operation across all 1 revision of this API.