Skip to main content
A session is a running browser. One-time profiles discard their state when the session stops. Persistent profiles can save cookies and other selected browser data for later sessions.

​
One-time profiles

POST /profiles/one_time creates and starts a browser. Use it when each task can begin with a fresh profile.
Set the environment variables as shown in the Quickstart. An omitted proxy uses an available account pool; if your account has none, supply your own proxy. The response has ws_url and internal_uuid at the top level. Connect to ws_url, then stop the session with the returned identifier. Cookies, storage, and history from a one-time profile are not saved as a persistent profile.

​
Persistent profiles

Create a profile once. title and fingerprint.os are required:
A successful creation returns HTTP 201 with the profile identifier in data.uuid. Save this identifier and use it to start the profile:
Creation does not start a browser. Each start restores saved profile state. Settings supplied to /start apply to the running session; use PATCH /profiles/{profile_uuid} to update stored settings while the profile is stopped. A persistent profile has one running browser at a time. Starting a profile that is already running returns the running session rather than restarting it, and the settings sent with that request are not applied. Stop the session first when a run needs different start settings. Use a different profile for independent work, and avoid having multiple workers control the same profile.

​
What gets saved

storage_options selects the data saved with the profile: Enable the storage your application uses. Cookies alone may not preserve a login that also depends on local storage. See Cookies.

​
Reuse a login

  1. Create a persistent profile with cookies enabled. Enable local storage if the site needs it.
  2. Start the profile and open the site’s login page.
  3. Sign in through your automation or the session’s DevTools.
  4. Stop the session through the API and wait for the response.
  5. Start the same profile and navigate to an authenticated page. Check that the page still recognizes the account before continuing.
The fingerprint and saved storage remain associated with the profile. A website can still expire or revoke its own session. Proxy settings do not guarantee the same exit IP on every run; configure proxy session behavior when IP continuity matters.

​
Change the proxy

A saved profile can change its connection in two ways, with different lifetimes. Change the stored proxy. PATCH the stopped profile; the next start uses the new value.
A pool selection is resolved when it is saved, not on each start: the profile stores one concrete proxy from the pool and reuses it every run. The exit IP behind a residential or mobile proxy still changes between sessions; use session control when the IP must stay the same. Saving the same selection again pins a different proxy. A stored pool proxy is not re-checked at start, so save the selection again if it stops working. Send a URL to store your own proxy, or null to remove the stored proxy and let later starts select from an available account pool:
Edit a stopped profile. A running profile returns profile_is_running; see errors. Override for one session. Send proxy in the start request. It applies to that browser only and leaves the stored proxy unchanged.
A proxy URL, open_vpn, and wireguard replace the stored proxy for that run in the same way. A shared-tier override needs a country - {"proxy": {"tier": "shared", "country": "de"}} - because a shared request without one leaves the stored proxy in place. An override reaches the browser only on a start that actually launches one; a request that returns an already running session does not apply it. Read a profile back with GET /profiles/{profile_uuid} to see its current connection. Account pool proxies are reported as premium or shared instead of credentials; your own proxies are returned as supplied. Changing the exit IP does not change the profile’s cookies, storage, or fingerprint. A site that tied its session to the previous IP or country can ask for verification again, so keep the country stable unless the account is meant to move. See proxies for targeting and session options.

​
Identifiers

Always use the identifier returned for the operation. Do not depend on profile and session identifiers being different, or on a persistent profile receiving a new identifier on every start.

​
How a session ends

Explicit stop. Send POST /profiles/{internal_uuid}/stop. For persistent profiles, a normal stop saves the selected browser state. Wait for completion before starting the next run.
Inactivity. The browser stops after browser_settings.inactive_kill_timeout seconds without activity. The default is 30 seconds; the accepted range is 1–3600 seconds. CDP commands, ChromeDriver requests, and scraping activity update the activity timer. An open but idle connection is not sufficient.
Set a longer timeout for work that includes pauses, such as manual input. A longer timeout also leaves an abandoned browser running longer. Failure. A browser or infrastructure failure can end the session before a normal stop completes. Recent unsaved state may be lost. Check active sessions before reconnecting or starting replacement work.

​
Finding what is running

data contains an array of sessions with internal_uuid, profile_uuid, one_time, started_at, and active_seconds. Use one_time to identify disposable sessions; do not infer profile type from whether an identifier is present. This lists running browsers only. GET /profiles lists saved profiles page by page, each with a status of started or stopped. Stop sessions owned by completed or failed jobs. Age alone does not prove that a session is abandoned.
POST /profiles/stop stops every running browser on the account, including browsers used by other workers. Its response reports stopped and failed separately.

​
Browser capacity

A running browser uses one concurrency slot until it stops. A failed or interrupted start request can have an uncertain outcome, so check for an existing session before retrying it.