Skip to main content
POST
/
v1
/
browser
/
session
Create Browser Session
curl --request POST \
  --url https://api.driver.dev/v1/browser/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "hosted",
  "country": "US",
  "nodeId": "node-id-from-servedBy",
  "duration": 600,
  "windowSize": "1920x1080",
  "proxyUrl": "socks5://user:[email protected]:1080",
  "fast": true,
  "captchaSolver": true,
  "extensionIds": [
    "abc123def456"
  ]
}
'
{
  "sessionId": "<string>",
  "servedBy": "<string>",
  "createdAt": "<string>",
  "stoppedAt": "<string>",
  "cdpUrl": "<string>",
  "note": "<string>"
}

Authorizations

​
Authorization
string
header
required

Your Driver API key. Get one at https://app.driver.dev

Body

application/json
​
type
enum<string>

Use hosted Driver infrastructure for the session.

Available options:
hosted
Example:

"hosted"

​
country
string

Start a session in a specific country using its 2-letter ISO code. Optional.

Required string length: 2
Example:

"US"

​
nodeId
string

Create the hosted session on a specific previously used hosted node. Optional. Overrides country.

Example:

"node-id-from-servedBy"

​
duration
integer

The duration of the browser session in seconds. Optional. Default is 3600 seconds (1 hour). Cannot be greater than 3600 seconds (1 hour). Cannot be less than 60 seconds (1 minute).

Required range: 60 < x <= 3600
Example:

600

​
windowSize
string

The window size for the browser session in the format WIDTHxHEIGHT (e.g., 1920x1080). Optional.

Example:

"1920x1080"

​
proxyUrl
string

SOCKS5 proxy URL for the session. Optional. Requires hosted sessions and cannot be used with nodeId.

Example:

"socks5://user:[email protected]:1080"

​
profile
object

The browser profile to use for the session. Optional.

​
fast
boolean

Attempt faster startup when the request is eligible. Optional.

Example:

true

​
captchaSolver
boolean

Enable the built-in CAPTCHA solver for the session. Optional. Default is false.

Example:

true

​
extensionIds
string[]

Chrome extension IDs to load into the browser session. Optional. Requires extension access for your account.

Example:
["abc123def456"]

Response

Successfully created a browser session.

​
sessionId
string
required

The ID of the created browser session.

​
status
enum<string>
required

The status of the session.

Available options:
starting,
active,
completed,
error
​
servedBy
string
required

The node ID that is serving this session.

​
createdAt
string
required

The ISO 8601 timestamp when the session was created.

​
stoppedAt
string | null
required

The ISO 8601 timestamp when the session was stopped, or null if it is still active.

​
cdpUrl
string<uri> | null
required

The URL to access the Chrome DevTools Protocol for this session, or null if not available.

​
note
string | null
required

An optional note attached to the session, or null if not set.