> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driver.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a session

> POST /v1/browser/session starts a Chrome and returns its CDP URL once it's reachable.

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](/docs/sessions/pools) instead.

<CodeGroup>
  ```bash cURL theme={"dark"}
  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"
    }'
  ```

  ```typescript TypeScript theme={"dark"}
  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();
  ```

  ```python Python theme={"dark"}
  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()
  ```
</CodeGroup>

## Response

```json theme={"dark"}
{
  "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`](/docs/sessions/lifecycle#get-a-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](/docs/options/browser-types).                                                                        |
| `country`       | string    | `US`                   | Two-letter code from [Countries](/docs/options/countries). Placement, network and locale follow it. See [Location](/docs/options/location).                              |
| `timezone`      | string    | chosen for the country | IANA name from that country's list on [Countries](/docs/options/countries).                                                                                              |
| `language`      | string    | chosen for the country | BCP-47 tag from that country's list on [Countries](/docs/options/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](/docs/options/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](/docs/options/proxies#dedicated-ips). See [Proxies](/docs/options/proxies). |
| `profile`       | object    |                        | `{ "name": "…", "persist": true }` loads and saves browser state. `persist` defaults to `false` (load only). See [Profiles](/docs/options/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](/docs/options/extensions).                                                                      |
| `nodeId`        | string    |                        | Run on the machine that served an earlier session. Overrides `country` and `type`. See [Node reuse](/docs/options/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](/docs/sessions/errors).

## Next

* [Connect over CDP](/docs/sessions/connect)
* [Lifecycle](/docs/sessions/lifecycle): get, list, label and stop sessions
* [Browser pools](/docs/sessions/pools): warm browsers with these options preset