Session

A Session is a stateful browser environment where AI agents execute tasks. Sessions maintain browser state, cookies, and context between multiple tasks.

What is a Session?

A persistent browser instance that:

• Executes multiple tasks sequentially
• Maintains login state between tasks
• Preserves cookies and browser state
• Provides real-time viewing via live URL

Key Properties

Response Fields

• id: Unique session identifier
• status: "active" or "stopped"
• liveUrl: Real-time browser viewing URL (null if stopped)
• tasks: All tasks executed in this session
• publicShareUrl: Public share URL (if share is active)
• startedAt / finishedAt: Session timestamps

Creation Parameters

• profileId: Profile for browser configuration (optional)
• proxyCountryCode: Proxy location (e.g., "us", "gb", "de")
• startUrl: URL to navigate to when session starts
• browserScreenWidth: Custom screen width in pixels (320-6144)
• browserScreenHeight: Custom screen height in pixels (320-3456)

Creating and Managing Sessions

1
import { BrowserUseClient } from "browser-use-sdk";
2
3
const client = new BrowserUseClient({ apiKey: "bu_..." });
4
5
// Create session with default settings (US proxy)
6
const session = await client.sessions.createSession();
7
8
// Create session with custom proxy and profile
9
const customSession = await client.sessions.createSession({
10
    profileId: "profile_123",
11
    proxyCountryCode: "us",  // US proxy
12
    browserScreenWidth: 1920,
13
    browserScreenHeight: 1080
14
});
15
16
// Manage sessions
17
const sessions = await client.sessions.listSessions();
18
await client.sessions.stopSession(session.id);
19
console.log(`Watch live: ${session.liveUrl}`);

Usage Patterns

Auto-Session (Implicit)

1
// Automatically creates and cleans up session
2
const task = await client.tasks.createTask({
3
    llm: "browser-use-llm",
4
    task: "Search for laptop prices on Amazon"
5
});

✅ Simple ❌ No state preservation ❌ No proxy customization (uses US by default)

Custom Session (Explicit)

1
// Create session with custom proxy (e.g., Germany)
2
const session = await client.sessions.createSession({
3
    profileId: "user_profile_123",
4
    proxyCountryCode: "de"
5
});
6
7
// Run multiple related tasks - all use the session's proxy
8
const loginTask = await client.tasks.createTask({
9
    sessionId: session.id,
10
    llm: "browser-use-llm",
11
    task: "Log into admin.example.com"
12
});
13
14
const dataTask = await client.tasks.createTask({
15
    sessionId: session.id,
16
    llm: "browser-use-llm",
17
    task: "Export user data"
18
});
19
20
// Cleanup
21
await client.sessions.stopSession(session.id);

✅ State preservation ✅ Multi-step workflows ✅ Custom proxy location ❌ Manual cleanup

State Management

What’s Preserved:

• Authentication cookies and tokens
• Local storage and session data
• Browser history and form data
• Downloaded resources and cache

Profile Inheritance:

1
// Session inherits login state from profile
2
const session = await client.sessions.createSession({ profileId: "logged_in_profile" });
3
4
// Already logged in from profile
5
const task = await client.tasks.createTask({
6
    sessionId: session.id,
7
    llm: "browser-use-llm",
8
    task: "Check dashboard notifications"
9
});

Real-Time Monitoring

Live URL (Private)

The liveUrl is a private URL for viewing your session in real-time. Only accessible to authenticated users with access to the session.

1
// Live viewing (private - requires authentication)
2
console.log(`Watch live: ${session.liveUrl}`);

Public Share

Create a public share link to allow anyone to view the session without authentication.

1
// Create public share
2
const share = await client.sessions.createPublicShare(session.id);
3
console.log(`Public URL: ${share.shareUrl}`);
4
console.log(`View count: ${share.viewCount}`);
5
6
// Get existing share info
7
const existingShare = await client.sessions.getPublicShare(session.id);
8
9
// Delete public share when done
10
await client.sessions.deletePublicShare(session.id);

Agent Session vs Browser Session

Browser Session (Standalone): Direct Chrome DevTools Protocol access for custom automation Agent Session (AI-Powered): AI agent environment for natural language task execution

These are separate products serving different use cases.

Best Practices

Use Auto-Session for: Simple tasks, no login, proof of concepts Use Custom Sessions for: Multi-step workflows, authentication, production apps

Session Management:

• Always stop sessions when done
• Use profiles to reduce setup time
• Don’t share live URLs publicly
• Clean up sessions with sensitive data

Next Steps