SOP 008: Browser Profiles

Fresh

Field	Value
SOP ID	SOP-008
Version	1.0
Status	Active
Source	Steel Profiles API

Overview

Persist complete browser state (auth, cookies, extensions, credentials, settings) across sessions using profiles. Think of it as saving a browser identity.

Prerequisites

• Steel account with API key
• steel-sdk installed

Profile Lifecycle

Procedure

Step 1: Create Session with Profile Persistence

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

// Do your browsing, login, etc.
// Profile is saved when session releases

Step 2: Reuse Profile in New Session

const secondSession = await client.sessions.create({
  profileId: firstSession.profileId
});
// Starts with same cookies, auth, extensions, settings!

Step 3: Update Profile with New Data

// Pass both profileId AND persistProfile to accumulate state
const thirdSession = await client.sessions.create({
  profileId: firstSession.profileId,
  persistProfile: true
});
// New browsing data will be saved to the profile

Step 4: Manual Profile Management

// Create profile manually with custom data
await client.profiles.create({
  userDataDir: fs.readFileSync('path/to/userDataDir.zip'),
  userAgent: 'Mozilla/5.0 ...'
});

// Update profile metadata
await client.profiles.update(profileId, {
  userAgent: 'Mozilla/5.0 (updated)...'
});

Limits

Constraint	Value
Max profile size	300 MB
Auto-deletion	After 30 days unused
Failed uploads	Profile set to FAILED state, unusable

Profile States

State	Description
UPLOADING	Profile being created, session still active
READY	Profile saved, available for use
FAILED	Upload failed (usually > 300 MB), cannot be used

Verification Checklist

• [ ] Session created with persistProfile: true
• [ ] Profile ID returned in session response
• [ ] New session with profileId starts with saved state
• [ ] Cookies and auth persist across sessions
• [ ] Profile size under 300 MB limit

Troubleshooting

Issue	Solution
Profile in FAILED state	Reduce profile size (< 300 MB), create fresh
Auth not persisting	Ensure persistProfile: true on the session where you logged in
Profile auto-deleted	Use profile within 30 days to prevent cleanup
Stale profile data	Create new session with both profileId and persistProfile: true

See Also

• SOP 005: Reuse Auth Context
• SOP 006: Manage Extensions
• SOP 007: Credentials API