POST
Create session

Authorizations

Authorization
string
header
required

Every request carries a bearer API key, which looks like ph_live_.... Keep keys server-side, because a key grants full control of your sessions. A missing header returns 401; an invalid or revoked key currently returns 403, so treat the two together as authentication failure.

Body

application/json
mode
string
default:ephemeral

ephemeral or persistent. ttl applies to persistent sessions only.

region
string | null

A region code from GET /v1/regions. Defaults to the nearest region.

persona
string | null

Pin a fingerprint persona. Defaults to auto-rotation.

ttl
number | null

Absolute lifetime in seconds for persistent sessions. Defaults to the plan default.

idle_timeout
number | null

The session is reclaimed after this many seconds with no activity. Keep it tight, because the session bills while it exists.

warm_up
boolean
default:false

Pre-warm the render path before returning.

proxy_rotation
string | null

per_session, per_request, or manual.

residential
boolean | null

Route egress through residential IPs. Paid plans only.

full_browser
boolean
default:false

Boot a headful browser with a viewable desktop.

block_ads
default:false

true, false, "strict", "basic", or "off".

Response

Successful Response

session_id
string
required

The session id, used in every session-scoped call.

state
string
required

starting, ready, closing, or dead.

mode
string
required

ephemeral or persistent.

owner
string
required

The account that owns the session.

region
string | null

The region the session runs in, or null for the default.

worker_id
string | null

Internal placement identifier. May be null.

connect_url
string | null

A ready-to-use CDP endpoint. Populated only by session create and /connect; always null when a session is read back.

connect_expires_in
integer | null

Seconds until connect_url stops working. 300 on create; null when a session is read back.