Profiles
Persist and reuse browser state across sessions.
Reuse cookies, storage, IndexedDB, or fingerprint config across runs.
Split by customer, account, or workflow for clear access and debugging.
Use read-only for reuse; write back only when state should persist.
When to Use Profiles
Use one-off sessions when no durable browser state is required. Reach for profiles when you need to:
Avoid logging in during every task and reduce avoidable target-site friction.
Keep cookies, localStorage, or IndexedDB written by the target site.
Let multiple automation jobs use the same controlled browser state.
Split state by customer, account, or workflow so debugging and access control stay clear.
Do not put every task into the same profile. Split profiles by account, customer, or workflow so debugging and access control stay clear.
How Profiles Work
Create an empty profile with POST /v1/profiles.
Pass profileId in POST /v1/sessions so the session loads that state.
Chromium produces new cookies, storage, and site context while the session runs.
When the session stops, the runner writes the updated profile blob to storage for the next session.
Write Locking
Only one session can write to a profile at a time. When you create a session with a profileId, the API acquires a write lock on the profile. This prevents concurrent sessions from overwriting each other's state.
A locked profile rejects new writers instead of overwriting state. The lock clears after the session stops and the updated profile blob is persisted; if a runner fails mid-session, recover intentionally with POST /v1/profiles/{id}/unlock.
Default posture: prefer a one-off session when durable state is not required; keep reused login state read-only when possible; allow write-back only when the workflow must refresh login state or save new context.
Generator Config
Profiles can carry a generator config for browser properties and fingerprint-generator input. Treat it as an advanced capability; most scraping, screenshot, and automation workflows only need profile state persistence. See the Profiles API Reference for field format, snake_case conventions, and the update endpoint.
The core path is simple: create a profile, attach it to a session, and choose whether writes should persist on stop. See the Profiles API Reference for listing, deletion, blob upload, generator config, unlock, and field-level details. Recovery endpoints are for controlled recovery, not the normal session path.