Session Lifecycle

Learn how to start and release browser sessions programmatically.

Overview

Sessions are the foundation of browser automation in Steel. Each session represents an isolated browser instance that persists until it's either explicitly released or times out.

Each session can be in one of three states:

  • Live: The session is active and ready to accept commands/connections. This is the state right after creation and during normal operation.

  • Released: The session has been intentionally shut down, either through explicit release or timeout. Resources have been cleaned up. Can no longer accept commands/connections.

  • Failed: Something went wrong during the session's lifetime (like a crash or connection loss). These sessions are automatically cleaned up.

Browser sessions are billed by the minute, rounded up. Launch sessions can last up to 15 minutes, Scale sessions up to 1 hour, and Enterprise sessions up to 24 hours. See Pricing/Limits for current rates and limits.

Understanding how sessions live and die helps you manage resources effectively and build more reliable applications.

Tying a Session to Your Own Records

To track a session in your own system, such as a job row that you write before the browser starts, put your own ID in metadata and save the id that create returns.

Custom session IDs are deprecated

Passing your own sessionId to create is deprecated, and Steel will reject it in a future release. Steel generates every session ID, because the ID records where the session runs. Put your own ID in metadata instead.

1
import { randomUUID } from 'node:crypto';
2
import Steel from 'steel-sdk';
3
4
const client = new Steel();
5
6
// Write your own record first, then create the session with its ID in metadata.
7
const jobId = randomUUID();
8
await jobs.insert({ jobId, status: 'starting' });
9
10
const session = await client.sessions.create({ metadata: { job_id: jobId } });
11
await jobs.update(jobId, { sessionId: session.id, status: 'running' });

If your process stops before it saves session.id, find the session by its job_id and release it. See Find Sessions by Metadata.

1
for await (const session of client.sessions.list({ metadata: { job_id: jobId } })) {
2
await client.sessions.release(session.id);
3
}

Use the id that create returns everywhere after that:

  • client.sessions.release(session.id) to end the session

  • client.sessions.files.list(session.id) and the rest of the Files API

  • wss://connect.steel.dev?apiKey=<key>&sessionId=<session.id> to attach Playwright or Puppeteer

Session Lifetime and Timeout

When you start a session, it stays alive for 5 minutes by default but you can change it by passing the timeout parameter, up to your plan's maximum session time. After the time passes, the session will be automatically released.

1
import Steel from 'steel-sdk';
2
3
const client = new Steel();
4
5
// Create session and keep it running for 10 minutes.
6
const session = await client.sessions.create({
7
timeout: 600000 // 10 minutes (NOTE: Units are in milliseconds)
8
});

Note: Currently, Steel doesn’t support editing the timeout duration of a live session.

Inactivity Timeout

By default a session runs until its timeout elapses, even when nothing is driving the browser. Set inactivityTimeout to release the session early once it stops seeing activity—any CDP command, Commands API request, or remote input—so you don’t keep paying for an idle browser while waiting on an external step.

1
import Steel from 'steel-sdk';
2
3
const client = new Steel();
4
5
// Release the session after 1 minute with no CDP or input activity,
6
// capped at a 10-minute hard limit.
7
const session = await client.sessions.create({
8
timeout: 600000, // 10 minutes (hard cap)
9
inactivityTimeout: 60000, // release after 1 minute of inactivity
10
});

Note: timeout is always the hard cap on a session’s lifetime. If inactivityTimeout is greater than or equal to timeout it has no effect—timeout elapses first. Omit inactivityTimeout to disable inactivity-based release (the default).

Releasing a Session

When you're done with a session, it's best practice to release it explicitly rather than waiting for the timeout. You can release a session any time before the timeout is up by calling the release method.

1
// Release a single session
2
const response = await client.sessions.release(session.id);

Bulk Session Release

Sometimes you need to clean up all active sessions at once. Steel provides a convenient way to do this:

1
// Release all active sessions
2
const response = await client.sessions.releaseAll();
3
console.log(response.message); // "All sessions released successfully"

Why a Session Ended

Every released or failed session has a releaseReason. It is null while the session is live, and for sessions created before Steel tracked the reason.

type: info Reading releaseReason in TypeScript needs steel-sdk 0.21.0 or later. Filtering by it in Find Past Sessions needs 0.21.0 or later in TypeScript and Python.

1
const session = await client.sessions.retrieve(sessionId);
2
3
console.log(session.status, session.releaseReason);
releaseReasonMeaning
user_requestedYou released the session through the API or SDK.
timeoutThe session reached its timeout.
inactivity_timeoutThe session had no activity for its inactivityTimeout.
creation_timeoutThe session did not start in time.
startup_failedSteel could not start the browser.
browser_closedThe browser or agent closed itself. This is not a crash.
browser_crashedThe browser crashed, or its machine stopped responding.

Find Past Sessions

sessions.list returns sessions newest first. Filter it by status, release reason, or creation time.

1
for await (const session of client.sessions.list({
2
releaseReason: 'timeout',
3
createdAfter: '2026-11-01T00:00:00Z',
4
createdBefore: '2026-11-02T00:00:00Z',
5
})) {
6
console.log(session.id, session.createdAt);
7
}
  • The list leaves out failed sessions unless you pass status or releaseReason. Pass status: 'failed' to list failed sessions.
  • releaseReason leaves out live sessions. Without status, it includes failed sessions with that reason.
  • createdAfter includes sessions created at that exact time. createdBefore does not. Both take ISO 8601 timestamps.
  • totalCount comes back only for status: 'live' with no metadata, signal, release reason, or date filter. For other lists, follow nextCursor until it is null. The SDK does this for you.

To filter by your own keys or by what happened during the session, see Session Metadata and Session Signals.

Need help building with the Sessions API?

Reach out to us on the #help channel on Discord under the ⭐ community section.

FAQ