---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/logins/profiles
markdown_url: https://steel.dev/docs/logins/profiles.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Profiles
description: Save a browser's cookies, logins, and settings as a profile, and start later sessions from it with profileId.
summary: Save a browser's cookies, logins, and settings as a profile, and start later sessions from it with profileId.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/logins/browser-state.md
related:
  - https://steel.dev/docs/logins/browser-state.md
  - https://steel.dev/docs/logins/stay-signed-in.md
  - https://steel.dev/docs/logins/session-context.md
  - https://steel.dev/docs/logins/credentials.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Profiles

A profile saves a session's whole browser in Steel: its cookies, storage, extensions, settings and user agent. A later session that starts from the profile gets the same cookies and storage, so it stays signed in until the site ends the login. Open tabs do not carry over. Use a profile when sessions should pick up where the last one stopped. [Browser state](https://steel.dev/docs/logins/browser-state) lists what carries over, and compares a profile with session context, which you store yourself, and credentials, which sign in for your agent.

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable. Then install the Steel SDK and Playwright.

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright
```

**Go**

```sh
go mod init profiles
go get github.com/steel-dev/sdk/go
```

**Rust**

```sh
cargo new profiles
cd profiles
cargo add steel-rs
cargo add tokio --features macros,rt-multi-thread
```

In Go and Rust, install only the SDK, as the [Go](https://steel.dev/docs/reference/sdks/go#install) and [Rust](https://steel.dev/docs/reference/sdks/rust#install) SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.

## Save a profile

Set `persistProfile` to `true` when you create the session. The response has a `profileId` at once, but Steel saves the browser only after you release the session. The profile has the status `UPLOADING` until the save is done, and then `READY`.

This program creates a session that saves a profile, stores a value in `localStorage`, and releases the session. Then it reads the profile every 2 seconds until it is `READY`, and prints its ID. It stops with an error if Steel could not save the profile, or if the profile is not ready after 60 seconds.

**TypeScript**

```ts file=save-profile.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();

