---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/sessions
markdown_url: https://steel.dev/docs/sessions.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Sessions
description: Create a Steel session, read its connection details, list your sessions, and release one when the work is done.
summary: Create a Steel session, read its connection details, list your sessions, and release one when the work is done.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/sessions/lifecycle.md
related:
  - https://steel.dev/docs/sessions/configuration.md
  - https://steel.dev/docs/sessions/lifecycle.md
  - https://steel.dev/docs/sessions/timeouts.md
  - https://steel.dev/docs/sessions/devices.md
  - https://steel.dev/docs/sessions/metadata.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# 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](https://steel.dev/docs/platform/limits).

The programs on this page need the Steel SDK (`npm install steel-sdk`, or `pip install steel-sdk` in a [virtual environment](https://steel.dev/docs/reference/sdks/python#install)) 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](https://steel.dev/docs/reference/sdks/go#install) and [Rust](https://steel.dev/docs/reference/sdks/rust#install) 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](https://steel.dev/docs/sessions/configuration) lists every option that you can pass.

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

**TypeScript**

```ts file=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);
}
```

**Python**

```python file=session.py
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)
```

**Go**

```go file=main.go
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
}
```

**Rust**

```rust file=src/main.rs
#[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:

**TypeScript**

```sh
npx tsx session.mts
```

**Python**

```sh
python session.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

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.

**TypeScript**

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

**Python**

```text nocopy
bd41e647-dc3e-4384-acb3-0a43e76023ca
live
https://app.steel.dev/sessions/bd41e647-dc3e-4384-acb3-0a43e76023ca
```

**Go**

```text nocopy
87f9441a-16c3-4d8f-af1a-7371bc7a2eba
live
https://app.steel.dev/sessions/87f9441a-16c3-4d8f-af1a-7371bc7a2eba
```

**Rust**

```text nocopy
76135c2d-b653-48ea-9d9f-1564f09b4fd1
Live
https://app.steel.dev/sessions/76135c2d-b653-48ea-9d9f-1564f09b4fd1
```

## Read the session

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

**TypeScript**

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

**Python**

```python
session = client.sessions.retrieve(session_id)
```

**Go**

```go
session, err := client.Sessions.Get(ctx, sessionID)
if err != nil {
	return err
}
```

**Rust**

```rust
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](https://steel.dev/docs/control/cdp). |
| `debugUrl` | The browser's live view. Open it, or embed it in your app. See [Live view](https://steel.dev/docs/observability/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](https://steel.dev/docs/reference/api/sessions#create-a-session) in the Sessions API lists the main ones. [Session lifecycle](https://steel.dev/docs/sessions/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`.

**TypeScript**

```ts file=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);
}
```

**Python**

```python file=list.py
from steel import Steel

client = Steel()

for session in client.sessions.list(status="live"):
    print(session.id, session.created_at)
```

**Go**

```go file=main.go
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
}
```

**Rust**

```rust file=src/main.rs
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:

**TypeScript**

```sh
npx tsx list.mts
```

**Python**

```sh
python list.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

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

**TypeScript**

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

**Python**

```text nocopy
98c5132b-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:00
```

**Go**

```text nocopy
ed6c554b-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 UTC
```

**Rust**

```text nocopy
3a0956c0-fdc4-4c35-9740-50dc33dcc2bb 2026-11-11T02:38:23.724Z
76bd2913-384c-4cbf-81d4-2a1db84aebc0 2026-11-11T02:38:23.266Z
```

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](https://steel.dev/docs/sessions/metadata).
- `signal`: a label that Steel puts on a session after it ends. See [Signals](https://steel.dev/docs/observability/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](https://steel.dev/docs/sessions/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.

**TypeScript**

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

**Python**

```python
response = client.sessions.release(session.id)
print(response)
```

**Go**

```go
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))
}()
```

**Rust**

```rust
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:

```json nocopy
{ "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.

**TypeScript**

```ts
const response = await client.sessions.releaseAll();
console.log(response.message);
```

**Python**

```python
response = client.sessions.release_all()
print(response.message)
```

**Go**

```go
response, err := client.Sessions.ReleaseAll(ctx, steel.SessionReleaseAllParams{})
if err != nil {
	return err
}
fmt.Println(response.Message)
```

**Rust**

```rust
let response = client
    .sessions()
    .release_all(steel_rs::SessionReleaseAllParams::default())
    .await?;
println!("{}", response.message);
```

```text nocopy
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.

> **Warning**
>
> With an organization key, `releaseAll` also stops the sessions that other members and services of your organization run.

## 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](https://steel.dev/docs/sessions#list-sessions). The session that you released is not in its output.

## Troubleshooting

For an error that is not here, see [Errors](https://steel.dev/docs/reference/errors).

### `invalid_api_key`

```json nocopy
{
  "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`](https://steel.dev/docs/reference/errors#invalid-api-key).

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

### `insufficient_funds`

```json nocopy
{
  "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](https://steel.dev/docs/platform/billing-and-usage#add-credits). See [`insufficient_funds`](https://steel.dev/docs/reference/errors#insufficient-funds).

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

### `concurrency_limit_reached`

```json nocopy
{
  "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`](https://steel.dev/docs/reference/errors#concurrency-limit-reached) and [Know your limits](https://steel.dev/docs/production/run-sessions-at-scale#know-your-limits).

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

## Next steps

- [Connect Playwright to Steel](https://steel.dev/docs/integrations/playwright): Drive the session from your code.
