---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/api/sessions
markdown_url: https://steel.dev/docs/reference/api/sessions.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Sessions API
description: Create, list, get and release sessions with the Steel API, and work with their logs, recordings, metadata, commands, CAPTCHAs and files.
summary: Create, list, get and release sessions with the Steel API, and work with their logs, recordings, metadata, commands, CAPTCHAs and files.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/api.md
  - https://steel.dev/docs/reference/api/quick-actions.md
  - https://steel.dev/docs/reference/api/profiles.md
  - https://steel.dev/docs/reference/api/credentials.md
  - https://steel.dev/docs/reference/api/files.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Sessions API

A session is one cloud browser that Steel runs for you. These endpoints create, list, get and release sessions, and work with a session's logs, recordings, metadata, commands, files and more. For the base URL, authentication and pagination, see [API conventions](https://steel.dev/docs/reference/api). For the error codes, see [Errors](https://steel.dev/docs/reference/errors).

The first example is a complete program. The later examples use its `client`, and the ID of a session in `SESSION_ID` (cURL), `sessionId` (TypeScript), `session_id` (Python and Rust) or `sessionID` (Go).

## Sessions

### List sessions

```http
GET /v1/sessions
```

Lists the sessions of your organization, one page at a time.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `cursorId` | query | string | no | | The cursor of the page to return. Pass `nextCursor` from the previous page. |
| `limit` | query | integer | no | `50` | Number of sessions to return, from 1 to 100. |
| `status` | query | string | no | | Filter by status: `live`, `released` or `failed`. |
| `releaseReason` | query | string | no | | Filter released sessions by why they ended: `user_requested`, `timeout`, `inactivity_timeout`, `creation_timeout`, `startup_failed`, `browser_closed` or `browser_crashed`. Live sessions are excluded. Without `status`, failed sessions that match are included. |
| `projectId` | query | string (uuid) | no | | Filter by project. |
| `createdAfter` | query | string (date-time) | no | | Only sessions created at or after this ISO 8601 time, such as `2026-10-01T00:00:00Z`. |
| `createdBefore` | query | string (date-time) | no | | Only sessions created before this ISO 8601 time. |
| `signal` | query | string\[] | no | | Signals that the session must have. Repeat the parameter to require several; all must match. See [Signals reference](https://steel.dev/docs/reference/signals). |
| `metadata` | query | object | no | | Exact-match metadata filters, such as `metadata[environment]=production`. All entries must match. Numbers and booleans are stored as strings, so `metadata[attempt]=3` matches `3` and `"3"`. |

| Field | Type | Description |
| - | - | - |
| `sessions` | object\[] | The sessions on this page. Each one is a session object, as in [Create a session](https://steel.dev/docs/reference/api/sessions#create-a-session). |
| `nextCursor` | string or null | The cursor of the next page. `null` when there are no more pages. |
| `totalCount` | integer | The number of live sessions. Present only for `status=live` with no `metadata`, `signal`, `releaseReason`, `createdAfter` or `createdBefore` filter. |

**cURL**

```sh
curl "https://api.steel.dev/v1/sessions?status=live&limit=10" \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts file=list-sessions.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-sessions.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(())
}
```

The SDKs fetch the next page for you while you iterate. The method that does this is `ListAutoPaging` in Go and `list_auto_paging` in Rust. In Rust, the program also needs `cargo add futures-util`. See [Create a session](https://steel.dev/docs/sessions).

### Create a session

```http
POST /v1/sessions
```

Starts a new session and returns it. With a project key, every field of the body is optional, and a request with no body creates a session with the defaults. With an organization key, the body must have `projectId`.

The body has these top-level fields. [Session configuration](https://steel.dev/docs/sessions/configuration) explains each one, with its default, nested fields and limits.

| Name | In | Type | Required |
| - | - | - | - |
| `blockAds` | body | boolean | no |
| `caCertificates` | body | string\[] | no |
| `concurrency` | body | integer | no |
| `credentials` | body | object | no |
| `debugConfig` | body | object | no |
| `deviceConfig` | body | object | no |
| `dimensions` | body | object | no |
| `experimentalFeatures` | body | string\[] | no |
| `extensionIds` | body | string\[] | no |
| `fullscreen` | body | boolean | no |
| `headless` | body | boolean | no |
| `inactivityTimeout` | body | integer | no |
| `metadata` | body | object | no |
| `namespace` | body | string | no |
| `optimizeBandwidth` | body | boolean or object | no |
| `persistProfile` | body | boolean | no |
| `profileId` | body | string (uuid) | no |
| `projectId` | body | string (uuid) | no |
| `proxyUrl` | body | string (uri) | no |
| `recording` | body | boolean | no |
| `sessionContext` | body | object | no |
| `solveCaptcha` | body | boolean | no |
| `stealthConfig` | body | object | no |
| `timeout` | body | integer | no |
| `useProxy` | body | boolean or object | no |
| `userAgent` | body | string | no |

The response is `201` with the session object. Its main fields:

| Field | Type | Description |
| - | - | - |
| `id` | string (uuid) | The ID of the session. |
| `status` | string | `live`, `released` or `failed`. |
| `websocketUrl` | string | The CDP URL of the session's browser. Connect Playwright or Puppeteer to it as it is: it holds a token for this session, until the session ends. A session in the list of sessions has it without the token. |
| `debugUrl` | string | The URL of the live view, which you can open in a browser or embed in your app. See [Live view](https://steel.dev/docs/observability/live-view). |
| `sessionViewerUrl` | string | The session's page in the Steel dashboard. |
| `createdAt` | string (date-time) | When the session started. |
| `duration` | integer | How long the session ran, in milliseconds. |
| `timeout` | integer | The session timeout, in milliseconds. |
| `inactivityTimeout` | integer | The inactivity timeout, in milliseconds, if one was set. |
| `dimensions` | object | The `width` and `height` of the browser window, in pixels. |
| `profileId` | string (uuid) | The profile that the session started from, or that it saves to. |
| `projectId` | string (uuid) or null | The project that the session runs in. |
| `metadata` | object | Your metadata. Every value comes back as a string. |
| `browserMode` | string | `stealth`, `standard` or `unknown`. |
| `proxySource` | string or null | `steel`, `external`, or `null` with no proxy. |
| `proxyBytesUsed` | integer | Bytes sent and received through a proxy, whether a Steel proxy or your own. |
| `creditsUsed` | integer | Credits that the session used. |
| `eventCount` | integer | Number of events recorded in the session. |
| `signals` | string\[] | Signals observed in the session. Filled in a few seconds after the session ends. |
| `releaseReason` | string or null | Why the session ended, such as `user_requested` or `timeout`. `null` while it is live, and when Steel has no record of why it ended. |

The object also holds the options that the session was created with, such as `headless`, `solveCaptcha`, `stealthConfig`, `debugConfig`, `deviceConfig`, `optimizeBandwidth`, `persistProfile`, `fullscreen` and `userAgent`.

**cURL**

```sh
curl -X POST https://api.steel.dev/v1/sessions \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blockAds": true}'
```

**TypeScript**

```ts
const session = await client.sessions.create({ blockAds: true });

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

**Python**

```python
session = client.sessions.create(block_ads=True)

try:
    print(session.id, session.session_viewer_url)
finally:
    client.sessions.release(session.id)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	BlockAds: steel.F(true),
})
if err != nil {
	return err
}
defer func() {
	if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
		log.Print(err)
	}
}()

fmt.Println(session.ID, session.SessionViewerURL)
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        block_ads: Some(true),
        ..Default::default()
    })
    .await?;

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

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

