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, Python, Go or Rust.
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.
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);
}from steel import Steel
client = Steel()
session = client.sessions.create(api_timeout=600000)
try:
print(session.timeout)
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{
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
}#[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:
npx tsx timeout.mtspython timeout.pygo run .cargo run600000Ask 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 request, or input from a person in the live view. These 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:
const session = await client.sessions.create({
timeout: 600000,
inactivityTimeout: 60000,
});session = client.sessions.create(
api_timeout=600000,
inactivity_timeout=60000,
)session, err := client.Sessions.New(ctx, steel.SessionNewParams{
Timeout: steel.F(int64(600000)),
InactivityTimeout: steel.F(int64(60000)),
})
if err != nil {
return err
}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 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 or the MCP server | 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 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.
Troubleshooting
Read releaseReason on the session to learn why it ended. See Create a session for how to read it.
releaseReason is timeout
{ "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 or agent traces.
Verify: Run the task again. When it is done, releaseReason is user_requested.
releaseReason is inactivity_timeout
{ "status": "released", "releaseReason": "inactivity_timeout" }Cause: The session got no activity 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
{
"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.
Verify: Create the session again. The response has a session id.