Profiles
Save cookies and localStorage, then restore them in a new browser.
With an initialized client:
const profile = await client.profiles.create({ name: "Report login" });
await client.withSession({
profile: { id: profile.id, persistOnClose: true },
}, async (session) => {
// Sign in using this browser. Close saves its authorized state.
});
await client.withSession({ profile: { id: profile.id } }, async (session) => {
// A new browser restores the saved cookies and localStorage.
});| Parameter | Type | Default / meaning |
|---|---|---|
name | string | Required; 1–128 characters |
profile.id | string | Profile in the same project |
profile.persistOnClose | boolean | false; set true to save on normal close or expiry |
Manage a Profile
| HTTP | TypeScript | Python |
|---|---|---|
POST /v1/profiles | profiles.create({ name }) | profiles.create(name) |
GET /v1/profiles | profiles.list({ limit, cursor }) | profiles.list(limit=..., cursor=...) |
GET /v1/profiles/{id} | profiles.get(id) | profiles.get(id) |
DELETE /v1/profiles/{id} | profiles.delete(id) | profiles.delete(id) |
Creation requires an Idempotency-Key; SDKs generate one. List responses contain items and nextCursor. Responses expose metadata, version, and inUse, never saved cookies or storage values.
A Profile can be used by one unreleased session at a time. Concurrent use or deletion returns 409 PROFILE_IN_USE. Close the browser and wait for releasedAt before using the Profile again. Deleted Profiles return 404; repeating deletion returns 204.
Check the save result
const ended = await client.sessions.get(sessionId);
if (ended.profile?.persistOnClose && ended.profile.saveStatus !== "saved") {
throw new Error("Profile was not saved");
}saveStatus is not_requested, pending, saved, or failed. A failed save exposes saveError.code, keeps the previous successful version, and still releases the browser. Runtime failure does not save partial state. Snapshots are encrypted at rest and limited to 8 MiB.
Profiles contain cookies and localStorage. They exclude sessionStorage, IndexedDB, downloads, page memory, and Agent history. Website sessions can expire or be revoked; your application must detect a new login challenge.
See reuse a login.