> ## 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 Browser Session

> Start a managed Chrome session and receive a CDP URL.

Create a browser session when you need explicit lifecycle control, session options, session history, or reconnect support.

## Create a Session

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.driver.dev/v1/browser/session" \
    -H "Authorization: Bearer $DRIVER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"type":"hosted"}'
  ```

  ```python Python theme={null}
  import os
  import requests

  resp = requests.post(
      "https://api.driver.dev/v1/browser/session",
      headers={
          "Authorization": f"Bearer {os.getenv('DRIVER_API_KEY')}",
          "Content-Type": "application/json",
      },
      json={"type": "hosted"},
  )
  resp.raise_for_status()
  session = resp.json()
  print(session["sessionId"], session["cdpUrl"])
  ```

  ```typescript TypeScript theme={null}
  import BrowsercashSDK from "@browsercash/sdk";

  const client = new BrowsercashSDK({
    apiKey: process.env.DRIVER_API_KEY!,
    baseURL: "https://api.driver.dev",
  });

  const session = await client.browser.session.create({ type: "hosted" });
  console.log(session.sessionId, session.cdpUrl);
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "sessionId": "example-session-id",
  "status": "active",
  "servedBy": "node-id",
  "createdAt": "2026-06-10T01:15:17.157Z",
  "stoppedAt": null,
  "cdpUrl": "wss://...",
  "note": null
}
```

## Session Options

| Parameter       | Type      | Description                                                                        |
| --------------- | --------- | ---------------------------------------------------------------------------------- |
| `type`          | string    | Use `hosted`.                                                                      |
| `country`       | string    | Two-letter ISO country code, such as `US`.                                         |
| `nodeId`        | string    | Create the session on a specific previously used hosted node. Overrides `country`. |
| `duration`      | integer   | Session duration in seconds. Must be greater than 60 and no more than 3600.        |
| `windowSize`    | string    | Initial browser dimensions as `WIDTHxHEIGHT`, such as `1920x1080`.                 |
| `proxyUrl`      | string    | SOCKS5 proxy URL for the session. Cannot be used with `nodeId`.                    |
| `profile`       | object    | Browser profile: `{ "name": "...", "persist": true }`.                             |
| `fast`          | boolean   | Attempts faster startup when the request is eligible.                              |
| `captchaSolver` | boolean   | Enables the built-in CAPTCHA solver for the session.                               |
| `extensionIds`  | string\[] | Chrome extension IDs to load. Requires extension access for your account.          |

<Note>
  Session notes are updated with `PATCH /v1/browser/session?sessionId=...`. Do not rely on `note` during create; current create responses return `note: null`.
</Note>

## Example with Options

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.driver.dev/v1/browser/session" \
    -H "Authorization: Bearer $DRIVER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "country": "US",
      "type": "hosted",
      "duration": 600,
      "windowSize": "1920x1080",
      "profile": {
        "name": "my-profile",
        "persist": true
      }
    }'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.driver.dev/v1/browser/session",
      headers={
          "Authorization": f"Bearer {os.getenv('DRIVER_API_KEY')}",
          "Content-Type": "application/json",
      },
      json={
          "country": "US",
          "type": "hosted",
          "duration": 600,
          "windowSize": "1920x1080",
          "profile": {
              "name": "my-profile",
              "persist": True,
          },
      },
  )
  ```

  ```typescript TypeScript theme={null}
  const session = await client.browser.session.create({
    country: "US",
    type: "hosted",
    duration: 600,
    windowSize: "1920x1080",
    profile: {
      name: "my-profile",
      persist: true,
    },
  });
  ```
</CodeGroup>

## Next Steps

* [Use a Browser Session](/docs/fundamentals/using-a-browser-session)
* [Manage Browser Sessions](/docs/fundamentals/managing-a-browser-session)