Profiles

A Profile is a single, whole browser identity: cookies, localStorage, and login state for every site are all stored in one Profile. It is not split per site — one user maps to one Profile, and when the agent opens the browser with it, that person's login state for all sites is present.

When creating a session or a monitor, you reference it by profile_id, and the agent opens the browser carrying that identity — no need to log in again each time. Without a Profile, every session is a blank slate — when it hits a page that requires a login, it can only stop.

Don't split Profiles per site

A Profile is whole. Log into whichever sites you need within the same Profile; every later task shares that one Profile. Do not create a separate Profile per site.

When to use it

• The task needs to access sites that require a login (email, social platforms, internal systems).
• You want multiple sessions / monitors to share the same login state, rather than each logging in on its own.
• The login state needs to be reused across tasks and across days.

When the task only accesses public pages and needs no login, you don't need a Profile.

Create and log in a Profile

To install a login state into a Profile for the first time, we recommend doing it in the Console: the Console opens a controlled browser where you log in normally, pass captchas, and make whatever settings you want, and the login state lands in the Profile. This step inherently needs a human, and the Console is the smoothest form for it.

After that, this Profile can be referenced repeatedly from code. You can also manage Profile resources via the API:

POST   /v1/projects/{pid}/profiles            create a profile
GET    /v1/projects/{pid}/profiles            list profiles
GET    /v1/projects/{pid}/profiles/{id}       get one
PATCH  /v1/projects/{pid}/profiles/{id}       rename, etc.
DELETE /v1/projects/{pid}/profiles/{id}       delete

Fields you can pass on creation:

Field	Type	Description
name	string	A recognizable name for the Profile, usually one per user
customer_user_id	string	Associate the Profile with a user in your business system

Interactive login goes through POST /v1/projects/{pid}/profiles/login and POST /v1/projects/{pid}/profiles/{id}/confirm — see the OpenAPI spec for the exact request bodies.

The API also has a cookie_domains field; it only serves the legacy "bring-your-own-cookies" B2B path and is not used by a whole Profile — you can ignore it.

Using a Profile in a session / monitor

Once you have a profile_id, reference it when creating a session:

from web_agent.v1 import Client
from web_agent.v1.types import CreateSessionRequest

async with Client(api_key="wa_...", project_id="proj_demo") as client:
    session = await client.sessions.create(CreateSessionRequest(
        instructions="Open the LinkedIn inbox and reply to the latest message.",
        profile_id="prof_alice",
    ))

Track monitors also accept profile_id; use it when monitoring sites that require a login.

Profile state

A Profile's state and these fields reflect whether it is still usable:

Field	Description
state	The Profile's current state
last_used_at	The most recent time it was used by a session / monitor
last_alive_at	The most recent time the login state was confirmed still valid
last_failure_reason	The reason for the most recent usage failure

Cookies and login state expire. If a run fails because the login is no longer valid, last_failure_reason explains why — at that point you need to go back to the Console and log in to that Profile again. Making this step observable costs less than letting the run fail repeatedly on the login page.

Next steps

• DoAnything — how profile_id enters a session
• Track — reuse login state for long-term monitoring
• API Overview — shared conventions; the full field set is in the OpenAPI spec