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. For the error codes, see 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
GET/v1/sessions
Lists the sessions of your organization, one page at a time.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cursorId | string · query | No | The cursor of the page to return. Pass nextCursor from the previous page. |
limit | integer · query | No | Number of sessions to return, from 1 to 100.Default 50. |
status | string · query | No | Filter by status: live, released or failed. |
releaseReason | string · query | 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 | string (uuid) · query | No | Filter by project. |
createdAfter | string (date-time) · query | No | Only sessions created at or after this ISO 8601 time, such as 2026-10-01T00:00:00Z. |
createdBefore | string (date-time) · query | No | Only sessions created before this ISO 8601 time. |
signal | string[] · query | No | Signals that the session must have. Repeat the parameter to require several; all must match. See Signals reference. |
metadata | object · query | 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". |
Response
| Field | Type | Description |
|---|---|---|
sessions | object[] | The sessions on this page. Each one is a session object, as in 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. |
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.
curl "https://api.steel.dev/v1/sessions?status=live&limit=10" \
-H "steel-api-key: $STEEL_API_KEY"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);
}from steel import Steel
client = Steel()
for session in client.sessions.list(status="live"):
print(session.id, session.created_at)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
}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(())
}Create a session
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 explains each one, with its default, nested fields and limits.
Parameters
| Name | Type | Required |
|---|---|---|
blockAds | boolean · body | No |
caCertificates | string[] · body | No |
concurrency | integer · body | No |
credentials | object · body | No |
debugConfig | object · body | No |
deviceConfig | object · body | No |
dimensions | object · body | No |
experimentalFeatures | string[] · body | No |
extensionIds | string[] · body | No |
fullscreen | boolean · body | No |
headless | boolean · body | No |
inactivityTimeout | integer · body | No |
metadata | object · body | No |
namespace | string · body | No |
optimizeBandwidth | boolean or object · body | No |
persistProfile | boolean · body | No |
profileId | string (uuid) · body | No |
projectId | string (uuid) · body | No |
proxyUrl | string (uri) · body | No |
recording | boolean · body | No |
sessionContext | object · body | No |
solveCaptcha | boolean · body | No |
stealthConfig | object · body | No |
timeout | integer · body | No |
useProxy | boolean or object · body | No |
userAgent | string · body | No |
The response is 201 with the session object. Its main fields:
Response
| 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. |
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.
Release the session when you are done with it. See Create a session.
curl -X POST https://api.steel.dev/v1/sessions \
-H "steel-api-key: $STEEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"blockAds": true}'const session = await client.sessions.create({ blockAds: true });
try {
console.log(session.id, session.sessionViewerUrl);
} finally {
await client.sessions.release(session.id);
}session = client.sessions.create(block_ads=True)
try:
print(session.id, session.session_viewer_url)
finally:
client.sessions.release(session.id)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)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?;
resultGet a session
GET/v1/sessions/{id}
Returns one session.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
The response is the session object, with the fields in Create a session.
See Create a session.
curl https://api.steel.dev/v1/sessions/$SESSION_ID \
-H "steel-api-key: $STEEL_API_KEY"const session = await client.sessions.retrieve(sessionId);
console.log(session.status);session = client.sessions.retrieve(session_id)
print(session.status)session, err := client.Sessions.Get(ctx, sessionID)
if err != nil {
return err
}
fmt.Println(session.Status)let session = client.sessions().retrieve(&session_id).await?;
println!("{:?}", session.status);Release a session
POST/v1/sessions/{id}/release
Ends one session.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
Response
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the session was released. |
message | string | Details about the result. |
See Session lifecycle.
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/release \
-H "steel-api-key: $STEEL_API_KEY"await client.sessions.release(sessionId);client.sessions.release(session_id)if _, err := client.Sessions.Release(ctx, sessionID); err != nil {
return err
}client.sessions().release(&session_id).await?;Release all sessions
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) · query | No | Release only the sessions of this project. |
Response
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the sessions were released. |
message | string | Details about the result. |
See Session lifecycle.
curl -X POST "https://api.steel.dev/v1/sessions/release?projectId=$STEEL_PROJECT_ID" \
-H "steel-api-key: $STEEL_API_KEY"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);import os
result = client.sessions.release_all(project_id=os.environ["STEEL_PROJECT_ID"])
print(result.message)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)let result = client
.sessions()
.release_all(steel_rs::SessionReleaseAllParams {
project_id: Some(std::env::var("STEEL_PROJECT_ID")?),
})
.await?;
println!("{}", result.message);Signals
List signal definitions
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.
Response
| 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. |
See Signals.
curl https://api.steel.dev/v1/sessions/signals/catalog \
-H "steel-api-key: $STEEL_API_KEY"const catalog = await client.sessions.signalCatalog();
for (const signal of catalog.signals) {
console.log(signal.value, signal.label, signal.severity);
}catalog = client.sessions.signal_catalog()
for signal in catalog.signals:
print(signal.value, signal.label, signal.severity)catalog, err := client.Sessions.SignalCatalog(ctx)
if err != nil {
return err
}
for _, signal := range catalog.Signals {
fmt.Println(signal.Value, signal.Label, signal.Severity)
}let catalog = client.sessions().signal_catalog().await?;
for signal in catalog.signals {
println!("{:?} {} {:?}", signal.value, signal.label, signal.severity);
}Logs and agent traces
Get agent logs
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
namespace | string · query | No | The namespace to read. Steel uses the session's namespace when you leave it out. |
startTime | string (date-time) · query | No | Only events at or after this time. |
endTime | string (date-time) · query | No | Only events at or before this time. |
eventTypes | string[] · query | No | Ignored. This endpoint sets its own list of event types. |
limit | integer · query | No | Number of events to return, from 1 to 1000.Default 100. |
offset | integer · query | No | Number of events to skip.Default 0. |
Response
| 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.
For a timeline of clicks and typing, use Get agent traces. See Agent traces.
curl "https://api.steel.dev/v1/sessions/$SESSION_ID/agent-logs?limit=100" \
-H "steel-api-key: $STEEL_API_KEY"Get agent traces
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
namespace | string · query | No | The namespace to read. Steel uses the session's namespace when you leave it out. |
startTime | string (date-time) · query | No | Only entries at or after this time. |
endTime | string (date-time) · query | No | Only entries at or before this time. |
eventTypes | string[] · query | No | Ignored. This endpoint sets its own list of event types. |
limit | integer · query | No | Number of entries to return, from 1 to 1000. Without it, the response has the whole trace. |
offset | integer · query | No | Number of entries to skip.Default 0. |
Response
| 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.
See Agent traces.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \
-H "steel-api-key: $STEEL_API_KEY"const trace = await client.sessions.agentTraces(sessionId);
console.log(trace.total, trace.events.length);trace = client.sessions.agent_traces(session_id)
print(trace.total, len(trace.events))trace, err := client.Sessions.AgentTraces(ctx, sessionID, steel.SessionAgentTracesParams{})
if err != nil {
return err
}
fmt.Println(trace.Total, len(trace.Events))let trace = client
.sessions()
.agent_traces(&session_id, steel_rs::SessionAgentTracesParams::default())
.await?;
println!("{} {}", trace.total, trace.events.len());Get session logs
GET/v1/sessions/{id}/logs
Returns the browser logs of a session: console messages, page errors, network requests and page loads.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
namespace | string · query | No | The namespace to read. Steel uses the session's namespace when you leave it out. |
startTime | string (date-time) · query | No | Only events at or after this time. |
endTime | string (date-time) · query | No | Only events at or before this time. |
eventTypes | string[] · query | No | Only events of these types. |
limit | integer · query | No | Number of events to return, from 1 to 1000.Default 100. |
offset | integer · query | No | Number of events to skip.Default 0. |
Response
| 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. |
See Logs.
curl "https://api.steel.dev/v1/sessions/$SESSION_ID/logs?limit=100" \
-H "steel-api-key: $STEEL_API_KEY"const logs = await client.sessions.logs(sessionId, { limit: 100 });
for (const event of logs.events) {
console.log(event.timestamp, event.type);
}logs = client.sessions.logs(session_id, limit=100)
for event in logs.events:
print(event.timestamp, event.type)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)
}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);
}Session context
Get the session context
GET/v1/sessions/{id}/context
Returns a session's cookies and storage, in the form that sessionContext accepts when you create a session.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
Response
| Field | Type | Description |
|---|---|---|
cookies | object[] | The cookies, with the fields in sessionContext. |
localStorage | object | localStorage items, by domain. |
sessionStorage | object | sessionStorage items, by domain. |
indexedDB | object | IndexedDB items, by domain. |
See Session context.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/context \
-H "steel-api-key: $STEEL_API_KEY"const context = await client.sessions.context(sessionId);
console.log(context.cookies?.length);context = client.sessions.context(session_id)
print(len(context.cookies or []))sessionContext, err := client.Sessions.Context(ctx, sessionID)
if err != nil {
return err
}
fmt.Println(len(sessionContext.Cookies))let context = client.sessions().context(&session_id).await?;
println!("{}", context.cookies.unwrap_or_default().len());Cost
Get the session cost
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
Response
| 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). |
See Session cost.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/cost \
-H "steel-api-key: $STEEL_API_KEY"const cost = await client.sessions.cost(sessionId);
console.log(cost.totalCost);cost = client.sessions.cost(session_id)
print(cost.total_cost)cost, err := client.Sessions.Cost(ctx, sessionID)
if err != nil {
return err
}
fmt.Println(cost.TotalCost)let cost = client.sessions().cost(&session_id).await?;
println!("{}", cost.total_cost);Recordings
Get recorded events
GET/v1/sessions/{id}/events
Returns a session's recorded events, in the rrweb format.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
compressed | boolean · query | No | true returns the events as Steel stores them, packed with @rrweb/, which makes the response smaller. Unpack them with the package's unpack function.Default false. |
limit | integer · query | No | Number of events to return, from 1 to 1000.Default 1000. |
pointer | string · query | 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 shows. The Rust SDK does not return headers, so a Rust call reads one page.
See Recordings.
curl "https://api.steel.dev/v1/sessions/$SESSION_ID/events?limit=1000" \
-H "steel-api-key: $STEEL_API_KEY"const events = await client.sessions.events(sessionId, { limit: 1000 });
console.log(events.length);events = client.sessions.events(session_id, limit=1000)
print(len(events))events, err := client.Sessions.Events(ctx, sessionID, steel.SessionEventsParams{
Limit: steel.F(int64(1000)),
})
if err != nil {
return err
}
fmt.Println(len(*events))let events = client
.sessions()
.events(
&session_id,
steel_rs::SessionEventsParams {
limit: Some(1000),
..Default::default()
},
)
.await?;
println!("{}", events.len());Get the HLS playlist
GET/v1/sessions/{id}/hls
Returns the HLS playlist of a session's recording, as application/vnd.apple.mpegurl.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | 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 do.
See Recordings.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/hls \
-H "steel-api-key: $STEEL_API_KEY" \
-o recording.m3u8import { writeFile } from "node:fs/promises";
const playlist = await client.sessions.hls(sessionId);
await writeFile("recording.m3u8", await playlist.text());playlist = client.sessions.hls(session_id)
playlist.write_to_file("recording.m3u8")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
}let playlist = client.sessions().hls(&session_id).await?;
std::fs::write("recording.m3u8", playlist)?;Live details
Get live details
GET/v1/sessions/{id}/live-details
Returns a session's live state: its open pages and the URLs to view them.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
Response
| 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. |
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. |
See Live view.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/live-details \
-H "steel-api-key: $STEEL_API_KEY"const details = await client.sessions.liveDetails(sessionId);
console.log(details.pages.map((page) => page.url));details = client.sessions.live_details(session_id)
print([page.url for page in details.pages])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)let details = client.sessions().live_details(&session_id).await?;
let urls: Vec<String> = details.pages.into_iter().map(|page| page.url).collect();
println!("{urls:?}");Metadata
Update metadata
PATCH/v1/sessions/{id}/metadata
Merges keys into a session's metadata and returns the result.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
metadata | object · body | 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.
Response
| Field | Type | Description |
|---|---|---|
metadata | object | The merged metadata. Every value is a string. |
In Rust, this code needs cargo add serde_json. See Add metadata.
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}}'const { metadata } = await client.sessions.updateMetadata(sessionId, {
metadata: { outcome: "success", attempt: null },
});
console.log(metadata);result = client.sessions.update_metadata(
session_id,
metadata={"outcome": "success", "attempt": None},
)
print(result.metadata)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))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)?);Replace metadata
PUT/v1/sessions/{id}/metadata
Replaces all of a session's metadata. Send an empty object to clear it.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the session. |
metadata | object · body | 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.
Response
| Field | Type | Description |
|---|---|---|
metadata | object | The new metadata. Every value is a string. |
See Add metadata.
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"}}'await client.sessions.replaceMetadata(sessionId, {
metadata: { job_id: "job-1042" },
});client.sessions.replace_metadata(session_id, metadata={"job_id": "job-1042"})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
}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?;CAPTCHAs
Solve CAPTCHAs
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string (uuid) · path | Yes | The ID of the session. |
pageId | string · body | No | The ID of the page that has the CAPTCHA, from Get the CAPTCHA status. |
url | string · body | No | The URL of the page that has the CAPTCHA. |
taskId | string · body | No | The ID of one CAPTCHA task, from Get the CAPTCHA status. |
Response
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the action succeeded. |
message | string | A message about the result. |
See CAPTCHA solving.
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 '{}'const result = await client.sessions.captchas.solve(sessionId);
console.log(result.success);result = client.sessions.captchas.solve(session_id)
print(result.success)result, err := client.Sessions.Captchas.Solve(ctx, sessionID, steel.SessionCaptchaSolveParams{})
if err != nil {
return err
}
fmt.Println(result.Success)let result = client
.sessions()
.captchas()
.solve(&session_id, steel_rs::SessionCaptchaSolveParams::default())
.await?;
println!("{}", result.success);Solve an image CAPTCHA
POST/v1/sessions/{sessionId}/captchas/solve-image
Solves an image CAPTCHA. Steel reads the image and types the answer into the input.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string (uuid) · path | Yes | The ID of the session. |
imageXPath | string · body | Yes | The XPath of the CAPTCHA image. |
inputXPath | string · body | Yes | The XPath of the input for the answer. |
url | string · body | No | The URL of the page that has the CAPTCHA.Default The current page. |
Response
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the action succeeded. |
message | string | A message about the result. |
See CAPTCHA solving.
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\"]"}'const result = await client.sessions.captchas.solveImage(sessionId, {
imageXPath: '//img[@id="captcha-image"]',
inputXPath: '//input[@name="captcha"]',
});
console.log(result.success);result = client.sessions.captchas.solve_image(
session_id,
image_x_path='//img[@id="captcha-image"]',
input_x_path='//input[@name="captcha"]',
)
print(result.success)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)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);Get the CAPTCHA status
GET/v1/sessions/{sessionId}/captchas/status
Returns the CAPTCHA state of each page in a session.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string (uuid) · path | Yes | The ID of the session. |
The response is an array with one object for each page:
Response
| 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. |
See CAPTCHA solving.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/captchas/status \
-H "steel-api-key: $STEEL_API_KEY"const pages = await client.sessions.captchas.status(sessionId);
console.log(pages.map((page) => page.isSolvingCaptcha));pages = client.sessions.captchas.status(session_id)
print([page.is_solving_captcha for page in pages])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)let pages = client.sessions().captchas().status(&session_id).await?;
let solving: Vec<bool> = pages.iter().map(|page| page.is_solving_captcha).collect();
println!("{solving:?}");Commands
Call these endpoints over HTTP. The Steel CLI and the MCP server call them for you. To call them from your own agent, see Build your own agent harness.
Run commands
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
Idempotency-Key | string · header | No | A random value. A retry with the same key returns the stored result and does not run the commands again. |
commands | object or object[] · body | Yes | One command, or an array of up to 50. Commands reference lists each command and its fields. |
after | string · body | No | The next value of your last response. A retry with the same after and commands runs only once. |
observe | object · body | 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.
Response
| 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. |
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. |
See Commands.
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}]}'Get a command execution
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 returned the state running.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
executionId | string · path | Yes | The ID of the execution, such as x-1. |
The response has the same fields as Run commands.
See Commands.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/commands/executions/x-1 \
-H "steel-api-key: $STEEL_API_KEY"Cancel a command execution
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
executionId | string · path | Yes | The ID of the execution, such as x-1. |
The response has the same fields as Run commands.
See Commands.
curl -X POST https://api.steel.dev/v1/sessions/$SESSION_ID/commands/executions/x-1/cancel \
-H "steel-api-key: $STEEL_API_KEY"Computer actions
Run a computer action
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
action | string · body | Yes | move_mouse, click_mouse, drag_mouse, scroll, press_key, type_text, wait, take_screenshot or get_cursor_position. |
coordinates | number[] · body | for move_mouse | [x, y]. Used by move_mouse, click_mouse and scroll. |
button | string · body | No | click_mouse: left, right, middle, back or forward. back and forward click the left button.Default left. |
click_type | string · body | No | click_mouse: down, up or click. Ignored. Steel always clicks.Default click. |
num_clicks | number · body | No | click_mouse: number of clicks. 2 double-clicks; any other value clicks once.Default 1. |
path | number[][] · body | for drag_mouse | drag_mouse: an array of [x, y] pairs. |
delta_x | number · body | No | scroll: horizontal amount. Steel scrolls one wheel step in the direction of the larger delta.Default 0. |
delta_y | number · body | No | scroll: vertical amount. Steel scrolls one wheel step in the direction of the larger delta.Default 0. |
keys | string[] · body | for press_key | press_key: the keys to press. |
text | string · body | for type_text | type_text: the text to type. |
duration | number · body | for wait | wait: how long to wait, in seconds. Ignored for press_key. |
hold_keys | string[] · body | No | Keys to hold during the action. Ignored. Not for press_key, wait, take_screenshot or get_cursor_position. |
screenshot | boolean · body | No | Take a screenshot after the action. Not for take_screenshot or get_cursor_position. |
Response
| 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. |
See Computer actions.
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"}'const { base64_image } = await client.sessions.computer(sessionId, {
action: "take_screenshot",
});result = client.sessions.computer(session_id, action="take_screenshot")
image = result.base64_imageresult, err := client.Sessions.Computer(ctx, sessionID, steel.SessionComputerParams{
Body: steel.SessionComputerParamsBodyTakeScreenshot{
Action: steel.F(steel.SessionComputerParamsBodyTakeScreenshotActionTakeScreenshot),
},
})
if err != nil {
return err
}
image := result.Base64Imagelet result = client
.sessions()
.computer(
&session_id,
steel_rs::SessionComputerParams::TakeScreenshot(
steel_rs::SessionComputerParamsTakeScreenshot {},
),
)
.await?;
let image = result.base64_image;Session files
Upload a file to a session
POST/v1/sessions/{sessionId}/files
Adds a file to a session. The request is multipart/form-data.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
file | file or string · body | Yes | The file content, an http:// or https:// URL to download, or the path of a global file. |
path | string · body | No | The path of the file in the session, such as downloads/. |
Response
| 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. |
See Files.
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"import { createReadStream } from "node:fs";
const file = await client.sessions.files.upload(sessionId, {
file: createReadStream("resume.pdf"),
path: "resume.pdf",
});
console.log(file.path);from pathlib import Path
file = client.sessions.files.upload(
session_id,
file=Path("resume.pdf"),
path="resume.pdf",
)
print(file.path)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)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);List session files
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
Response
| Field | Type | Description |
|---|---|---|
data | object[] | The files, each with path, size in bytes and lastModified. |
See Files.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/files \
-H "steel-api-key: $STEEL_API_KEY"const files = await client.sessions.files.list(sessionId);
console.log(files.data.map((file) => file.path));files = client.sessions.files.list(session_id)
print([file.path for file in files.data])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)let files = client.sessions().files().list(&session_id).await?;
let paths: Vec<String> = files.data.into_iter().map(|file| file.path).collect();
println!("{paths:?}");Download a session file
GET/v1/sessions/{sessionId}/files/{path}
Downloads one file from a session.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
path | string · path | Yes | The path of the file. It can contain /. |
The response is the file, as application/octet-stream.
See Files.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/files/report.csv \
-H "steel-api-key: $STEEL_API_KEY" \
-o report.csvconst response = await client.sessions.files.download(sessionId, "report.csv");
const csv = await response.text();response = client.sessions.files.download("report.csv", session_id=session_id)
response.write_to_file("report.csv")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)let response = client
.sessions()
.files()
.download(&session_id, "report.csv")
.await?;
let csv = String::from_utf8(response.to_vec())?;Download all session files
GET/v1/sessions/{sessionId}/files.zip
Downloads all of a session's files in one ZIP archive.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
The response is the archive, as application/zip.
See Files.
curl https://api.steel.dev/v1/sessions/$SESSION_ID/files.zip \
-H "steel-api-key: $STEEL_API_KEY" \
-o files.zipimport { writeFile } from "node:fs/promises";
const response = await client.sessions.files.downloadArchive(sessionId);
await writeFile("files.zip", Buffer.from(await response.arrayBuffer()));response = client.sessions.files.download_archive(session_id)
response.write_to_file("files.zip")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
}let response = client
.sessions()
.files()
.download_archive(&session_id)
.await?;
std::fs::write("files.zip", response)?;Delete a session file
DELETE/v1/sessions/{sessionId}/files/{path}
Deletes one file from a session.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
path | string · path | Yes | The path of the file. It can contain /. |
The response is 204 with no body.
See Files.
curl -X DELETE https://api.steel.dev/v1/sessions/$SESSION_ID/files/report.csv \
-H "steel-api-key: $STEEL_API_KEY"await client.sessions.files.delete(sessionId, "report.csv");client.sessions.files.delete("report.csv", session_id=session_id)if err := client.Sessions.Files.Delete(ctx, sessionID, "report.csv"); err != nil {
return err
}client
.sessions()
.files()
.delete(&session_id, "report.csv")
.await?;Delete all session files
DELETE/v1/sessions/{sessionId}/files
Deletes all of a session's files.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string · path | Yes | The ID of the session. |
The response is 204 with no body.
See Files.
curl -X DELETE https://api.steel.dev/v1/sessions/$SESSION_ID/files \
-H "steel-api-key: $STEEL_API_KEY"await client.sessions.files.deleteAll(sessionId);client.sessions.files.delete_all(session_id)if err := client.Sessions.Files.DeleteAll(ctx, sessionID); err != nil {
return err
}client.sessions().files().delete_all(&session_id).await?;