Sessions
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.
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);
}from steel import Steel
client = Steel()
session = client.sessions.create()
try:
print(session.id)
print(session.status)
print(session.session_viewer_url)
finally:
client.sessions.release(session.id)package main
import (
"context"
"fmt"
"log"
"github.com/steel-dev/sdk/go"
)
func main() {
if err := run(context.Background()); err != nil {
log.Fatal(err)
}
}
func run(ctx context.Context) error {
client := steel.NewClient()
session, err := client.Sessions.New(ctx, steel.SessionNewParams{})
if err != nil {
return err
}
defer func() {
if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
log.Print(err)
}
}()
fmt.Println(session.ID)
fmt.Println(session.Status)
fmt.Println(session.SessionViewerURL)
return nil
}#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = steel_rs::Client::new();
let session = client
.sessions()
.create(steel_rs::SessionCreateParams::default())
.await?;
let result: Result<(), Box<dyn std::error::Error>> = async {
println!("{}", session.id);
println!("{:?}", session.status);
println!("{}", session.session_viewer_url);
Ok(())
}
.await;
client.sessions().release(&session.id).await?;
result
}Run the program:
npx tsx session.mtspython session.pygo run .cargo runThe 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-9035dad73115bd41e647-dc3e-4384-acb3-0a43e76023ca
live
https://app.steel.dev/sessions/bd41e647-dc3e-4384-acb3-0a43e76023ca87f9441a-16c3-4d8f-af1a-7371bc7a2eba
live
https://app.steel.dev/sessions/87f9441a-16c3-4d8f-af1a-7371bc7a2eba76135c2d-b653-48ea-9d9f-1564f09b4fd1
Live
https://app.steel.dev/sessions/76135c2d-b653-48ea-9d9f-1564f09b4fd1Read 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);session = client.sessions.retrieve(session_id)session, err := client.Sessions.Get(ctx, sessionID)
if err != nil {
return err
}let session = client.sessions().retrieve(&session_id).await?;These fields are the ones that you use most:
| Field | What it holds |
|---|---|
id | The session ID, a UUID. Every other call about the session takes it. |
status | live while the browser runs, then released, even after a crash. failed means that Steel could not start the browser. |
websocketUrl | The 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. |
debugUrl | The browser's live view. Open it, or embed it in your app. See Live view. |
sessionViewerUrl | The session's page in the Steel dashboard. It shows the live view while the session runs, and the recording and logs after it ends. |
releaseReason | Why 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.
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);
}from steel import Steel
client = Steel()
for session in client.sessions.list(status="live"):
print(session.id, session.created_at)package main
import (
"context"
"fmt"
"log"
"github.com/steel-dev/sdk/go"
)
func main() {
if err := run(context.Background()); err != nil {
log.Fatal(err)
}
}
func run(ctx context.Context) error {
client := steel.NewClient()
iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
Status: steel.F(steel.SessionListParamsStatusLive),
})
for iter.Next() {
session := iter.Current()
fmt.Println(session.ID, session.CreatedAt)
}
if err := iter.Err(); err != nil {
return err
}
return nil
}use futures_util::StreamExt;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = steel_rs::Client::new();
let sessions = client
.sessions()
.list_auto_paging(steel_rs::SessionListParams {
status: Some(steel_rs::SessionListParamsStatus::Live),
..Default::default()
});
let mut sessions = std::pin::pin!(sessions);
while let Some(session) = sessions.next().await {
let session = session?;
println!("{} {}", session.id, session.created_at);
}
Ok(())
}In Rust, the program also needs cargo add futures-util. Run the program:
npx tsx list.mtspython list.pygo run .cargo runThe 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.334Z98c5132b-ad34-41b7-8680-9d7c4230d4ad 2026-11-13 17:28:42.559000+00:00
0b4f7993-7dbc-4a86-b41e-bd603c2f581d 2026-11-13 17:28:42.028000+00:00ed6c554b-f881-4989-a94c-949b52d60629 2026-11-11 02:38:19.828 +0000 UTC
97991af4-dfa1-4d42-9a70-2c64b7018bed 2026-11-11 02:38:19.313 +0000 UTC3a0956c0-fdc4-4c35-9740-50dc33dcc2bb 2026-11-11T02:38:23.724Z
76bd2913-384c-4cbf-81d4-2a1db84aebc0 2026-11-11T02:38:23.266ZBy 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,releasedorfailed.releaseReason: the reason that a session ended, such astimeout.createdAfterandcreatedBefore: ISO 8601 times.createdAfterincludes the exact time.createdBeforedoes 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);response = client.sessions.release(session.id)
print(response)import "encoding/json"
defer func() {
response, err := client.Sessions.Release(ctx, session.ID)
if err != nil {
log.Print(err)
return
}
out, err := json.MarshalIndent(response, "", " ")
if err != nil {
log.Print(err)
return
}
fmt.Println(string(out))
}()let response = client.sessions().release(&session.id).await?;
println!("{}", serde_json::to_string_pretty(&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);response = client.sessions.release_all()
print(response.message)response, err := client.Sessions.ReleaseAll(ctx, steel.SessionReleaseAllParams{})
if err != nil {
return err
}
fmt.Println(response.Message)let response = client
.sessions()
.release_all(steel_rs::SessionReleaseAllParams::default())
.await?;
println!("{}", 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_idin Python and Rust,ProjectIDin Go) to release the sessions of one project only. - A project key releases the live sessions of its own project only, whatever
projectIdyou 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
- Connect Playwright to Steel: Drive the session from your code.