async function waitUntilReady(profileId: string) {
  const deadline = Date.now() + 60_000;
  for (;;) {
    const profile = await client.profiles.get(profileId);
    if (profile.status === "READY") return profile;
    if (profile.status === "FAILED") throw new Error(`Steel could not save profile ${profileId}.`);
    if (Date.now() > deadline) throw new Error(`Profile ${profileId} is not ready after 60 seconds.`);
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

const session = await client.sessions.create({ persistProfile: true });

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  await page.evaluate(() => localStorage.setItem("theme", "dark"));
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

const profile = await waitUntilReady(session.profileId!);
console.log(profile.id, profile.status);
```

**Python**

```python file=save_profile.py
import time

from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()


def wait_until_ready(profile_id):
    deadline = time.monotonic() + 60
    while True:
        profile = client.profiles.get(profile_id)
        if profile.status == "READY":
            return profile
        if profile.status == "FAILED":
            raise RuntimeError(f"Steel could not save profile {profile_id}.")
        if time.monotonic() > deadline:
            raise RuntimeError(f"Profile {profile_id} is not ready after 60 seconds.")
        time.sleep(2)


session = client.sessions.create(persist_profile=True)

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        page.evaluate("() => localStorage.setItem('theme', 'dark')")
        browser.close()
finally:
    client.sessions.release(session.id)

profile = wait_until_ready(session.profile_id)
print(profile.id, profile.status)
```

Run the program:

**TypeScript**

```sh
npx tsx save-profile.mts
```

**Python**

```sh
python save_profile.py
```

The program prints the profile's ID and status. Keep the ID, because the next sections use it.

```text nocopy
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY
```

To save a login, sign in during this session, with your code or by hand in the [live view](https://steel.dev/docs/observability/live-view). Before you release the session, open a page that only a signed-in user can see, to check that the login worked.

Besides the browser, a profile saves the `userAgent`, `dimensions`, `useProxy`, `extensionIds` and `credentials` of the session that created it.

> **Warning**
>
> Do not save a profile from a session that uses `credentials`. [Use credentials with a profile](https://steel.dev/docs/logins/credentials#use-credentials-with-a-profile) explains why, and shows how to use both.

## Start a session from a profile

Pass the ID of a `READY` profile in `profileId`. The session starts with the saved browser.

This program starts a session from the profile and reads the value that the first session stored.

**TypeScript**

```ts file=use-profile.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create({
  profileId: process.env.PROFILE_ID,
});

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  console.log(await page.evaluate(() => localStorage.getItem("theme")));
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}
```

**Python**

```python file=use_profile.py
import os

from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()
session = client.sessions.create(profile_id=os.environ["PROFILE_ID"])

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(page.evaluate("() => localStorage.getItem('theme')"))
        browser.close()
finally:
    client.sessions.release(session.id)
```

Run the program with the ID that the first program printed:

**TypeScript**

```sh
PROFILE_ID=f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 npx tsx use-profile.mts
```

**Python**

```sh
PROFILE_ID=f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 python use_profile.py
```

The program prints the value from the first session.

```text nocopy
dark
```

A session that starts from a profile does not change the profile. To save the session's changes, see [Update a profile](https://steel.dev/docs/logins/profiles#update-a-profile). If the request sets `userAgent`, `dimensions` or `useProxy`, the session uses the request's value instead of the profile's.

A profile keeps the browser, not the IP address. Some sites ask for a new login when an account appears from a new address. To keep the address too, use the profile with a [dedicated IP](https://steel.dev/docs/stealth/dedicated-ips#use-a-dedicated-ip-with-a-profile).

## Update a profile

To save a session's changes back into its profile, pass `persistProfile: true` with `profileId`. When you release the session, Steel replaces the saved browser with this session's browser. The profile stays `READY` during the update, and its `updatedAt` changes when the save is done.

**TypeScript**

```ts
const session = await client.sessions.create({
  profileId: process.env.PROFILE_ID,
  persistProfile: true,
});
```

**Python**

```python
session = client.sessions.create(
    profile_id=os.environ["PROFILE_ID"],
    persist_profile=True,
)
```

**Go**

```go
import "os"

session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	ProfileID:      steel.F(os.Getenv("PROFILE_ID")),
	PersistProfile: steel.F(true),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        profile_id: Some(std::env::var("PROFILE_ID")?),
        persist_profile: Some(true),
        ..Default::default()
    })
    .await?;
```

Use one profile for each account, and do not run two sessions that save the same profile at the same time. Both start from the same browser, and the session that you release last replaces the other's changes.

You can also replace the saved browser with a browser profile directory of your own, as a zip file of at most 300 MB. Send it in `userDataDir` to `client.profiles.update`. You can change `userAgent`, `dimensions` and `useProxy` in the same call. Steel does not save `proxyUrl` in a profile.

**TypeScript**

```ts
import { createReadStream } from "node:fs";

const profile = await client.profiles.update(process.env.PROFILE_ID!, {
  userDataDir: createReadStream("profile.zip"),
});
```

**Python**

```python
with open("profile.zip", "rb") as user_data_dir:
    profile = client.profiles.update(
        os.environ["PROFILE_ID"],
        user_data_dir=user_data_dir,
    )
```

**Go**

```go
import (
	"io"
	"os"
)

