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 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.
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightgo mod init profiles
go get github.com/steel-dev/sdk/gocargo new profiles
cd profiles
cargo add steel-rs
cargo add tokio --features macros,rt-multi-threadIn Go and Rust, install only the SDK, as the Go and Rust 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.
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);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:
npx tsx save-profile.mtspython save_profile.pyThe program prints the profile's ID and status. Keep the ID, because the next sections use it.
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READYTo save a login, sign in during this session, with your code or by hand in the 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.
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.
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);
}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:
PROFILE_ID=f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 npx tsx use-profile.mtsPROFILE_ID=f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 python use_profile.pyThe program prints the value from the first session.
darkA session that starts from a profile does not change the profile. To save the session's changes, see 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.
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.
const session = await client.sessions.create({
profileId: process.env.PROFILE_ID,
persistProfile: true,
});session = client.sessions.create(
profile_id=os.environ["PROFILE_ID"],
persist_profile=True,
)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
}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.
import { createReadStream } from "node:fs";
const profile = await client.profiles.update(process.env.PROFILE_ID!, {
userDataDir: createReadStream("profile.zip"),
});with open("profile.zip", "rb") as user_data_dir:
profile = client.profiles.update(
os.environ["PROFILE_ID"],
user_data_dir=user_data_dir,
)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
}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 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.
const { profiles, count } = await client.profiles.list();
console.log(count);
for (const profile of profiles) {
console.log(profile.id, profile.status);
}result = client.profiles.list()
print(result.count)
for profile in result.profiles:
print(profile.id, profile.status)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)
}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:
980
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY
52bb1668-ce32-4229-8698-2b269294e76d READY980
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY
52bb1668-ce32-4229-8698-2b269294e76d READY980
52bb1668-ce32-4229-8698-2b269294e76d READY
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY980
52bb1668-ce32-4229-8698-2b269294e76d Ready
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 ReadyTo 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.
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 shows. The session has what the first session stored, such as the localStorage value dark that the program prints.
Troubleshooting
profile_not_ready
{
"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 does.
Verify: client.profiles.get returns the status READY, and the new session starts.
profile_upload_failed
{
"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
{
"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: Sign in once, start each run from the profile, and sign in again when the login expires.