One-time profiles
One request creates and starts the browser. Use a one-time profile when each task can begin fresh:proxy, the browser uses an available account pool. Supply your own proxy if your account has none.
The response has ws_url and internal_uuid. Connect to ws_url, then use internal_uuid to stop the session. Everything the browser stored is discarded with it.
Persistent profiles
Create a profile once:data.uuid from the response and use it to start the profile:
/start apply to the running session. To change the stored settings, update the profile while it is stopped.
A persistent profile runs one browser at a time. Starting it again returns the running session and ignores the settings sent with that request, so stop the session first when a run needs different ones. Use a separate profile for work that runs in parallel.
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
Sign in once in a persistent profile with the storage the site needs, through your automation or the session’s DevTools. Stop the session and wait for the response: that is what saves the state for the next start. The site can still expire its own session, and the exit IP can differ on the next run. Use session control when the IP has to stay the same.Change the proxy
Change the proxy when the stored one stops working, which happens with residential and mobile peers, or when a run needs a different location. Replace the saved value for future runs, or override it for a single session. Change the stored proxy. Update the profile while it is stopped; the next start uses the new value.null to remove the stored proxy and let later starts select from an available account pool:
profile_is_running; see errors.
Override for one session. Send the same proxy field in the start request instead. It applies to that browser only and leaves the stored proxy unchanged.
A proxy URL, open_vpn, or wireguard also overrides the stored proxy for that run. A shared-tier override needs a country, for example {"proxy": {"tier": "shared", "country": "de"}}. Without a country, a shared request leaves the stored proxy in place.
Read the profile with GET /profiles/{profile_uuid} to see its current connection.
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. For persistent profiles, a normal stop saves the selected browser state. Wait for completion before starting the next run.browser_settings.inactive_kill_timeout seconds without a CDP command, ChromeDriver request, or scrape. The default is 30 seconds; an open but idle connection does not count.
Set a longer timeout for work that includes pauses, such as manual input. An
abandoned browser then also runs longer.
Finding what is running
data lists the running sessions. Use one_time to identify disposable ones; do not infer the 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.