Profiles and sign-ins

A profile is a browser’s memory: cookies, localStorage, IndexedDB, service workers and saved logins. A session started with a profile begins where the last one left off, and saves it back when it stops. Sign in to a site once, and every later session with that profile is signed in.

Create one and use it

profile = client.profiles.create(name="Shopify admin")
browser = client.browsers.create(profile_id=profile.id, timeout=30)

Or create it on the dashboard’s Profiles page.

The profile is saved when the browser stops, so stop it rather than letting it time out when the sign-in matters (a timeout saves too, but your agent may have left mid-step). Each save is a new version; the version before stays until the next save succeeds, so a lost machine never corrupts a profile.

Sign in as a person

Some sign-ins need a person: a one-time code, a passkey, a CAPTCHA. On the dashboard’s Profiles page, Open to sign in starts a browser with the profile and opens its live view. Sign in, close the tab, and stop the browser: the profile now holds the session. Your agents’ browsers with that profile start signed in.

You can do the same from code: start a browser with the profile, open its liveUrl yourself, and stop it when done.

One browser per profile

A profile is used by one live browser at a time. A second create with the same profile joins the live browser (answers it, 201), so two agents can share it. It answers 409 profile_in_use when the second create asks for a different proxy or screen than the live one has.

Profile settings

Settings apply to every session started with the profile, unless the create says otherwise:

{
  "name": "Shop in Germany",
  "settings": {
    "proxy": { "country": "de", "sticky": true },
    "screen": { "width": 1440, "height": 900 },
    "locale": "de-DE",
    "timezone": "Europe/Berlin"
  }
}

A site that saw a German address at sign-in may ask again from elsewhere, so a profile’s proxy keeps its sessions in one country.

Import your Chrome profile

Bring a profile you already use, on the dashboard (Import on a profile) or with POST /profiles/{id}/import. Imports add up: a folder, then a storage state.

Upload	What comes along
A profile folder, zipped (application/zip, 50 MB at most): a user-data-dir, or one profile folder such as Default	localStorage, IndexedDB, service workers, preferences and history. Cookies and passwords only when they are not encrypted with a key of your machine, which is rare on Windows and macOS.
A storage state (application/json, 20 MB at most), what Playwright’s storage_state() writes	Its cookies and each origin’s localStorage.

So from Windows or macOS, send both: the zipped folder for storage, and a storage state for cookies, written by Playwright with the profile’s browser closed:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context("<your profile folder>", channel="chrome", headless=True)
    context.storage_state(path="storage-state.json")
    context.close()

Each import runs as a short session and is charged as one. Sites that bind a session to its device (Google on Windows, some banks) or to an IP address may still ask you to sign in again.