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

​
Create a Session

curl -X POST "https://api.driver.dev/v1/browser/session" \
  -H "Authorization: Bearer $DRIVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"hosted"}'

​
Response

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

​
Session Options

ParameterTypeDescription
typestringUse hosted.
countrystringTwo-letter ISO country code, such as US.
nodeIdstringCreate the session on a specific previously used hosted node. Overrides country.
durationintegerSession duration in seconds. Must be greater than 60 and no more than 3600.
windowSizestringInitial browser dimensions as WIDTHxHEIGHT, such as 1920x1080.
proxyUrlstringSOCKS5 proxy URL for the session. Cannot be used with nodeId.
profileobjectBrowser profile: { "name": "...", "persist": true }.
fastbooleanAttempts faster startup when the request is eligible.
captchaSolverbooleanEnables the built-in CAPTCHA solver for the session.
extensionIdsstring[]Chrome extension IDs to load. Requires extension access for your account.
Session notes are updated with PATCH /v1/browser/session?sessionId=.... Do not rely on note during create; current create responses return note: null.

​
Example with Options

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
    }
  }'

​
Next Steps