---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/sessions/timeouts
markdown_url: https://steel.dev/docs/sessions/timeouts.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Set timeouts
description: Set how long a session can live with timeout, and how long it can sit idle with inactivityTimeout, within your plan's maximum.
summary: Set how long a session can live with timeout, and how long it can sit idle with inactivityTimeout, within your plan's maximum.
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/devices.md
  - https://steel.dev/docs/sessions/metadata.md
  - https://steel.dev/docs/sessions/bandwidth.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Set timeouts

Two timeouts end a session that you did not release. `timeout` is the longest time that the session can live. `inactivityTimeout` ends it earlier when nothing drives the browser. Set both so that a crashed or stalled program does not leave a browser running longer than the task needs. Your plan sets the longest `timeout` that you can ask for.

Both values are in milliseconds, and you set them when you create the session. You cannot change them on a live session.

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable, and install the Steel SDK for your language: [TypeScript](https://steel.dev/docs/reference/sdks/typescript#install), [Python](https://steel.dev/docs/reference/sdks/python#install), [Go](https://steel.dev/docs/reference/sdks/go#install) or [Rust](https://steel.dev/docs/reference/sdks/rust#install).

## Set the session timeout

`timeout` defaults to 300000, which is 5 minutes. When the time is up, Steel releases the session, even if your program still uses it. The shortest timeout is 15000. Steel raises a smaller value to 15000. In Python, the option is named `api_timeout`, because `timeout` sets the HTTP request's time limit. In Go and Rust, it is `Timeout` and `timeout`.

This program creates a session that can live for 10 minutes, prints its timeout, and releases it.

**TypeScript**

```ts file=timeout.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create({ timeout: 600000 });

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

**Python**

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

client = Steel()
session = client.sessions.create(api_timeout=600000)

try:
    print(session.timeout)
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{
		Timeout: steel.F(int64(600000)),
	})
	if err != nil {
		return err
	}
	defer func() {
		if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
			log.Print(err)
		}
	}()

	fmt.Println(session.Timeout)
	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 {
            timeout: Some(600000),
            ..Default::default()
        })
        .await?;

    let result: Result<(), Box<dyn std::error::Error>> = async {
        println!("{}", session.timeout);
        Ok(())
    }
    .await;

    client.sessions().release(&session.id).await?;
    result
}
```

Run the program:

**TypeScript**

```sh
npx tsx timeout.mts
```

**Python**

```sh
python timeout.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

```text nocopy
600000
```

Ask for the time that the task needs, with a margin. A long timeout costs nothing when you release the session on time. The timeout sets the most that you pay when your program fails to release the session.

## Release idle sessions

`inactivityTimeout` releases the session when it receives no activity for that long. Activity is a CDP command, a [Commands](https://steel.dev/docs/control/commands) request, or input from a person in the [live view](https://steel.dev/docs/observability/live-view). These [computer actions](https://steel.dev/docs/control/computer-actions) also count: `move_mouse`, `click_mouse`, `drag_mouse`, `scroll`, `press_key` and `type_text`. The other computer actions, such as `take_screenshot` and `wait`, do not. Each activity starts the count again. Without `inactivityTimeout`, a session stays alive until its `timeout`, even when nothing drives it.

This session can live for 10 minutes, and ends after 1 minute without activity:

**TypeScript**

```ts
const session = await client.sessions.create({
  timeout: 600000,
  inactivityTimeout: 60000,
});
```

**Python**

```python
session = client.sessions.create(
    api_timeout=600000,
    inactivity_timeout=60000,
)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	Timeout:           steel.F(int64(600000)),
	InactivityTimeout: steel.F(int64(60000)),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        timeout: Some(600000),
        inactivity_timeout: Some(60000),
        ..Default::default()
    })
    .await?;
```

Set `inactivityTimeout` lower than `timeout`. If it is equal or greater, it has no effect, because `timeout` ends the session first.

Time that your agent spends on a model call, or that a person spends reading the page, sends no activity to the browser. Choose a value that is longer than your task's longest pause.

## Check that it worked

The session object has the timeouts that it runs with: `timeout`, and `inactivityTimeout` when you set one. The program in [Set the session timeout](https://steel.dev/docs/sessions/timeouts#set-the-session-timeout) prints `600000`. To see `inactivityTimeout` work, create a session with it and do nothing in the session. Wait longer than that time, then read the session with `sessions.retrieve` (`Sessions.Get` in Go): its `status` is `released`, and its `releaseReason` is `inactivity_timeout`.

## Defaults

The defaults depend on what creates the session:

| Created by | `timeout` | `inactivityTimeout` |
| - | - | - |
| The API or an SDK | 5 minutes | None |
| The [Steel CLI](https://steel.dev/docs/control/cli#drive-a-browser) or the [MCP server](https://steel.dev/docs/control/mcp-server#limits) | 15 minutes. Change it with `--timeout` in the CLI, or `timeout_minutes` on `session_create`. | 10 minutes. In the CLI, change it with `--inactivity-timeout`. |

## Plan limits

The longest `timeout` depends on your plan. [Limits](https://steel.dev/docs/platform/limits) lists the maximum session length for each plan. A request with a longer `timeout` fails, and no session is created. The response has the code `session_timeout_exceeded`. See [Troubleshooting](https://steel.dev/docs/sessions/timeouts#troubleshooting).

## Troubleshooting

Read `releaseReason` on the session to learn why it ended. See [Create a session](https://steel.dev/docs/sessions) for how to read it.

### `releaseReason` is `timeout`

```json nocopy
{ "status": "released", "releaseReason": "timeout" }
```

**Cause:** The session reached its `timeout` before your program released it. Steel released it, and your program's connection closed.

**Fix:** Create the session with a larger `timeout`, within your plan's maximum. If the task should have ended sooner, look for the step that waited, in the [logs](https://steel.dev/docs/observability/logs) or [agent traces](https://steel.dev/docs/observability/agent-traces).

**Verify:** Run the task again. When it is done, `releaseReason` is `user_requested`.

### `releaseReason` is `inactivity_timeout`

```json nocopy
{ "status": "released", "releaseReason": "inactivity_timeout" }
```

**Cause:** The session got no [activity](https://steel.dev/docs/sessions/timeouts#release-idle-sessions) for the time in `inactivityTimeout`. This happens when the agent waits on a slow model call, when a computer-use agent only takes screenshots, or when a person does not act in time.

**Fix:** Raise `inactivityTimeout` above the task's longest pause, or leave it out.

**Verify:** Run the task again. When it is done, `releaseReason` is `user_requested`.

### `session_timeout_exceeded`

```json nocopy
{
  "error": "Bad Request",
  "code": "session_timeout_exceeded",
  "message": "Requested 'timeout' of 3600000 ms exceeds the maximum of 15 minutes on the launch plan. Set 'timeout' to 900000 or less, or upgrade your plan for longer sessions.",
  "param": "timeout",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/pricinglimits"
}
```

**Cause:** `timeout` is longer than your plan's maximum session length. The message names your plan and its maximum.

**Fix:** Set `timeout` to the value in the message or lower. For longer sessions, change your plan in [Billing and usage](https://steel.dev/docs/platform/billing-and-usage).

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

## Next steps

- [Session lifecycle](https://steel.dev/docs/sessions/lifecycle): See the other ways that a session ends, besides its two timeouts.
- [Session cost](https://steel.dev/docs/production/session-cost): Read what a session cost when it ran until its timeout.