userDataDir, err := os.Open("profile.zip")
if err != nil {
	return err
}
defer userDataDir.Close()
profile, err := client.Profiles.Update(ctx, os.Getenv("PROFILE_ID"), steel.ProfileUpdateParams{
	UserDataDir: steel.F[io.Reader](userDataDir),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let profile = client
    .profiles()
    .update(
        &std::env::var("PROFILE_ID")?,
        steel_rs::ProfileUpdateParams::new(steel_rs::Upload::open("profile.zip").await?),
    )
    .await?;
```

To create a new profile from a zip file, call `client.profiles.create` with the same fields. The [Profiles API](https://steel.dev/docs/reference/api/profiles) lists every field.

## List profiles

`client.profiles.list` returns the profiles of your project and their count, the most recently updated first. Each profile has its `id`, its `status`, and the times it was created and last updated.

**TypeScript**

```ts
const { profiles, count } = await client.profiles.list();
console.log(count);
for (const profile of profiles) {
  console.log(profile.id, profile.status);
}
```

**Python**

```python
result = client.profiles.list()
print(result.count)
for profile in result.profiles:
    print(profile.id, profile.status)
```

**Go**

```go
result, err := client.Profiles.List(ctx, steel.ProfileListParams{})
if err != nil {
	return err
}
fmt.Println(result.Count)
for _, profile := range result.Profiles {
	fmt.Println(profile.ID, profile.Status)
}
```

**Rust**

```rust
let result = client
    .profiles()
    .list(steel_rs::ProfileListParams::default())
    .await?;
println!("{}", result.count);
for profile in result.profiles {
    println!("{} {:?}", profile.id, profile.status);
}
```

The code prints the count, then one line for each profile. In a project with 980 profiles, the output starts like this:

**TypeScript**

```text nocopy
980
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY
52bb1668-ce32-4229-8698-2b269294e76d READY
```

**Python**

```text nocopy
980
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY
52bb1668-ce32-4229-8698-2b269294e76d READY
```

**Go**

```text nocopy
980
52bb1668-ce32-4229-8698-2b269294e76d READY
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY
```

**Rust**

```text nocopy
980
52bb1668-ce32-4229-8698-2b269294e76d Ready
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 Ready
```

To read one profile, call `client.profiles.get` with its ID.

Steel deletes a profile that no session has used for 30 days. The API has no call to delete a profile. To remove a login from a profile now, start a session from the profile with `persistProfile: true`, sign out of the site or clear its cookies, and release the session. Steel then saves the profile without the login. To have a profile deleted, contact [Support](https://steel.dev/docs/support).

## Check that it worked

Read the profile with `client.profiles.get` (`client.Profiles.Get` in Go). A saved profile has the status `READY`. Then start a session from it, as [Start a session from a profile](https://steel.dev/docs/logins/profiles#start-a-session-from-a-profile) shows. The session has what the first session stored, such as the `localStorage` value `dark` that the program prints.

## Troubleshooting

### `profile_not_ready`

```json nocopy
{
  "error": "Conflict",
  "code": "profile_not_ready",
  "message": "Profile 'f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254' is not ready yet. It is saved after session 'c1876bc5-6d4d-4e32-a270-1565b9f91281' is released. If that session is still running, release it (POST /v1/sessions/c1876bc5-6d4d-4e32-a270-1565b9f91281/release), then retry in 5 seconds.",
  "param": "profileId",
  "retryable": true,
  "retryAfterSeconds": 5,
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/reusing-auth-context"
}
```

**Cause:** The profile has the status `UPLOADING`. The session that saves it is still running, or Steel is still saving it.

**Fix:** Release the session that the message names. Wait until the profile is `READY`, as the program in [Save a profile](https://steel.dev/docs/logins/profiles#save-a-profile) does.

**Verify:** `client.profiles.get` returns the status `READY`, and the new session starts.

### `profile_upload_failed`

```json nocopy
{
  "error": "Unprocessable Entity",
  "code": "profile_upload_failed",
  "message": "Profile 'PROFILE_ID' failed to upload and cannot be used. Create a new profile and reference that one instead.",
  "param": "profileId",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/reusing-auth-context"
}
```

**Cause:** Steel could not save the profile, and its status is `FAILED`. A profile larger than 300 MB fails this way.

**Fix:** Create a new profile, and keep it at 300 MB or less.

**Verify:** The new profile reaches the status `READY`.

### `profile_not_found`

```json nocopy
{
  "error": "Not Found",
  "code": "profile_not_found",
  "message": "Profile '8c6468ce-89ca-4368-ab09-dbd96909bf19' not found. It may have expired (profiles have a TTL) or belong to a different organization. Check the id, or create a new profile.",
  "param": "profileId",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/reusing-auth-context"
}
```

**Cause:** The ID is wrong, the profile belongs to another organization or project, or Steel deleted it after 30 days without use.

**Fix:** Check the ID with `client.profiles.list`. If the profile is gone, save a new one.

**Verify:** `client.profiles.get` returns the profile.

## Next steps

- [Stay signed in across sessions](https://steel.dev/docs/logins/stay-signed-in): Sign in once, start each run from the profile, and sign in again when the login expires.
