---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/sessions/lifecycle
markdown_url: https://steel.dev/docs/sessions/lifecycle.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Session lifecycle
description: A session starts when you create it and ends when you release it or a timeout passes. Learn its states, its timeouts, and how billing follows them.
summary: A session starts when you create it and ends when you release it or a timeout passes.
type: concept
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/sessions.md
  - https://steel.dev/docs/sessions/configuration.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
---

# Session lifecycle

A session lasts from its creation until you release it, one of its timeouts passes, or its browser stops. Steel bills the browser for that time, so a session that you forget keeps costing money until a timeout ends it.

## States

A session's `status` is one of these values:

| Status | Meaning |
| - | - |
| `live` | The browser runs. You can connect to it, send commands and watch it. |
| `released` | The session ended. You released it, a timeout passed, or the browser closed or crashed. `releaseReason` says which. |
| `failed` | Steel could not start the browser. `releaseReason` is `startup_failed` or `creation_timeout`. |

A session is `live` after `sessions.create` returns. It then moves once, to `released`, and never returns to `live`. To keep working, create a new session. When Steel cannot start the browser, `sessions.create` returns an error. Steel can keep a record of the attempt, as a session with the status `failed`.

A crash does not make a session `failed`. To find the sessions whose browser crashed, list sessions with `releaseReason` set to `browser_crashed`.

`sessions.list` leaves out failed sessions unless you ask for them by `status` or `releaseReason`. [Create a session](https://steel.dev/docs/sessions) shows how to list and filter sessions.

## How a session ends

Each released or failed session has a `releaseReason` that says why it ended. It is `null` while the session is `live`. It can also be `null` after a session ends, when Steel has no record of why it ended, as for sessions from before Steel recorded reasons.

| `releaseReason` | What ended the session |
| - | - |
| `user_requested` | You released it through the API or SDK. |
| `timeout` | It reached its `timeout`. |
| `inactivity_timeout` | It had no activity for its `inactivityTimeout`. |
| `creation_timeout` | It did not start in time. |
| `startup_failed` | Steel could not start the browser. |
| `browser_closed` | The browser or agent closed itself. This is not a crash. |
| `browser_crashed` | The browser crashed, or its machine stopped responding. |

Release a session as soon as the work is done. `sessions.release` ends one session, and `sessions.releaseAll` (`release_all` in Python) ends every live session that your API key can reach. See [Release all sessions](https://steel.dev/docs/sessions#release-all-sessions). Release a session in a `finally` block, so that it ends even when your code fails. A release of a session that already ended returns `Session already released.`

## Timeouts

Two timeouts end a session that you do not release. You set both when you create the session, in milliseconds. You cannot change them on a live session.

- `timeout` is the longest that the session can live. [Set timeouts](https://steel.dev/docs/sessions/timeouts#defaults) has its default, and [Limits](https://steel.dev/docs/platform/limits) has the maximum for each plan.
- `inactivityTimeout` ends the session early when nothing drives it for that long. A CDP command, a Commands request, input from the live view and most computer actions count as activity. [Release idle sessions](https://steel.dev/docs/sessions/timeouts#release-idle-sessions) lists them. The option has no default. Without it, an idle session runs until its `timeout`.

In the Python SDK, the options are `api_timeout` and `inactivity_timeout`. A session timeout passed as `timeout` in Python is deprecated, because `timeout` there sets the HTTP request's timeout.

`timeout` is always the hard limit. An `inactivityTimeout` that is equal to `timeout` or longer has no effect.

Set `inactivityTimeout` when your code can stop without a release, for example when an agent hangs. The session then ends once it has been idle for its `inactivityTimeout`, not at the end of its `timeout`. The MCP server and the Steel CLI set an `inactivityTimeout` on the sessions that they create. [Set timeouts](https://steel.dev/docs/sessions/timeouts#defaults) lists their defaults.

[Set timeouts](https://steel.dev/docs/sessions/timeouts) shows how to set both.

## What you pay for

Steel bills browser time for a session from its start until it ends. The billed time never goes past the session's `timeout`. The rate depends on your plan, and [Pricing](https://steel.dev/docs/platform/pricing) has it.

A session can also add charges for [Steel proxy](https://steel.dev/docs/stealth/proxies) bandwidth and for each [CAPTCHA](https://steel.dev/docs/stealth/captcha-solving) that Steel solves. Steel adds up the final cost after the release. [Session cost](https://steel.dev/docs/production/session-cost) shows how to read it.

The cheapest session is one that ends as soon as its work is done. Release it explicitly, and use `inactivityTimeout` as a safety net.

## What remains after release

A released session has no browser, so a request that needs the browser fails. You cannot connect over CDP, send commands or read the session context. A Commands request returns `410` with `session_ended`.

The session itself stays, with its `id`, its `status` and its `releaseReason`. Some data becomes available only after the release:

- The [session cost](https://steel.dev/docs/production/session-cost) is final once Steel records the usage.
- The [signals](https://steel.dev/docs/observability/signals) appear a few seconds after the session ends.
- A [profile](https://steel.dev/docs/logins/profiles) that the session saved becomes ready to load.

The recording, logs, agent traces and files stay too. [About Steel](https://steel.dev/docs/get-started/about-steel) lists what each one holds. [Limits](https://steel.dev/docs/platform/limits#data-retention) says how long Steel keeps them.