Release the session when you are done with it. See [Create a session](https://steel.dev/docs/sessions).

### Get a session

```http
GET /v1/sessions/{id}
```

Returns one session.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |

The response is the session object, with the fields in [Create a session](https://steel.dev/docs/reference/api/sessions#create-a-session).

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

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

**Python**

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

**Go**

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

**Rust**

```rust
let session = client.sessions().retrieve(&session_id).await?;
println!("{:?}", session.status);
```

See [Create a session](https://steel.dev/docs/sessions).

### Release a session

```http
POST /v1/sessions/{id}/release
```

Ends one session.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Whether the session was released. |
| `message` | string | Details about the result. |

**cURL**

```sh
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/release \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
await client.sessions.release(sessionId);
```

**Python**

```python
client.sessions.release(session_id)
```

**Go**

```go
if _, err := client.Sessions.Release(ctx, sessionID); err != nil {
	return err
}
```

**Rust**

```rust
client.sessions().release(&session_id).await?;
```

See [Session lifecycle](https://steel.dev/docs/sessions/lifecycle).

### Release all sessions

```http
POST /v1/sessions/release
```

Releases the live sessions of one project, or of your whole organization. With an organization key and no `projectId`, it releases every live session in all of your organization's projects. With a project key, it releases only the sessions of the key's project. The examples read the project's ID from `STEEL_PROJECT_ID`, so that they never release the sessions of other projects.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `projectId` | query | string (uuid) | no | | Release only the sessions of this project. |

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Whether the sessions were released. |
| `message` | string | Details about the result. |

**cURL**

```sh
curl -X POST "https://api.steel.dev/v1/sessions/release?projectId=$STEEL_PROJECT_ID" \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const projectId = process.env.STEEL_PROJECT_ID;
if (!projectId) throw new Error("Set STEEL_PROJECT_ID");

const result = await client.sessions.releaseAll({ projectId });
console.log(result.message);
```

**Python**

```python
import os

result = client.sessions.release_all(project_id=os.environ["STEEL_PROJECT_ID"])
print(result.message)
```

**Go**

```go
import "os"

result, err := client.Sessions.ReleaseAll(ctx, steel.SessionReleaseAllParams{
	ProjectID: steel.F(os.Getenv("STEEL_PROJECT_ID")),
})
if err != nil {
	return err
}
fmt.Println(result.Message)
```

**Rust**

```rust
let result = client
    .sessions()
    .release_all(steel_rs::SessionReleaseAllParams {
        project_id: Some(std::env::var("STEEL_PROJECT_ID")?),
    })
    .await?;
println!("{}", result.message);
```

See [Session lifecycle](https://steel.dev/docs/sessions/lifecycle).

## Signals

### List signal definitions

```http
GET /v1/sessions/signals/catalog
```

Returns the label and meaning of each signal that a session can have. It holds no session data.

This endpoint takes no parameters.

| Field | Type | Description |
| - | - | - |
| `signals` | object\[] | One entry for each signal, with `value`, `label`, `description`, `severity` (`info`, `warning`, `danger` or `success`) and `source` (`manual` or `derived`). |
| `semantics` | string | How to read signals, and the limits of their coverage. |

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/signals/catalog \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const catalog = await client.sessions.signalCatalog();

for (const signal of catalog.signals) {
  console.log(signal.value, signal.label, signal.severity);
}
```

**Python**

```python
catalog = client.sessions.signal_catalog()

for signal in catalog.signals:
    print(signal.value, signal.label, signal.severity)
```

**Go**

```go
catalog, err := client.Sessions.SignalCatalog(ctx)
if err != nil {
	return err
}

for _, signal := range catalog.Signals {
	fmt.Println(signal.Value, signal.Label, signal.Severity)
}
```

**Rust**

```rust
let catalog = client.sessions().signal_catalog().await?;

for signal in catalog.signals {
    println!("{:?} {} {:?}", signal.value, signal.label, signal.severity);
}
```

See [Signals](https://steel.dev/docs/observability/signals).

## Logs and agent traces

### Get agent logs

```http
GET /v1/sessions/{id}/agent-logs
```

Returns the raw input and navigation events that an agent sent to the browser over CDP, such as `Input.dispatchMouseEvent` and `Page.navigate`.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |
| `namespace` | query | string | no | | The namespace to read. Steel uses the session's namespace when you leave it out. |
| `startTime` | query | string (date-time) | no | | Only events at or after this time. |
| `endTime` | query | string (date-time) | no | | Only events at or before this time. |
| `eventTypes` | query | string\[] | no | | Ignored. This endpoint sets its own list of event types. |
| `limit` | query | integer | no | `100` | Number of events to return, from 1 to 1000. |
| `offset` | query | integer | no | `0` | Number of events to skip. |

| Field | Type | Description |
| - | - | - |
| `events` | object\[] | The input and navigation events on this page. |
| `total` | number | The number of events that match. |
| `hasMore` | boolean | Whether more events follow this page. |

The SDKs have no method for this endpoint.

```sh
curl "https://api.steel.dev/v1/sessions/$SESSION_ID/agent-logs?limit=100" \
  -H "steel-api-key: $STEEL_API_KEY"
```

For a timeline of clicks and typing, use [Get agent traces](https://steel.dev/docs/reference/api/sessions#get-agent-traces). See [Agent traces](https://steel.dev/docs/observability/agent-traces).

### Get agent traces

```http
GET /v1/sessions/{id}/agent-traces
```

Returns the agent trace of a session: one entry for each click, typed text, scroll, drag and navigation, with the element's role, accessible name and selectors.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |
| `namespace` | query | string | no | | The namespace to read. Steel uses the session's namespace when you leave it out. |
| `startTime` | query | string (date-time) | no | | Only entries at or after this time. |
| `endTime` | query | string (date-time) | no | | Only entries at or before this time. |
| `eventTypes` | query | string\[] | no | | Ignored. This endpoint sets its own list of event types. |
| `limit` | query | integer | no | | Number of entries to return, from 1 to 1000. Without it, the response has the whole trace. |
| `offset` | query | integer | no | `0` | Number of entries to skip. |

| Field | Type | Description |
| - | - | - |
| `events` | object\[] | The entries of the trace. |
| `total` | number | The number of entries that match. |
| `hasMore` | boolean | Whether more entries follow this page. |

When Steel captured no browser actions in the session, as in older sessions, it builds the trace from the session's raw CDP commands. A session with neither returns an empty list.

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const trace = await client.sessions.agentTraces(sessionId);
console.log(trace.total, trace.events.length);
```

**Python**

```python
trace = client.sessions.agent_traces(session_id)
print(trace.total, len(trace.events))
```

**Go**

```go
trace, err := client.Sessions.AgentTraces(ctx, sessionID, steel.SessionAgentTracesParams{})
if err != nil {
	return err
}
fmt.Println(trace.Total, len(trace.Events))
```

**Rust**

```rust
let trace = client
    .sessions()
    .agent_traces(&session_id, steel_rs::SessionAgentTracesParams::default())
    .await?;
println!("{} {}", trace.total, trace.events.len());
```

See [Agent traces](https://steel.dev/docs/observability/agent-traces).

### Get session logs

```http
GET /v1/sessions/{id}/logs
```

Returns the browser logs of a session: console messages, page errors, network requests and page loads.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |
| `namespace` | query | string | no | | The namespace to read. Steel uses the session's namespace when you leave it out. |
| `startTime` | query | string (date-time) | no | | Only events at or after this time. |
| `endTime` | query | string (date-time) | no | | Only events at or before this time. |
| `eventTypes` | query | string\[] | no | | Only events of these types. |
| `limit` | query | integer | no | `100` | Number of events to return, from 1 to 1000. |
| `offset` | query | integer | no | `0` | Number of events to skip. |

| Field | Type | Description |
| - | - | - |
| `events` | object\[] | The events, each with `id`, `timestamp`, `type` and `log`. |
| `total` | number | The number of events that match. |
| `hasMore` | boolean | Whether more events follow this page. |

**cURL**

```sh
curl "https://api.steel.dev/v1/sessions/$SESSION_ID/logs?limit=100" \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const logs = await client.sessions.logs(sessionId, { limit: 100 });
for (const event of logs.events) {
  console.log(event.timestamp, event.type);
}
```

**Python**

```python
logs = client.sessions.logs(session_id, limit=100)
for event in logs.events:
    print(event.timestamp, event.type)
```

**Go**

```go
logs, err := client.Sessions.Logs(ctx, sessionID, steel.SessionLogsParams{
	Limit: steel.F(int64(100)),
})
if err != nil {
	return err
}
for _, event := range logs.Events {
	fmt.Println(event.Timestamp, event.Type)
}
```

**Rust**

```rust
let logs = client
    .sessions()
    .logs(
        &session_id,
        steel_rs::SessionLogsParams {
            limit: Some(100),
            ..Default::default()
        },
    )
    .await?;
for event in logs.events {
    println!("{} {}", event.timestamp, event.r#type);
}
```

See [Logs](https://steel.dev/docs/observability/logs).

## Session context

### Get the session context

```http
GET /v1/sessions/{id}/context
```

Returns a session's cookies and storage, in the form that `sessionContext` accepts when you create a session.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |

| Field | Type | Description |
| - | - | - |
| `cookies` | object\[] | The cookies, with the fields in [sessionContext](https://steel.dev/docs/sessions/configuration#sessioncontext). |
| `localStorage` | object | `localStorage` items, by domain. |
| `sessionStorage` | object | `sessionStorage` items, by domain. |
| `indexedDB` | object | IndexedDB items, by domain. |

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/context \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const context = await client.sessions.context(sessionId);
console.log(context.cookies?.length);
```

**Python**

```python
context = client.sessions.context(session_id)
print(len(context.cookies or []))
```

**Go**

```go
sessionContext, err := client.Sessions.Context(ctx, sessionID)
if err != nil {
	return err
}
fmt.Println(len(sessionContext.Cookies))
```

**Rust**

```rust
let context = client.sessions().context(&session_id).await?;
println!("{}", context.cookies.unwrap_or_default().len());
```

See [Session context](https://steel.dev/docs/logins/session-context).

## Cost

### Get the session cost

```http
GET /v1/sessions/{id}/cost
```

Returns the final cost of a released session in US dollars, to six decimal places. For a few seconds after the release, until Steel writes the final usage, it returns a `totalCost` of `0`, so wait about 5 seconds after the release before you call it.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |

| Field | Type | Description |
| - | - | - |
| `id` | string (uuid) | The ID of the session. |
| `totalCost` | number | The total cost in US dollars, such as `0.031905`. |
| `currency` | string | Always `usd`. |
| `unit` | string | Always `dollar`. |
| `usage` | object | The billable usage: `browser` (`value` and `unit`, `minute` or `second`), `proxy` (`bytes`) and `captcha` (`solves`). |

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/cost \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const cost = await client.sessions.cost(sessionId);
console.log(cost.totalCost);
```

**Python**

```python
cost = client.sessions.cost(session_id)
print(cost.total_cost)
```

**Go**

```go
cost, err := client.Sessions.Cost(ctx, sessionID)
if err != nil {
	return err
}
fmt.Println(cost.TotalCost)
```

**Rust**

```rust
let cost = client.sessions().cost(&session_id).await?;
println!("{}", cost.total_cost);
```

See [Session cost](https://steel.dev/docs/production/session-cost).

## Recordings

### Get recorded events

```http
GET /v1/sessions/{id}/events
```

Returns a session's recorded events, in the rrweb format.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |
| `compressed` | query | boolean | no | `false` | `true` returns the events as Steel stores them, packed with `@rrweb/packer`, which makes the response smaller. Unpack them with the package's `unpack` function. |
| `limit` | query | integer | no | `1000` | Number of events to return, from 1 to 1000. |
| `pointer` | query | string | no | | The page to return. Pass the value of the `Next-Cursor` response header. |

The response is one page of rrweb events. When more events are left, it has a `Next-Cursor` header. The SDK methods return only the events, so in TypeScript, Python and Go, read the header from the raw response, as [Fetch the recording](https://steel.dev/docs/observability/recordings#fetch-the-recording) shows. The Rust SDK does not return headers, so a Rust call reads one page.

**cURL**

```sh
curl "https://api.steel.dev/v1/sessions/$SESSION_ID/events?limit=1000" \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const events = await client.sessions.events(sessionId, { limit: 1000 });
console.log(events.length);
```

**Python**

```python
events = client.sessions.events(session_id, limit=1000)
print(len(events))
```

**Go**

```go
events, err := client.Sessions.Events(ctx, sessionID, steel.SessionEventsParams{
	Limit: steel.F(int64(1000)),
})
if err != nil {
	return err
}
fmt.Println(len(*events))
```

**Rust**

```rust
let events = client
    .sessions()
    .events(
        &session_id,
        steel_rs::SessionEventsParams {
            limit: Some(1000),
            ..Default::default()
        },
    )
    .await?;
println!("{}", events.len());
```

See [Recordings](https://steel.dev/docs/observability/recordings).

### Get the HLS playlist

```http
GET /v1/sessions/{id}/hls
```

Returns the HLS playlist of a session's recording, as `application/vnd.apple.mpegurl`.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |

The response is an M3U8 playlist that a video player can play. The playlist is ready a few seconds after the session ends. Until then, the endpoint returns `404`, so ask again every 2 seconds, as the examples in [Recordings](https://steel.dev/docs/observability/recordings#fetch-the-recording) do.

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/hls \
  -H "steel-api-key: $STEEL_API_KEY" \
  -o recording.m3u8
```

**TypeScript**

```ts
import { writeFile } from "node:fs/promises";

const playlist = await client.sessions.hls(sessionId);
await writeFile("recording.m3u8", await playlist.text());
```

**Python**

```python
playlist = client.sessions.hls(session_id)
playlist.write_to_file("recording.m3u8")
```

**Go**

```go
import (
	"io"
	"os"
)

playlist, err := client.Sessions.Hls(ctx, sessionID)
if err != nil {
	return err
}
defer playlist.Body.Close()
body, err := io.ReadAll(playlist.Body)
if err != nil {
	return err
}
if err := os.WriteFile("recording.m3u8", body, 0o644); err != nil {
	return err
}
```

**Rust**

```rust
let playlist = client.sessions().hls(&session_id).await?;
std::fs::write("recording.m3u8", playlist)?;
```

See [Recordings](https://steel.dev/docs/observability/recordings).

## Live details

### Get live details

```http
GET /v1/sessions/{id}/live-details
```

Returns a session's live state: its open pages and the URLs to view them.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |

| Field | Type | Description |
| - | - | - |
| `pages` | object\[] | The open pages, each with `id`, `url`, `title`, `favicon`, and the `sessionViewerUrl` and `sessionViewerFullscreenUrl` of the live view of that page. In a headless session, these two URLs show only that page. See [Embed the live view in your app](https://steel.dev/docs/observability/live-view#embed-the-live-view-in-your-app). |
| `sessionViewerUrl` | string | The URL of the live view, the same URL as the session's `debugUrl`. It is not the dashboard page in the session's own `sessionViewerUrl`, which has the same name. |
| `sessionViewerFullscreenUrl` | string | The URL of the live view without its navigation controls. It hides them only in a headless session. |
| `wsUrl` | string | The CDP URL of the session's browser, with a token for this session in it. The token expires when the session ends. |

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/live-details \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const details = await client.sessions.liveDetails(sessionId);
console.log(details.pages.map((page) => page.url));
```

**Python**

```python
details = client.sessions.live_details(session_id)
print([page.url for page in details.pages])
```

**Go**

```go
details, err := client.Sessions.LiveDetails(ctx, sessionID)
if err != nil {
	return err
}
var urls []string
for _, page := range details.Pages {
	urls = append(urls, page.URL)
}
fmt.Println(urls)
```

**Rust**

```rust
let details = client.sessions().live_details(&session_id).await?;
let urls: Vec<String> = details.pages.into_iter().map(|page| page.url).collect();
println!("{urls:?}");
```

See [Live view](https://steel.dev/docs/observability/live-view).

## Metadata

### Update metadata

```http
PATCH /v1/sessions/{id}/metadata
```

Merges keys into a session's metadata and returns the result.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |
| `metadata` | body | object | yes | | Up to 100 keys to change. A string, a number or a boolean sets a key. `null` removes it. Keys that you leave out keep their values. |

The merged metadata must stay within 50 keys and 8192 bytes of UTF-8 JSON. Updates to different keys at the same time are all kept.

| Field | Type | Description |
| - | - | - |
| `metadata` | object | The merged metadata. Every value is a string. |

**cURL**

```sh
curl -X PATCH https://api.steel.dev/v1/sessions/$SESSION_ID/metadata \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"outcome": "success", "attempt": null}}'
```

**TypeScript**

```ts
const { metadata } = await client.sessions.updateMetadata(sessionId, {
  metadata: { outcome: "success", attempt: null },
});
console.log(metadata);
```

**Python**

```python
result = client.sessions.update_metadata(
    session_id,
    metadata={"outcome": "success", "attempt": None},
)
print(result.metadata)
```

**Go**

```go
import (
	"encoding/json"

	"github.com/steel-dev/sdk/go/shared"
)

result, err := client.Sessions.UpdateMetadata(ctx, sessionID, steel.SessionUpdateMetadataParams{
	Metadata: steel.F(map[string]steel.SessionUpdateMetadataParamsMetadataUnion{
		"outcome": shared.UnionString("success"),
		"attempt": nil,
	}),
})
if err != nil {
	return err
}
out, err := json.MarshalIndent(result.Metadata, "", "  ")
if err != nil {
	return err
}
fmt.Println(string(out))
```

**Rust**

```rust
let result = client
    .sessions()
    .update_metadata(
        &session_id,
        steel_rs::SessionUpdateMetadataParams::new(std::collections::HashMap::from([
            (
                "outcome".to_owned(),
                Some(steel_rs::SessionUpdateMetadataParamsMetadata::String(
                    "success".to_owned(),
                )),
            ),
            ("attempt".to_owned(), None),
        ])),
    )
    .await?;
println!("{}", serde_json::to_string_pretty(&result.metadata)?);
```

In Rust, this code needs `cargo add serde_json`. See [Add metadata](https://steel.dev/docs/sessions/metadata).

### Replace metadata

```http
PUT /v1/sessions/{id}/metadata
```

Replaces all of a session's metadata. Send an empty object to clear it.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the session. |
| `metadata` | body | object | yes | | The new metadata: up to 50 keys and 8192 bytes of UTF-8 JSON. Values are strings, numbers or booleans. |

When two replacements arrive at the same time, the last one wins. To change single keys, use [Update metadata](https://steel.dev/docs/reference/api/sessions#update-metadata).

| Field | Type | Description |
| - | - | - |
| `metadata` | object | The new metadata. Every value is a string. |

**cURL**

```sh
curl -X PUT https://api.steel.dev/v1/sessions/$SESSION_ID/metadata \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"job_id": "job-1042"}}'
```

**TypeScript**

```ts
await client.sessions.replaceMetadata(sessionId, {
  metadata: { job_id: "job-1042" },
});
```

**Python**

```python
client.sessions.replace_metadata(session_id, metadata={"job_id": "job-1042"})
```

**Go**

```go
import "github.com/steel-dev/sdk/go/shared"

if _, err := client.Sessions.ReplaceMetadata(ctx, sessionID, steel.SessionReplaceMetadataParams{
	Metadata: steel.F(map[string]steel.SessionReplaceMetadataParamsMetadataUnion{
		"job_id": shared.UnionString("job-1042"),
	}),
}); err != nil {
	return err
}
```

**Rust**

```rust
client
    .sessions()
    .replace_metadata(
        &session_id,
        steel_rs::SessionReplaceMetadataParams::new(std::collections::HashMap::from([(
            "job_id".to_owned(),
            steel_rs::SessionReplaceMetadataParamsMetadata::String("job-1042".to_owned()),
        )])),
    )
    .await?;
```

See [Add metadata](https://steel.dev/docs/sessions/metadata).

## CAPTCHAs

### Solve CAPTCHAs

```http
POST /v1/sessions/{sessionId}/captchas/solve
```

Starts solving CAPTCHAs in a session. With `pageId`, `url` or `taskId`, Steel solves that CAPTCHA. With none of them, it solves every CAPTCHA that it detected.

Use it when `stealthConfig.autoCaptchaSolving` is `false`.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string (uuid) | yes | | The ID of the session. |
| `pageId` | body | string | no | | The ID of the page that has the CAPTCHA, from [Get the CAPTCHA status](https://steel.dev/docs/reference/api/sessions#get-the-captcha-status). |
| `url` | body | string | no | | The URL of the page that has the CAPTCHA. |
| `taskId` | body | string | no | | The ID of one CAPTCHA task, from [Get the CAPTCHA status](https://steel.dev/docs/reference/api/sessions#get-the-captcha-status). |

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Whether the action succeeded. |
| `message` | string | A message about the result. |

**cURL**

```sh
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/captchas/solve \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**TypeScript**

```ts
const result = await client.sessions.captchas.solve(sessionId);
console.log(result.success);
```

**Python**

```python
result = client.sessions.captchas.solve(session_id)
print(result.success)
```

**Go**

```go
result, err := client.Sessions.Captchas.Solve(ctx, sessionID, steel.SessionCaptchaSolveParams{})
if err != nil {
	return err
}
fmt.Println(result.Success)
```

**Rust**

```rust
let result = client
    .sessions()
    .captchas()
    .solve(&session_id, steel_rs::SessionCaptchaSolveParams::default())
    .await?;
println!("{}", result.success);
```

See [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving).

### Solve an image CAPTCHA

```http
POST /v1/sessions/{sessionId}/captchas/solve-image
```

Solves an image CAPTCHA. Steel reads the image and types the answer into the input.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string (uuid) | yes | | The ID of the session. |
| `imageXPath` | body | string | yes | | The XPath of the CAPTCHA image. |
| `inputXPath` | body | string | yes | | The XPath of the input for the answer. |
| `url` | body | string | no | The current page | The URL of the page that has the CAPTCHA. |

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Whether the action succeeded. |
| `message` | string | A message about the result. |

**cURL**

```sh
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/captchas/solve-image \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imageXPath": "//img[@id=\"captcha-image\"]", "inputXPath": "//input[@name=\"captcha\"]"}'
```

**TypeScript**

```ts
const result = await client.sessions.captchas.solveImage(sessionId, {
  imageXPath: '//img[@id="captcha-image"]',
  inputXPath: '//input[@name="captcha"]',
});
console.log(result.success);
```

**Python**

```python
result = client.sessions.captchas.solve_image(
    session_id,
    image_x_path='//img[@id="captcha-image"]',
    input_x_path='//input[@name="captcha"]',
)
print(result.success)
```

**Go**

```go
result, err := client.Sessions.Captchas.SolveImage(ctx, sessionID, steel.SessionCaptchaSolveImageParams{
	ImageXPath: steel.F(`//img[@id="captcha-image"]`),
	InputXPath: steel.F(`//input[@name="captcha"]`),
})
if err != nil {
	return err
}
fmt.Println(result.Success)
```

**Rust**

```rust
let result = client
    .sessions()
    .captchas()
    .solve_image(
        &session_id,
        steel_rs::SessionCaptchaSolveImageParams::new(
            r#"//img[@id="captcha-image"]"#.to_owned(),
            r#"//input[@name="captcha"]"#.to_owned(),
        ),
    )
    .await?;
println!("{}", result.success);
```

See [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving).

### Get the CAPTCHA status

```http
GET /v1/sessions/{sessionId}/captchas/status
```

Returns the CAPTCHA state of each page in a session.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string (uuid) | yes | | The ID of the session. |

The response is an array with one object for each page:

| Field | Type | Description |
| - | - | - |
| `pageId` | string | The ID of the page. |
| `url` | string | The URL of the page. |
| `isSolvingCaptcha` | boolean | Whether Steel is solving a CAPTCHA on the page now. |
| `tasks` | array | The page's CAPTCHA tasks. |
| `created` | number | When the state was created, in milliseconds since the Unix epoch. |
| `lastUpdated` | number | When the state last changed, in milliseconds since the Unix epoch. |

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/captchas/status \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const pages = await client.sessions.captchas.status(sessionId);
console.log(pages.map((page) => page.isSolvingCaptcha));
```

**Python**

```python
pages = client.sessions.captchas.status(session_id)
print([page.is_solving_captcha for page in pages])
```

**Go**

```go
pages, err := client.Sessions.Captchas.Status(ctx, sessionID)
if err != nil {
	return err
}
var solving []bool
for _, page := range *pages {
	solving = append(solving, page.IsSolvingCaptcha)
}
fmt.Println(solving)
```

**Rust**

```rust
let pages = client.sessions().captchas().status(&session_id).await?;
let solving: Vec<bool> = pages.iter().map(|page| page.is_solving_captcha).collect();
println!("{solving:?}");
```

See [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving).

## Commands

Call these endpoints over HTTP. The [Steel CLI](https://steel.dev/docs/control/cli) and the [MCP server](https://steel.dev/docs/control/mcp-server) call them for you. To call them from your own agent, see [Build your own agent harness](https://steel.dev/docs/control/commands#build-your-own-agent-harness).

### Run commands

```http
POST /v1/sessions/{sessionId}/commands
```

Drives a session's browser with commands such as `snapshot`, `click` and `fill`. The commands run in order and stop at the first failure.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |
| `Idempotency-Key` | header | string | no | | A random value. A retry with the same key returns the stored result and does not run the commands again. |
| `commands` | body | object or object\[] | yes | | One command, or an array of up to 50. [Commands reference](https://steel.dev/docs/reference/commands) lists each command and its fields. |
| `after` | body | string | no | | The `next` value of your last response. A retry with the same `after` and `commands` runs only once. |
| `observe` | body | object | no | | Return a snapshot (`mode: "snapshot"`) or a diff (`mode: "diff"`) of the page after the commands. |

The request returns `200` even when a command fails, and the command's error is in `results`. Commands that ran before it are not undone.

| Field | Type | Description |
| - | - | - |
| `id` | string | The ID of the execution, such as `x-1`. Use it to get or cancel the execution. |
| `execution` | object | `id`, `state` (`running`, `completed`, `failed`, `cancelled` or `timeout`), `effect` (`none`, `applied` or `unknown`), `ran` and `replayed`. |
| `results` | object\[] | One result for each command that has finished. |
| `page` | object or null | The tab that the execution used: `tab`, `url` and `title`. |
| `next` | string | Send it as `after` in the next request. |
| `observe` | object | The snapshot or the diff that `observe` asked for. |
| `dialog` | object | A dialog that is open on the tab and blocks it. A `press` of `Enter` or `Escape` answers it. See [Dialogs](https://steel.dev/docs/reference/commands#dialogs). |
| `epochChanged` | boolean | Present with `after`. `true` when something else changed the session after the response whose `next` value you sent. |
| `bodyExpired` | boolean | Whether the large parts of a stored result have expired. |

```sh
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"commands": [{"command": "navigate", "url": "https://example.com"}, {"command": "snapshot", "interactive": true}]}'
```

See [Commands](https://steel.dev/docs/control/commands).

### Get a command execution

```http
GET /v1/sessions/{sessionId}/commands/executions/{executionId}
```

Waits up to 20 seconds for an execution to finish, then returns it. Use it when [Run commands](https://steel.dev/docs/reference/api/sessions#run-commands) returned the state `running`.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |
| `executionId` | path | string | yes | | The ID of the execution, such as `x-1`. |

The response has the same fields as [Run commands](https://steel.dev/docs/reference/api/sessions#run-commands).

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/commands/executions/x-1 \
  -H "steel-api-key: $STEEL_API_KEY"
```

See [Commands](https://steel.dev/docs/control/commands).

### Cancel a command execution

```http
POST /v1/sessions/{sessionId}/commands/executions/{executionId}/cancel
```

Stops an execution. The running command stops before its next input. Commands that already ran are not undone.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |
| `executionId` | path | string | yes | | The ID of the execution, such as `x-1`. |

The response has the same fields as [Run commands](https://steel.dev/docs/reference/api/sessions#run-commands).

```sh
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands/executions/x-1/cancel \
  -H "steel-api-key: $STEEL_API_KEY"
```

See [Commands](https://steel.dev/docs/control/commands).

## Computer actions

### Run a computer action

```http
POST /v1/sessions/{sessionId}/computer
```

Runs one mouse, keyboard or screenshot action in a session. The body is one action, and `action` decides which other fields it takes.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |
| `action` | body | string | yes | | `move_mouse`, `click_mouse`, `drag_mouse`, `scroll`, `press_key`, `type_text`, `wait`, `take_screenshot` or `get_cursor_position`. |
| `coordinates` | body | number\[] | for `move_mouse` | | `[x, y]`. Used by `move_mouse`, `click_mouse` and `scroll`. |
| `button` | body | string | no | `left` | `click_mouse`: `left`, `right`, `middle`, `back` or `forward`. `back` and `forward` click the left button. |
| `click_type` | body | string | no | `click` | `click_mouse`: `down`, `up` or `click`. Ignored. Steel always clicks. |
| `num_clicks` | body | number | no | `1` | `click_mouse`: number of clicks. `2` double-clicks; any other value clicks once. |
| `path` | body | number\[]\[] | for `drag_mouse` | | `drag_mouse`: an array of `[x, y]` pairs. |
| `delta_x` | body | number | no | `0` | `scroll`: horizontal amount. Steel scrolls one wheel step in the direction of the larger delta. |
| `delta_y` | body | number | no | `0` | `scroll`: vertical amount. Steel scrolls one wheel step in the direction of the larger delta. |
| `keys` | body | string\[] | for `press_key` | | `press_key`: the keys to press. |
| `text` | body | string | for `type_text` | | `type_text`: the text to type. |
| `duration` | body | number | for `wait` | | `wait`: how long to wait, in seconds. Ignored for `press_key`. |
| `hold_keys` | body | string\[] | no | | Keys to hold during the action. Ignored. Not for `press_key`, `wait`, `take_screenshot` or `get_cursor_position`. |
| `screenshot` | body | boolean | no | | Take a screenshot after the action. Not for `take_screenshot` or `get_cursor_position`. |

| Field | Type | Description |
| - | - | - |
| `base64_image` | string | The screenshot, in base64, when one was taken. |
| `output` | string | What the action did, as text, such as `Mouse left clicked at (100, 200)`. |
| `error` | string | The error, if the action failed. |
| `system` | string | Always `steel-browser`. |

**cURL**

```sh
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/computer \
  -H "steel-api-key: $STEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "take_screenshot"}'
```

**TypeScript**

```ts
const { base64_image } = await client.sessions.computer(sessionId, {
  action: "take_screenshot",
});
```

**Python**

```python
result = client.sessions.computer(session_id, action="take_screenshot")
image = result.base64_image
```

**Go**

```go
result, err := client.Sessions.Computer(ctx, sessionID, steel.SessionComputerParams{
	Body: steel.SessionComputerParamsBodyTakeScreenshot{
		Action: steel.F(steel.SessionComputerParamsBodyTakeScreenshotActionTakeScreenshot),
	},
})
if err != nil {
	return err
}
image := result.Base64Image
```

**Rust**

```rust
let result = client
    .sessions()
    .computer(
        &session_id,
        steel_rs::SessionComputerParams::TakeScreenshot(
            steel_rs::SessionComputerParamsTakeScreenshot {},
        ),
    )
    .await?;
let image = result.base64_image;
```

See [Computer actions](https://steel.dev/docs/control/computer-actions).

## Session files

### Upload a file to a session

```http
POST /v1/sessions/{sessionId}/files
```

Adds a file to a session. The request is `multipart/form-data`.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |
| `file` | body | file or string | yes | | The file content, an `http://` or `https://` URL to download, or the path of a [global file](https://steel.dev/docs/reference/api/files). |
| `path` | body | string | no | | The path of the file in the session, such as `downloads/report.pdf`. |

| Field | Type | Description |
| - | - | - |
| `path` | string | The path of the file in the session. |
| `size` | integer | The size in bytes. |
| `lastModified` | string (date-time) | When the file was created. |

**cURL**

```sh
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/files \
  -H "steel-api-key: $STEEL_API_KEY" \
  -F "file=@resume.pdf" \
  -F "path=resume.pdf"
```

**TypeScript**

```ts
import { createReadStream } from "node:fs";

const file = await client.sessions.files.upload(sessionId, {
  file: createReadStream("resume.pdf"),
  path: "resume.pdf",
});
console.log(file.path);
```

**Python**

```python
from pathlib import Path

file = client.sessions.files.upload(
    session_id,
    file=Path("resume.pdf"),
    path="resume.pdf",
)
print(file.path)
```

**Go**

```go
import (
	"io"
	"os"
)

resume, err := os.Open("resume.pdf")
if err != nil {
	return err
}
defer resume.Close()

file, err := client.Sessions.Files.Upload(ctx, sessionID, steel.SessionFileUploadParams{
	File: steel.F[io.Reader](resume),
	Path: steel.F("resume.pdf"),
})
if err != nil {
	return err
}
fmt.Println(file.Path)
```

**Rust**

```rust
let resume = steel_rs::Upload::open("resume.pdf").await?;
let file = client
    .sessions()
    .files()
    .upload(
        &session_id,
        steel_rs::SessionFileUploadParams {
            path: Some("resume.pdf".to_owned()),
            ..steel_rs::SessionFileUploadParams::new(resume)
        },
    )
    .await?;
println!("{}", file.path);
```

See [Files](https://steel.dev/docs/sessions/files).

### List session files

```http
GET /v1/sessions/{sessionId}/files
```

Lists a session's files. While the session runs, the newest file comes first. After the session ends, the files come in no set order.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |

| Field | Type | Description |
| - | - | - |
| `data` | object\[] | The files, each with `path`, `size` in bytes and `lastModified`. |

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/files \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const files = await client.sessions.files.list(sessionId);
console.log(files.data.map((file) => file.path));
```

**Python**

```python
files = client.sessions.files.list(session_id)
print([file.path for file in files.data])
```

**Go**

```go
files, err := client.Sessions.Files.List(ctx, sessionID)
if err != nil {
	return err
}
var paths []string
for _, file := range files.Data {
	paths = append(paths, file.Path)
}
fmt.Println(paths)
```

**Rust**

```rust
let files = client.sessions().files().list(&session_id).await?;
let paths: Vec<String> = files.data.into_iter().map(|file| file.path).collect();
println!("{paths:?}");
```

See [Files](https://steel.dev/docs/sessions/files).

### Download a session file

```http
GET /v1/sessions/{sessionId}/files/{path}
```

Downloads one file from a session.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |
| `path` | path | string | yes | | The path of the file. It can contain `/`. |

The response is the file, as `application/octet-stream`.

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/files/report.csv \
  -H "steel-api-key: $STEEL_API_KEY" \
  -o report.csv
```

**TypeScript**

```ts
const response = await client.sessions.files.download(sessionId, "report.csv");
const csv = await response.text();
```

**Python**

```python
response = client.sessions.files.download("report.csv", session_id=session_id)
response.write_to_file("report.csv")
```

**Go**

```go
import "io"

response, err := client.Sessions.Files.Download(ctx, sessionID, "report.csv")
if err != nil {
	return err
}
defer response.Body.Close()
body, err := io.ReadAll(response.Body)
if err != nil {
	return err
}
csv := string(body)
```

**Rust**

```rust
let response = client
    .sessions()
    .files()
    .download(&session_id, "report.csv")
    .await?;
let csv = String::from_utf8(response.to_vec())?;
```

See [Files](https://steel.dev/docs/sessions/files).

### Download all session files

```http
GET /v1/sessions/{sessionId}/files.zip
```

Downloads all of a session's files in one ZIP archive.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |

The response is the archive, as `application/zip`.

**cURL**

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/files.zip \
  -H "steel-api-key: $STEEL_API_KEY" \
  -o files.zip
```

**TypeScript**

```ts
import { writeFile } from "node:fs/promises";

const response = await client.sessions.files.downloadArchive(sessionId);
await writeFile("files.zip", Buffer.from(await response.arrayBuffer()));
```

**Python**

```python
response = client.sessions.files.download_archive(session_id)
response.write_to_file("files.zip")
```

**Go**

```go
import (
	"io"
	"os"
)

response, err := client.Sessions.Files.DownloadArchive(ctx, sessionID)
if err != nil {
	return err
}
defer response.Body.Close()
archive, err := io.ReadAll(response.Body)
if err != nil {
	return err
}
if err := os.WriteFile("files.zip", archive, 0o644); err != nil {
	return err
}
```

**Rust**

```rust
let response = client
    .sessions()
    .files()
    .download_archive(&session_id)
    .await?;
std::fs::write("files.zip", response)?;
```

See [Files](https://steel.dev/docs/sessions/files).

### Delete a session file

```http
DELETE /v1/sessions/{sessionId}/files/{path}
```

Deletes one file from a session.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |
| `path` | path | string | yes | | The path of the file. It can contain `/`. |

The response is `204` with no body.

**cURL**

```sh
curl -X DELETE https://api.steel.dev/v1/sessions/$SESSION_ID/files/report.csv \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
await client.sessions.files.delete(sessionId, "report.csv");
```

**Python**

```python
client.sessions.files.delete("report.csv", session_id=session_id)
```

**Go**

```go
if err := client.Sessions.Files.Delete(ctx, sessionID, "report.csv"); err != nil {
	return err
}
```

**Rust**

```rust
client
    .sessions()
    .files()
    .delete(&session_id, "report.csv")
    .await?;
```

See [Files](https://steel.dev/docs/sessions/files).

### Delete all session files

```http
DELETE /v1/sessions/{sessionId}/files
```

Deletes all of a session's files.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `sessionId` | path | string | yes | | The ID of the session. |

The response is `204` with no body.

**cURL**

```sh
curl -X DELETE https://api.steel.dev/v1/sessions/$SESSION_ID/files \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
await client.sessions.files.deleteAll(sessionId);
```

**Python**

```python
client.sessions.files.delete_all(session_id)
```

**Go**

```go
if err := client.Sessions.Files.DeleteAll(ctx, sessionID); err != nil {
	return err
}
```

**Rust**

```rust
client.sessions().files().delete_all(&session_id).await?;
```

See [Files](https://steel.dev/docs/sessions/files).
