Skip to main content
POST
/
browser
/
sessions
Create Session
curl --request POST \
  --url https://api.example.com/browser/sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "capabilities": [
    "<string>"
  ],
  "extensions": [
    "<string>"
  ],
  "proxyUrl": "<string>",
  "proxy": {
    "location": "<string>",
    "provider": "<string>",
    "sticky": true
  },
  "timeout": 123
}
'
{
  "id": "<string>",
  "status": "<string>",
  "cdpUrl": "<string>",
  "liveViewUrl": "<string>",
  "capabilities": [
    "<string>"
  ],
  "extensions": [
    "<string>"
  ],
  "proxyUrl": "<string>",
  "proxy": {},
  "createdAt": 123,
  "expiresAt": 123
}

​
Overview

Creates a new browser session backed by a sandboxed VM. The session stays alive until it hits timeout of inactivity, you destroy it explicitly, or it expires at expiresAt. Returns a cdpUrl you can attach to with any Chrome DevTools Protocol client (Playwright, Puppeteer, chromedp), plus a liveViewUrl for an interactive noVNC view.

​
Body

​
capabilities
string[]
Runtime capabilities to enable on the session. Supported values include stealth (anti-bot evasion) and recording (server-side MP4 capture).
​
extensions
string[]
Extension IDs to load into the browser. Upload extensions first via POST /browser/extensions.
​
proxyUrl
string
Raw proxy URL (e.g. http://user:pass@host:port). Mutually exclusive with proxy.
​
proxy
object
Managed proxy options. Mutually exclusive with proxyUrl.
​
timeout
integer
default:"900000"
Idle timeout in ms before the session auto-terminates. Default 15 minutes.

​
Example Request

curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions" \
  -H "Authorization: Bearer $SCRAPENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

​
Response

​
Success Response (201)

​
id
string
Session ID (UUID). Use this as {id} in all other browser session endpoints.
​
status
string
Current state — typically ready when the session is immediately usable.
​
cdpUrl
string
Chrome DevTools Protocol WebSocket URL. Attach any CDP client here.
​
liveViewUrl
string
Shareable noVNC URL for interactive live view.
​
capabilities
string[]
Capabilities enabled on this session.
​
extensions
string[]
Extension IDs loaded into the browser.
​
proxyUrl
string
Raw proxy URL, when the session was created with proxyUrl.
​
proxy
object
Managed proxy info — enabled, provider, location, sticky.
​
createdAt
integer
Unix epoch milliseconds when the session was created.
​
expiresAt
integer
Unix epoch milliseconds when the session will auto-expire absent activity.
Example Response: 
{
  "id": "baa3f390-fa6e-4a24-b84a-a575a5f3a9c7",
  "status": "ready",
  "cdpUrl": "wss://cdp.scrapengine.io/sessions/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7",
  "liveViewUrl": "https://live.scrapengine.io/baa3f390-fa6e-4a24-b84a-a575a5f3a9c7",
  "capabilities": ["stealth"],
  "extensions": [],
  "proxy": { "enabled": true, "provider": "oxylabs", "location": "us", "sticky": true },
  "createdAt": 1714000000000,
  "expiresAt": 1714001800000
}

​
Error Responses

StatusDescription
400Invalid body — e.g. more than 20 extensions requested, or a validation error on a field.
401Unauthorized — invalid or missing API key.
503Maximum concurrent sessions reached for this account, the browser pool cannot allocate a sandbox, or VM initialization failed.