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

# TypeScript SDK

The Steel SDK for TypeScript and JavaScript is the `steel-sdk` package on npm. It gives your code typed methods for the endpoints of the Steel API, and it retries failed requests and pages through lists for you. The [API reference](https://steel.dev/docs/reference/api) shows the call for each endpoint.

## Install

```sh
npm install steel-sdk
```

The SDK supports TypeScript 4.5 or later and these runtimes:

- Node.js 18 LTS or later
- Deno 1.28.0 or later
- Bun 1.0 or later
- Cloudflare Workers and the Vercel Edge Runtime
- Up-to-date web browsers

React Native is not supported. In a web browser, do not give the SDK your API key, because anyone who opens the page can read it. See [Authentication](https://steel.dev/docs/reference/api#authentication).

## Create a client

`new Steel()` reads your API key from the `STEEL_API_KEY` environment variable. To change the key or another setting, pass options to the constructor.

```ts
import Steel from "steel-sdk";

const client = new Steel();
```

| Option | Default | Meaning |
| - | - | - |
| `steelAPIKey` | `process.env.STEEL_API_KEY` | The API key. The SDK sends it in the `steel-api-key` header. |
| `baseURL` | `process.env.STEEL_BASE_URL`, then `https://api.steel.dev` | The URL of the API. Change it to use a [self-hosted Steel Browser](https://steel.dev/docs/self-hosting/steel-browser). |
| `timeout` | `60000` | How long one HTTP request can take, in milliseconds. |
| `maxRetries` | `2` | How many times the SDK retries a request that failed. |
| `defaultHeaders` | none | Headers to send with every request. |
| `defaultQuery` | none | Query parameters to send with every request. |
| `fetch` | `node-fetch` in Node.js, the global `fetch` elsewhere | A custom `fetch` function, for example to log each request. |
| `httpAgent` | an agent that reuses connections | The HTTP agent for all requests, for example to send them through a proxy. |

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

## 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`.

```ts file=session.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create();

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

Run the program:

```sh
npx tsx session.mts
```

The program prints the session's ID.

```text nocopy
de987dce-13d0-4e2b-b70c-6d2fa9a189d0
```

To drive the session's browser, connect Playwright or Puppeteer over CDP (Chrome DevTools Protocol). See [Playwright](https://steel.dev/docs/integrations/playwright) and [Puppeteer](https://steel.dev/docs/integrations/puppeteer).

A method's options are camelCase, such as `useProxy` and `blockAds`. In `sessions.create`, `timeout` is the session timeout. [Session configuration](https://steel.dev/docs/sessions/configuration) lists every option of a new session.

## Retries and timeouts

The SDK retries a request twice, with 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 the response has the `x-should-retry` header, the SDK follows the header instead of this list. `true` retries and `false` does not. When the response has a `Retry-After` header, the SDK waits that long before it retries.

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

Set `maxRetries` and `timeout` on the client for all requests:

```ts
const client = new Steel({
  maxRetries: 0,
  timeout: 20 * 1000,
});
```

To change them for one call, pass them in the method's last argument. This argument holds the request options, not the API's parameters:

```ts
await client.sessions.retrieve(session.id, {
  maxRetries: 5,
  timeout: 5 * 1000,
});
```

## Handle errors

When the SDK cannot reach the API, or when the API returns a 4xx or 5xx status, the call throws a subclass of `Steel.APIError`. The error has `status`, `headers` and `error`, which is the response's JSON body.

```ts
try {
  await client.sessions.retrieve(sessionId);
} catch (err) {
  if (err instanceof Steel.APIError) {
    console.log(err.status);
    console.log(err.name);
    console.log(err.error);
  } else {
    throw err;
  }
}
```

| 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](https://steel.dev/docs/reference/errors) lists the error codes and messages of the API.

## Pagination

`client.sessions.list` returns its results in pages. Iterate with `for await` to read every item. The SDK fetches the next page when it needs it.

```ts
for await (const session of client.sessions.list({ status: "live" })) {
  console.log(session.id);
}
```

To read one page at a time, use `hasNextPage()` and `getNextPage()`:

```ts
let page = await client.sessions.list({ status: "live" });
while (true) {
  for (const session of page.sessions) {
    console.log(session.id);
  }
  if (!page.hasNextPage()) {
    break;
  }
  page = await page.getNextPage();
}
```

## Methods

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

| Methods | API reference |
| - | - |
| `client.sessions`, `client.sessions.files`, `client.sessions.captchas` | [Sessions API](https://steel.dev/docs/reference/api/sessions) |
| `client.scrape`, `client.screenshot`, `client.pdf` | [Quick actions API](https://steel.dev/docs/reference/api/quick-actions) |
| `client.profiles` | [Profiles API](https://steel.dev/docs/reference/api/profiles) |
| `client.credentials` | [Credentials API](https://steel.dev/docs/reference/api/credentials) |
| `client.files` | [Files API](https://steel.dev/docs/reference/api/files) |
| `client.extensions` | [Extensions API](https://steel.dev/docs/reference/api/extensions) |
| `client.projects` | [Projects API](https://steel.dev/docs/reference/api/projects) |
| `client.apiKeys` | [API keys API](https://steel.dev/docs/reference/api/api-keys) |

The SDK's own list of methods and types is [api.md](https://github.com/steel-dev/sdk/tree/main/typescript/api.md). Your editor also shows the type of each parameter and field, because the package includes TypeScript definitions.
