Create session
Boots an isolated browser and returns a ready-to-use connect_url. The session bills for as long as it exists, so keep idle_timeout tight and release the session in a finally block.
Authorizations
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
ephemeral or persistent. ttl applies to persistent sessions only.
A region code from GET /v1/regions. Defaults to the nearest region.
Pin a fingerprint persona. Defaults to auto-rotation.
Absolute lifetime in seconds for persistent sessions. Defaults to the plan default.
The session is reclaimed after this many seconds with no activity. Keep it tight, because the session bills while it exists.
Pre-warm the render path before returning.
per_session, per_request, or manual.
Route egress through residential IPs. Paid plans only.
Boot a headful browser with a viewable desktop.
true, false, "strict", "basic", or "off".
Response
Successful Response
The session id, used in every session-scoped call.
starting, ready, closing, or dead.
ephemeral or persistent.
The account that owns the session.
The region the session runs in, or null for the default.
Internal placement identifier. May be null.
A ready-to-use CDP endpoint. Populated only by session create and /connect; always null when a session is read back.
Seconds until connect_url stops working. 300 on create; null when a session is read back.