Browsers

Profiles

A Profile is a reusable identity — cookies and localStorage for a site — that a browser starts with and saves back to.

What a Profile is

Saved browser state for one site: cookies and localStorage, scoped to explicit origins, encrypted at rest. Start a browser with a Profile and it is signed in; stop it and the state is saved back. Pass the Profile to a run and the agent works as that identity.

A Profile is not a full browser profile: no fingerprint, disk cache, IndexedDB or sessionStorage. It is the sign-in state, and only that.

Routes

Method and path	Request and result
`GET /v1/profiles`	Metadata, up to 500 per project
`POST /v1/profiles`	`{ "name", "site", "allowed_origins"?, "login_credential_id"? }`; `site` is an HTTP(S) URL without credentials, query or hash; origins default to the site's origin; the credential is one of the project's `login` credentials
`GET /v1/profiles/{id}`	Metadata, revision, saved counts, and the holder `browser_id` when a browser has it
`PATCH /v1/profiles/{id}`	`{ "revision", "name"?, "site"?, "allowed_origins"?, "needs_auth"?, "login_credential_id"? }` (`null` unbinds); idle profiles only; a narrower scope drops the saved state outside it
`POST /v1/profiles/{id}/import`	`{ "revision", "state": { "cookies", "origins" } }`; Playwright's storage-state shape, replaced atomically
`POST /v1/profiles/{id}/save`	`{ "revision", "browser_id" }`; capture from the running holder; refused while an Agent run owns it
`DELETE /v1/profiles/{id}`	`{ "revision" }`; refused while a browser holds it; owner or admin

Reading needs read; create, update, import and save need execute; deletion needs an owner or admin session. No route returns plaintext cookies or localStorage.

Create the Profile for the site.
Create a browser with profile_id, open the site, and sign in — by hand from the live window, or through actions.
Save (POST …/save), or simply stop the browser: a normal stop saves.
Pass profile_id to later browsers and to runs. A continuation of a session keeps its identity; a supplied browser must carry the same Profile.

profile = client.profiles.create({"name": "Shop account", "site": "https://shop.example"})browser = client.browsers.create({"profile_id": profile["id"]})browser.ready()# … sign in from the console's live window, or with actions …client.profiles.save(profile["id"], browser["id"])run = client.run("Open my orders page and list the last three orders.", profile_id=profile["id"])

profile = client.profiles.create({"name": "Shop account", "site": "https://shop.example"})
browser = client.browsers.create({"profile_id": profile["id"]})
browser.ready()
# … sign in from the console's live window, or with actions …
client.profiles.save(profile["id"], browser["id"])
run = client.run("Open my orders page and list the last three orders.", profile_id=profile["id"])

const profile = await client.profiles.create({ name: 'Shop account', site: 'https://shop.example' });const browser = await client.browsers.create({ profile_id: profile.id });await browser.ready();// … sign in from the console's live window, or with actions …await client.profiles.save(profile.id, { browser_id: browser.id });const run = await client.run('Open my orders page and list the last three orders.', { profile_id: profile.id });

const profile = await client.profiles.create({ name: 'Shop account', site: 'https://shop.example' });
const browser = await client.browsers.create({ profile_id: profile.id });
await browser.ready();
// … sign in from the console's live window, or with actions …
await client.profiles.save(profile.id, { browser_id: browser.id });
const run = await client.run('Open my orders page and list the last three orders.', { profile_id: profile.id });

States

State	Meaning
`draft`	Created, nothing saved yet
`ready`	State was saved — by the platform, not authenticated by the site
`busy`	A browser holds it
`needs_auth`	Marked as needing a fresh sign-in
`save_failed`	The last save failed; the previous state is kept
`cleanup_failed`	The holder's release could not be verified

Signing in with the Agent

A profile may be bound to one of the project's login credentials (login_credential_id). The console's Sign in with the Agent starts a run with profile_id and credential_ids: [that credential] and a task that opens the site and types the password placeholder — the agent never sees the value; the username goes into the task text as written. The same from code: create the run yourself with those two fields and a task of your own. When the run ends on the signed-in page, save the profile from its browser (or let the browser's idle stop save it); the credential's value is never part of the saved state.

A browser records profile_sync: failed when its final save failed; the last good state is retained, and an explicit save can be retried while the browser runs.

Limits

256 KiB of state, 500 cookies, 32 exact HTTP(S) origins and 512 localStorage entries per origin. Imported cookies carry name, value, domain, path, expires, httpOnly, secure, sameSite; origins carry origin and localStorage: [{ name, value }]. Captures omit unrelated sites; cookie scope follows browser domain rules, not ports.