Python SDK
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-sdkThe 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()| Argument | Default | Meaning |
|---|---|---|
steel_api_key | STEEL_API_KEY | The API key. The SDK sends it in the steel-api-key header. |
base_url | STEEL_BASE_URL, then https:// | The URL of the API. Change it to use a self-hosted Steel Browser. |
timeout | 60 seconds, 5 seconds to connect | How long one HTTP request can take. A number of seconds or an httpx.. |
max_retries | 2 | How many times the SDK retries a request that failed. |
default_headers | none | Headers to send with every request. |
default_query | none | Query parameters to send with every request. |
http_client | an httpx client | A custom httpx., or httpx. 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.
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.pyThe program prints the session's ID.
0128f557-f063-4db9-b97b-48092ee22e8eTo 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 Timeout409 Conflict429 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 raisessteel.APITimeoutError, a subclass of it. - When the API returns a 4xx or 5xx status, the SDK raises a subclass of
steel.APIStatusError. It hasstatus_code,responseandbody, 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)| Status | Error class |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| 500 or higher | InternalServerError |
| No response | APIConnectionError |
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.
| Methods | API reference |
|---|---|
client., client., client. | Sessions API |
client., client., client. | Quick actions API |
client. | Profiles API |
client. | Credentials API |
client. | Files API |
client. | Extensions API |
client. | Projects API |
client. | API keys API |
The SDK's own list of methods and types is api.md.