Persistent Sessions & Profiles

Learn about Persistent (sticky) Sessions and Persistent Profiles on Oxylabs Headless Browser. Reconnect to ongoing sessions and reuse your cookies or local storage though multiple sessions.

Managing long-running multi-stage automation workflows or maintaining logged-in user states across distinct connection sequences requires persisting browser states. Oxylabs Headless Browser offers two advanced persistence systems:

Persistent Sessions	Keep a live remote browser environment running across client disconnections.
Persistent Profiles	Save and restore cookies, local storage, and browser cache. (Activation required)

Persistent Sessions

Persistent (sticky) Sessions keep your remote browser instance running in the cloud (even when your local automation script disconnects) by defining a custom session_name to your connection URL:

wss://USER:[e-mail]?session_name=checkout-flow-test

Parameter	Description	Type
session_name	When defined, a sessions persist up to the maximum time-to-live (TTL) (max 24h or until stopped). Reconnect with the same session_name to reattach the same session ID and existing tabs. Supported format: ^[A-Za-z0-9-]{3,36}$	String
keep_alive	While true (default), the session stays on in the cloud after you disconnect (up to max TTL – 24h). While false, calling browser.close() reclaims and closes the session.	Boolean

Reconnect to an existing tab

// Reconnect to existing session with 
const browser = await chromium.connectOverCDP(endpoint);
const ctx = browser.contexts()[0];
const page = ctx.pages().find(p => p.url().includes("http://example.com "));

Persistent Profiles

Persistent Profiles feature and o_profile parameters are restricted by default. To access them, contact Oxylabs support (live chat or email) or your Dedicated Account Manager.

Save cookies and localStorage under a named profile and restore them in a brand-new session. Using the following parameters lets you maintain a logged-in persona across sessions without re-authenticating every time:

Parameter	Description	Type
o_profile	Save/restore cookies and localStorage with a named profile (14 days from last use). Supported format: ^[A-Za-z0-9_-]{1,36}$	String
o_profile_save	Force profile save mid-session. Default: true.	Boolean
proxy_resi_ses_id	Custom session ID to pin residential exit IP across sessions. Supported format: ^[A-Za-z0-9]{3,36}$.	String
proxy_resi_ses_time	Duration to hold the pinned residential proxy exit IP in minutes. Min 1, max 1440 (24h).	Integer

The number of profiles per account is capped (max_profiles). Exceeding the limit returns CDP_LIMIT_REACHED: profile limit reached error. Reuse one stable profile name when possible, or contact Oxylabs support (live chat or email) or your Dedicated Account Manager to raise the limit.

Reliable cross-session restore

For websites with strict bot monitoring systems, saving cookies is not enough. If a restored profile connects from a different residential exit IP, your cookies may get invalidated, resulting in blank pages or security verification screens.

To ensure consistent logins, pair your profile with a pinned residential exit IP:

// Session 1: Authenticate and back up state
const connectionOne = "wss://USER:[e-mail]?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";

// Session 2: Restore profile with the exact same IP session context
const connectionTwo = "wss://USER:[e-mail]?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";