--- title: "Create Browser Session" method: POST path: "/browsers" tags: ["Browsers"] --- # Create Browser 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` 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 ## Request body - CreateBrowserSessionRequest: Request model for creating a browser session. - `profileId` string, 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' - `metadata` object, nullable: Labels for this browser. Up to 10 key-value pairs. Filterable on the browsers list and in the dashboard history. - `timeout` integer: 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, nullable: Custom screen width in pixels for the browser. - `browserScreenHeight` integer, nullable: Custom screen height in pixels for the browser. - `allowResizing` boolean: Whether to allow the browser to be resized during the session (not recommended since it reduces stealthiness). - `pdfRendererEnabled` boolean: 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: Whether the browser detects and solves CAPTCHAs on its own. Set to false to handle CAPTCHAs yourself. Defaults to true. - `customProxy` CustomProxy: Request model for creating a custom proxy. - `host` string, required: Host of the proxy. - `port` integer, required: Port of the proxy. - `username` string, nullable: Username for proxy authentication. - `password` string, nullable: Password for proxy authentication. - `ignoreCertErrors` boolean: Ignore TLS certificate errors. Enable this if your proxy uses a self-signed or untrusted certificate (e.g. Burp Suite, corporate proxies). - `enableRecording` boolean: If True, enables session recording. Defaults to False. - `extensionIds` string[]: Up to 3 ready extensions from POST /api/v4/extensions to install before the browser starts. ## Response `201` Successful Response - BrowserSessionItemView: View model for representing a browser session in list views. - `id` string, 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) - `liveUrl` string, nullable: URL where the browser can be viewed live in real-time - `cdpUrl` string, nullable: Chrome DevTools Protocol URL for browser automation - `timeoutAt` string, date-time, required: Timestamp when the session will timeout - `startedAt` string, date-time, required: Timestamp when the session was created and started - `finishedAt` string, date-time, nullable: Timestamp when the session was stopped (None if still active) - `proxyUsedMb` string: Amount of proxy data used in MB - `proxyCost` string: Cost of proxy usage in USD - `browserCost` string: Cost of browser session hosting in USD - `agentSessionId` string, uuid, nullable: ID of the agent session that created this browser (None for standalone BaaS sessions) - `recordingUrl` string, nullable: Presigned URL to download the session recording. Only populated on `GET /api/v2/browsers/{id}`; always `null` in list responses. - `metadata` object: Caller-supplied labels set when the browser was created. - `extensions` BrowserExtensionView[]: Extensions installed in the browser, in the order of `extensionIds`. - `id` string, uuid, required: Extension ID from POST /api/v4/extensions - `runtimeId` string, required: Chromium extension ID, as in chrome-extension://{runtimeId}/ - `version` string, required: Version from the extension manifest ## Other responses - `402`: Insufficient credits, or the API key reached its monthly spend limit. - `403`: Session timeout limit exceeded (maximum 4 hours), or extensions are not available to this project - `404`: Profile or extension not found - `422`: Request validation failed - `429`: Too many concurrent active sessions --- [API](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4.md) · [All operations](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/llms.txt) · [OpenAPI document](https://skmtc.dev/browser-use/apis/browser-use-public-api-v4/revisions/cd7b1eee1102?raw)