Profiles

A profile saves your login, your cookies and site data, so you don't have to sign in again. Log in once, attach the profile to any session, and you start already signed in.

Create a profile

const profile = await client.profiles.create({ name: "amazon-seller" })
console.log(profile.id) // "prof_abc123"

Log in from your browser

Open the profile in the console → Profiles → Open editor to drive a live browser right in your tab. Log into your sites, click through any prompts, then hit Save. This is the easy way to handle sites with 2FA or captchas.

Upload an existing login

Already have a working storageState.json from Playwright? Upload it directly:

import { readFile } from "node:fs/promises"

const storageState = JSON.parse(await readFile("./storage-state.json", "utf-8"))
await client.profiles.save(profile.id, storageState)

Attach to a session

const session = await client.sessions.create({
  profileId: "prof_abc123",
})

console.log(session.storageState?.cookies?.length, "cookies loaded")

The profile seeds the session's default context, not every context

A profile can only be applied when a browser context is created — there is no way to retrofit cookies onto a context that already exists. That means attaching a profile seeds exactly one context: the session's default one.

The launch() wrapper (TS and Python) handles this for you: it creates that default context itself and exposes it as session.context (session.context/browser_session.context) — use that, or session.newPage(), rather than browser.contexts()[0], which is not guaranteed to be the seeded one.

A context you create yourself — via session.newContext(), or by connecting with raw CDP and calling the browser's own newContext() — does not carry the profile. Apply session.storageState to it yourself at creation time if you need the login there too.

List and delete

const profiles = await client.profiles.list()
for (const p of profiles) console.log(p.id, p.name)

await client.profiles.delete("prof_abc123")

Treat profiles like passwords

A profile holds a real login. Anyone with your API key can attach it to a session and act as that account. Keep your keys safe and use a separate key per environment.

What's inside

Profiles use Playwright's standard storageState, the same JSON that context.storageState({ path }) writes.

type StorageState = {
  cookies?: Array<{
    name: string
    value: string
    domain?: string
    path?: string
    expires?: number
    httpOnly?: boolean
    secure?: boolean
    sameSite?: "Strict" | "Lax" | "None"
  }>
  origins?: Array<{
    origin: string
    localStorage?: Array<{ name: string; value: string }>
  }>
}