Create Browser Session | Browser Use Cloud Docs

Create a new browser session.

Pricing: Browser sessions are charged per hour with tiered pricing:

Pay As You Go users: $0.06/hour
Business/Scaleup subscribers: $0.03/hour (50% discount)

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

Create a new browser session. **Pricing:** Browser sessions are charged per hour with tiered pricing: - Pay As You Go users: $0.06/hour - Business/Scaleup subscribers: $0.03/hour (50% discount) 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

Authentication

X-Browser-Use-API-Keystring

API Key authentication via header

Request

This endpoint expects an object.

profileIdstring or nullOptionalformat: "uuid"

The ID of the profile to use for the session

proxyCountryCodeenum or nullOptional

Country code for proxy location.

timeoutintegerOptionalDefaults to 60

The timeout for the session in minutes. All users can use up to 240 minutes (4 hours). Pay As You Go users are charged $0.06/hour, subscribers get 50% off.

browserScreenWidthinteger or nullOptional320-6144

Custom screen width in pixels for the browser.

browserScreenHeightinteger or nullOptional320-3456

Custom screen height in pixels for the browser.

allowResizingbooleanOptionalDefaults to false

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

Response

Successful Response

idstringformat: "uuid"

Unique identifier for the session

statusenum

Current status of the session (active/stopped)

Allowed values:

timeoutAtdatetime

Timestamp when the session will timeout

startedAtdatetime

Timestamp when the session was created and started

liveUrlstring or null

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

cdpUrlstring or null

Chrome DevTools Protocol URL for browser automation

finishedAtdatetime or null

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

1	import requests
2
3	url = "https://api.browser-use.com/api/v2/browsers"
4
5	payload = {}
6	headers = {
7	"X-Browser-Use-API-Key": "<apiKey>",
8	"Content-Type": "application/json"
9	}
10
11	response = requests.post(url, json=payload, headers=headers)
12
13	print(response.json())

1	{
2	"id": "string",
3	"status": "active",
4	"timeoutAt": "2024-01-15T09:30:00Z",
5	"startedAt": "2024-01-15T09:30:00Z",
6	"liveUrl": "string",
7	"cdpUrl": "string",
8	"finishedAt": "2024-01-15T09:30:00Z"
9	}

Authentication

Request

Response

Errors