Create a session

One browser on one machine for up to an hour. Every field is optional; the defaults give you a hosted Chrome in the US. If a few seconds of start-up is too slow, acquire from a browser pool instead.

curl -X POST https://api.driver.dev/v1/browser/session \
  -H "Authorization: Bearer $DRIVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "duration": 600,
    "windowSize": "1920x1080",
    "profile": { "name": "my-profile", "persist": true },
    "note": "price check, client X"
  }'

const res = await fetch("https://api.driver.dev/v1/browser/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DRIVER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country: "US",
    duration: 600,
    windowSize: "1920x1080",
    profile: { name: "my-profile", persist: true },
    note: "price check, client X",
  }),
});
if (!res.ok) throw new Error(`Driver ${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const session = await res.json();

r = requests.post(
    "https://api.driver.dev/v1/browser/session",
    headers={"Authorization": f"Bearer {os.environ['DRIVER_API_KEY']}"},
    json={
        "country": "US",
        "duration": 600,
        "windowSize": "1920x1080",
        "profile": {"name": "my-profile", "persist": True},
        "note": "price check, client X",
    },
)
r.raise_for_status()
session = r.json()

Response

{
  "sessionId": "0b1f5c1e6d3a4f7c9e2b8d4a6c1e3f5a",
  "status": "active",
  "servedBy": "adapt-ensure-swim",
  "createdAt": "2026-09-17T14:02:11.000Z",
  "stoppedAt": null,
  "cdpUrl": "wss://…",
  "note": "price check, client X"
}

The call blocks until Chrome is reachable (measured: two to three seconds), so cdpUrl is set and status is active. It gives up after 20 seconds on most machines, three minutes on the newest, with a 504. Set a client timeout of at least three minutes on this call; everything else answers within seconds. The browser opens on about:blank, or your url, with one context and one tab. If you get starting, poll GET /v1/browser/session until cdpUrl appears. Session ids are opaque (32 hex characters today); don’t validate the format. cdpUrl is a credential: anyone holding it can drive the browser.

Options

Field	Type	Default	What it does
`type`	string	`hosted`	`hosted`, `hosted_stealth` or `hosted_privacy`. See Browser types.
`country`	string	`US`	Two-letter code from Countries. Placement, network and locale follow it. See Location.
`timezone`	string	chosen for the country	IANA name from that country’s list on Countries.
`language`	string	chosen for the country	BCP-47 tag from that country’s list on Countries. US sessions are always `en-US`.
`duration`	integer	`3600`	Seconds until the session stops on its own, 60 to 3600 inclusive.
`url`	string		Opened right after launch.
`windowSize`	string	node default	Outer window size, `WIDTHxHEIGHT`. See Window size.
`displaySize`	string		Virtual display size, `WIDTHxHEIGHT`.
`proxyUrl`	string	Driver’s network	Your own `socks5://` or `socks5h://` URL, or `dedicated://…` for one of your dedicated IPs. See Proxies.
`profile`	object		`{ "name": "…", "persist": true }` loads and saves browser state. `persist` defaults to `false` (load only). See Profiles.
`captchaSolver`	boolean	`false`	Load Driver’s CAPTCHA solver.
`adblock`	boolean	`false`	Block ads.
`extensionIds`	string[]		Uploaded extension ids to load. Needs extension access. See Extensions.
`nodeId`	string		Run on the machine that served an earlier session. Overrides `country` and `type`. See Node reuse.
`browserCheck`	boolean	`false`	Run a browser validation check during creation.
`note`	string		Up to 256 characters, shown in the dashboard.

Unknown fields are a 400 (window_size is not supported by this endpoint), as are out-of-range values (duration: Too small: expected number to be >=60, note: Too big: expected string to have <=256 characters) and options that contradict each other: a timezone or language not listed for the country (Unsupported timezone "Europe/Berlin" for country US.), a country that doesn’t match your proxy’s exit, a proxy that can’t be reached. The message names the field.

Errors

Status	Meaning
`400`	Invalid or incompatible options; the message names the field.
`401`	Missing or invalid API key.
`402`	The workspace is out of credits.
`403`	Concurrency limit, or a feature your plan doesn’t include.
`429`	Too many requests.
`500`	Something failed on Driver’s side.
`503`	No browser capacity. Carries `Retry-After: 2` and `"code": "browser_capacity_unavailable"`.
`504`	A machine was selected but Chrome wasn’t reachable before the startup deadline (20 s, up to 3 min on some machines).

What to retry is on Errors.

Connect over CDP
Lifecycle: get, list, label and stop sessions
Browser pools: warm browsers with these options preset

Start

Browser sessions

Session options

Frameworks

Account

Create a session

Response

Options

Errors

Next

​Response

​Options

​Errors

​Next

Response

Options

Errors

Next