Skip to content

Sessions

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

A session is one cloud browser that Steel runs for you. You create it with one API call, connect your code or agent to it, and release it when the work is done. Your plan sets how many sessions can run at the same time and how long each one can last. See Limits.

The programs on this page need the Steel SDK (npm install steel-sdk, or pip install steel-sdk in a virtual environment) and your API key in the STEEL_API_KEY environment variable. In Go and Rust, each program is the main.go of a module or the src/main.rs of a Cargo project, set up as the Go and Rust SDK pages show.

Create a session

Call sessions.create. With no options, Steel starts a desktop browser with a visible window, and releases it after 5 minutes. Session configuration lists every option that you can pass.

This program creates a session, prints its ID, status and session viewer URL, and releases it.

session.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create();

try {
  console.log(session.id);
  console.log(session.status);
  console.log(session.sessionViewerUrl);
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx session.mts

The program prints the session ID, the status live (Live in Rust), and the session viewer URL, which opens the session's page in the Steel dashboard.

9a209ccd-4ef4-44b6-a8e5-9035dad73115
live
https://app.steel.dev/sessions/9a209ccd-4ef4-44b6-a8e5-9035dad73115

Read the session

sessions.create returns the session object. To read it again later, call sessions.retrieve with the ID.

const session = await client.sessions.retrieve(sessionId);

These fields are the ones that you use most:

FieldWhat it holds
idThe session ID, a UUID. Every other call about the session takes it.
statuslive while the browser runs, then released, even after a crash. failed means that Steel could not start the browser.
websocketUrlThe browser's Chrome DevTools Protocol (CDP) URL. Connect Playwright or Puppeteer to it as it is: it holds a token for this session. See CDP.
debugUrlThe browser's live view. Open it, or embed it in your app. See Live view.
sessionViewerUrlThe session's page in the Steel dashboard. It shows the live view while the session runs, and the recording and logs after it ends.
releaseReasonWhy the session ended, such as user_requested, timeout or browser_crashed. It is null while the session is live.

The session object has more fields, such as the options that the session runs with. Create a session in the Sessions API lists the main ones. Session lifecycle explains each status and each release reason.

In TypeScript, releaseReason needs steel-sdk 0.21.0 or later.

List sessions

sessions.list returns your sessions, the newest first. Pass status to list only the live ones. The SDK fetches every page for you. In Go and Rust, the method that does this is ListAutoPaging or list_auto_paging.

list.mts
import Steel from "steel-sdk";

const client = new Steel();

for await (const session of client.sessions.list({ status: "live" })) {
  console.log(session.id, session.createdAt);
}

In Rust, the program also needs cargo add futures-util. Run the program:

npx tsx list.mts

The program prints one line for each live session. It prints nothing if no session is live.

552b8420-7af5-4628-a5fc-7cca1aad2ca5 2026-11-13T17:28:37.837Z
4e5863ca-fa1b-48f7-a910-c071579a8465 2026-11-13T17:28:37.334Z

By default, the list holds live and released sessions. It leaves out failed sessions unless you pass status or releaseReason. To narrow the list, pass one or more of these filters:

  • status: live, released or failed.
  • releaseReason: the reason that a session ended, such as timeout.
  • createdAfter and createdBefore: ISO 8601 times. createdAfter includes the exact time. createdBefore does not.
  • metadata: your own keys and values. See Add metadata.
  • signal: a label that Steel puts on a session after it ends. See Signals.

Every filter except status needs steel-sdk 0.21.0 or later, in TypeScript and in Python.

Release a session

Release a session as soon as the work is done. Steel bills a session until it ends, and a live session counts toward your limit of concurrent sessions. If you do not release it, the session runs until its timeout. See Set timeouts.

Call sessions.release with the ID. Put the call in finally, as the programs on this page do, so that an error in your code does not leave the browser running. In Go, put it in a defer. In Rust, call it after the async block.

const response = await client.sessions.release(session.id);
console.log(response);

In Rust, this code needs cargo add serde_json.

The response says that the session is released:

{ "success": true, "message": "Session released successfully." }

If the session has already ended, the call still succeeds, with the message Session already released. An unknown ID returns 404.

Closing the Playwright or Puppeteer connection does not release the session. The browser keeps running, and you can connect to it again.

Release all sessions

sessions.releaseAll (sessions.release_all in Python, Sessions.ReleaseAll in Go and sessions().release_all in Rust) releases every live session that your API key can reach. Use it to clean up after a crash, or in a test that must start with no session.

const response = await client.sessions.releaseAll();
console.log(response.message);
All sessions released successfully.

If Steel cannot release every session, the call fails with 503 and the message Could not release all active sessions. Retry the call.

What the call releases depends on the key:

  • An organization key releases the live sessions of every project in the organization. Pass projectId (project_id in Python and Rust, ProjectID in Go) to release the sessions of one project only.
  • A project key releases the live sessions of its own project only, whatever projectId you pass.

Check that it worked

After the program releases the session, read it with sessions.retrieve (Sessions.Get in Go) and the ID that the program printed. Its status is released, and its releaseReason is user_requested. Then run the program in List sessions. The session that you released is not in its output.

Troubleshooting

For an error that is not here, see Errors.

invalid_api_key

{
  "error": "Unauthorized",
  "code": "invalid_api_key",
  "message": "Invalid Steel API key. The key sent in the 'steel-api-key' header does not match any account. Create or rotate a key at https://app.steel.dev/settings/api-keys.",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/authentication"
}

Cause: The response has the status 401. The key in STEEL_API_KEY does not match an active key. It has a typo or a space at the end, or someone revoked it.

Fix: Copy the key again, or create a new one. See invalid_api_key.

Verify: Create the session again. The response has a session id.

insufficient_funds

{
  "error": "Payment Required",
  "code": "insufficient_funds",
  "message": "Your account is out of credits, so new sessions are refused. Add funds at https://app.steel.dev/settings/billing, then retry.",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/pricinglimits"
}

Cause: The response has the status 402. Your account has no credits left, so Steel refuses new sessions. Running sessions are not affected.

Fix: Add credits in Billing and usage. See insufficient_funds.

Verify: Create the session again. The response has a session id.

concurrency_limit_reached

{
  "error": "Too Many Requests",
  "code": "concurrency_limit_reached",
  "message": "Concurrent session limit reached for your launch plan (10 of 10 sessions running). Release a running session (POST /v1/sessions/{id}/release) before creating another, or upgrade your plan for a higher limit.",
  "retryable": true,
  "linkToDocs": "https://docs.steel.dev/overview/pricinglimits"
}

Cause: The response has the status 429. Your organization already runs as many sessions as its plan allows.

Fix: Release a session that you no longer need, or wait for one to end. See concurrency_limit_reached and Know your limits.

Verify: Create the session again. The response has a session id.

Next steps