Skip to content

Python SDK

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

The Steel SDK for Python is the steel-sdk package on PyPI, imported as steel. It gives your code methods for the endpoints of the Steel API, and it retries failed requests and pages through lists for you. The API reference shows the call for each endpoint.

Install

Install the SDK in a virtual environment. Then python and pip run the Python that has the SDK, even on macOS, which has no python command of its own. In each new terminal, run source .venv/bin/activate again.

python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk

The SDK needs Python 3.10 or later. It has a synchronous client, Steel, and an asynchronous client, AsyncSteel, both built on httpx.

To use aiohttp instead of httpx in the asynchronous client, install the extra:

pip install 'steel-sdk[aiohttp]'

Then pass http_client=DefaultAioHttpClient() to AsyncSteel. Import DefaultAioHttpClient from steel.

Create a client

Steel() reads your API key from the STEEL_API_KEY environment variable. To change the key or another setting, pass keyword arguments.

from steel import Steel

client = Steel()
ArgumentDefaultMeaning
steel_api_keySTEEL_API_KEYThe API key. The SDK sends it in the steel-api-key header.
base_urlSTEEL_BASE_URL, then https://api.steel.devThe URL of the API. Change it to use a self-hosted Steel Browser.
timeout60 seconds, 5 seconds to connectHow long one HTTP request can take. A number of seconds or an httpx.Timeout.
max_retries2How many times the SDK retries a request that failed.
default_headersnoneHeaders to send with every request.
default_querynoneQuery parameters to send with every request.
http_clientan httpx clientA custom httpx.Client, or httpx.AsyncClient for AsyncSteel.

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

Set STEEL_LOG to info or debug to log requests with the standard logging module.

Create a session

This program creates a session, prints its ID, and releases it. A session runs until you release it or until it times out, so release it in finally.

session.py
from steel import Steel

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

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

Run the program:

python session.py

The program prints the session's ID.

0128f557-f063-4db9-b97b-48092ee22e8e

To drive the session's browser, connect Playwright over CDP (Chrome DevTools Protocol). See Playwright.

A method's arguments are snake_case, such as use_proxy and block_ads. Nested parameters are dictionaries. Responses are Pydantic models, with to_dict() and to_json(). Session configuration lists every option of a new session.

In sessions.create, the session timeout is api_timeout, in milliseconds. The timeout argument of any method is the HTTP timeout of that request.

The asynchronous client has the same methods. Use await with each call:

import asyncio

from steel import AsyncSteel

client = AsyncSteel()


async def main() -> None:
    session = await client.sessions.create()
    try:
        print(session.id)
    finally:
        await client.sessions.release(session.id)


asyncio.run(main())

Retries and timeouts

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

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

When a response has the x-should-retry header, the SDK follows it instead of this list. true retries, and false does not.

A request times out after one minute and then raises APITimeoutError. The SDK retries a request that timed out, so a call can take longer than its timeout.

Set max_retries and timeout on the client for all requests:

from steel import Steel

client = Steel(max_retries=0, timeout=20.0)

For a separate limit on each phase of the request, pass an httpx.Timeout:

import httpx
from steel import Steel

client = Steel(timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0))

To change the retries or the timeout for one call, use with_options:

client.with_options(max_retries=5, timeout=5.0).sessions.retrieve(session.id)

Handle errors

All errors of the SDK inherit from steel.APIError.

  • When the SDK cannot reach the API, it raises steel.APIConnectionError. A timeout raises steel.APITimeoutError, a subclass of it.
  • When the API returns a 4xx or 5xx status, the SDK raises a subclass of steel.APIStatusError. It has status_code, response and body, which is the response's JSON body.
import steel
from steel import Steel

client = Steel()

try:
    client.sessions.retrieve(session_id)
except steel.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)
except steel.RateLimitError:
    print("A 429 status code was received")
except steel.APIStatusError as e:
    print(e.status_code)
    print(e.body)
StatusError class
400BadRequestError
401AuthenticationError
403PermissionDeniedError
404NotFoundError
409ConflictError
422UnprocessableEntityError
429RateLimitError
500 or higherInternalServerError
No responseAPIConnectionError

Errors lists the error codes and messages of the API.

Pagination

client.sessions.list returns its results in pages. Iterate over the result to read every item. The SDK fetches the next page when it needs it.

for session in client.sessions.list(status="live"):
    print(session.id)

With AsyncSteel, use async for.

To read one page at a time, use has_next_page() and get_next_page():

page = client.sessions.list(status="live")
while True:
    for session in page.sessions:
        print(session.id)
    if not page.has_next_page():
        break
    page = page.get_next_page()

Methods

Each group of methods matches a page of the API reference. The methods take the same parameters as the endpoints, in snake_case.

MethodsAPI reference
client.sessions, client.sessions.files, client.sessions.captchasSessions API
client.scrape, client.screenshot, client.pdfQuick actions API
client.profilesProfiles API
client.credentialsCredentials API
client.filesFiles API
client.extensionsExtensions API
client.projectsProjects API
client.api_keysAPI keys API

The SDK's own list of methods and types is api.md.