---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/sdks/rust
markdown_url: https://steel.dev/docs/reference/sdks/rust.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Rust SDK
description: Install the Steel Rust SDK, configure the client, and handle errors, retries, and pagination.
summary: Install the Steel Rust SDK, configure the client, and handle errors, retries, and pagination.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/sdks/typescript.md
  - https://steel.dev/docs/reference/sdks/python.md
  - https://steel.dev/docs/reference/sdks/go.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Rust SDK

The Steel SDK for Rust is the crate `steel-rs` on crates.io, used in code as `steel_rs`. It gives your code `async` methods for the endpoints of the Steel API, and it retries failed requests and pages through lists for you. The [API reference](https://steel.dev/docs/reference/api) shows the call for each endpoint.

## Install

Each Rust program in these docs is the `src/main.rs` of a Cargo project. The methods are `async`, so the SDK needs an async runtime. These commands create the project and add the SDK and Tokio:

```sh
cargo new example
cd example
cargo add steel-rs
cargo add tokio --features macros,rt-multi-thread
```

The SDK needs Rust 1.80 or later. It sends requests with `reqwest` over `rustls`.

## Create a client

`steel_rs::Client::new()` reads your API key from the `STEEL_API_KEY` environment variable and the base URL from `STEEL_BASE_URL`. To set the options in code, use the builder:

```rust
use std::time::Duration;

let client = steel_rs::Client::builder()
    .api_key(std::env::var("STEEL_API_KEY")?)
    .max_retries(5)
    .timeout(Duration::from_secs(20))
    .build();
```

| Builder method | Default | Meaning |
| - | - | - |
| `api_key` | `STEEL_API_KEY` | The API key. |
| `base_url` | `STEEL_BASE_URL`, then `https://api.steel.dev` | The URL of the API. Change it to use a [self-hosted Steel Browser](https://steel.dev/docs/self-hosting/steel-browser). |
| `max_retries` | `2` | How many times the SDK retries a request that failed. |
| `timeout` | 60 seconds | How long each attempt of a request can take. |
| `header` | none | A header to send with every request. Call it once for each header. |
| `http_client` | a new `reqwest::Client` | The `reqwest` client that sends the requests. |

The `STEEL_CUSTOM_HEADERS` environment variable adds headers to every request. Write one `Name: value` pair on each line.

`Client` keeps its state behind an `Arc`, so a clone shares the same settings and HTTP client. Accessors such as `client.sessions()` borrow the client.

## Create a session

This program creates a session, prints its ID, and releases it. A session runs until you release it or until it times out, so release it when the work is done.

```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);
        Ok(())
    }
    .await;

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

Run the program from the root of a Cargo project, with the file at `src/main.rs`:

```sh
cargo run
```

The program prints the session's ID.

```text nocopy
313385e8-469d-40c8-9509-7607521186b2
```

The program does its work in an `async` block and releases the session after the block. If a step in the block returns an error, the `?` ends the block, not the program, so the release still runs.

To drive the session's browser, connect a CDP (Chrome DevTools Protocol) client to `session.websocket_url`. The URL holds a token for the session, so the client needs no API key.

Params structs list every input of a method. A struct without required fields implements `Default`. A struct with required fields has a `new` constructor that takes only those fields. Set the other fields with struct update syntax:

```rust
let page = client
    .scrape(steel_rs::ScrapeParams {
        format: Some(vec![steel_rs::ScrapeParamsFormat::Markdown]),
        ..steel_rs::ScrapeParams::new("https://example.com".to_owned())
    })
    .await?;
```

[Session configuration](https://steel.dev/docs/sessions/configuration) lists every option of a new session.

## Retries and timeouts

The SDK retries a request twice, with exponential backoff, after one of these failures:

- a connection error or a timeout
- `408 Request Timeout`
- `409 Conflict`
- `429 Too Many Requests`
- a status of 500 or higher

A response with the `x-should-retry` header overrides this rule. This needs `steel-rs` 0.23.0 or later, because older versions do not read the header. When the response has a `retry-after` or `retry-after-ms` header of 60 seconds or less, the SDK waits that long before it retries.

Each attempt times out after 60 seconds. Change the number of retries and the timeout with `max_retries` and `timeout` on the builder, as in [Create a client](https://steel.dev/docs/reference/sdks/rust#create-a-client).

## Handle errors

Every method returns `Result<T, steel_rs::Error>`. The error is one of these variants:

| Variant | When |
| - | - |
| `Error::Api` | The API returned a status outside 2xx. It holds `status`, `body` and `headers`. |
| `Error::Http` | The request failed in `reqwest`, for example on a network error or a timeout. |
| `Error::Decode` | The SDK could not decode the response. |
| `Error::Invalid` | The current SDK does not return it. It holds a message as a `String`. |

`error.status()` returns the status of any error that has one, and `error.body()` returns the body of an `Error::Api`.

```rust
match client.sessions().retrieve(&session_id).await {
    Ok(session) => println!("{}", session.id),
    Err(error) => {
        println!("{:?}", error.status());
        println!("{:?}", error.body());
    }
}
```

[Errors](https://steel.dev/docs/reference/errors) lists the error codes and messages of the API.

## Pagination

A list method returns a `Page`. `next_page()` fetches the next one. Each list method also has an `_auto_paging` version that returns a `Stream` over every item.

```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!("{} started at {}", session.id, session.created_at);
    }
    Ok(())
}
```

This program also needs `futures-util`:

```sh
cargo add futures-util
```

## Methods

The Rust SDK has the methods of the other SDKs, with snake_case names. You reach each group of methods through an accessor on the client, such as `client.sessions()` or `client.sessions().files()`. `sessions.create` is `client.sessions().create`. Types are PascalCase and named by their path, such as `SessionCreateParams`.

The [API reference](https://steel.dev/docs/reference/api) documents each endpoint and its parameters. The types and methods of the crate are on [docs.rs](https://docs.rs/steel-rs).
