---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/sdks/go
markdown_url: https://steel.dev/docs/reference/sdks/go.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Go SDK
description: Install the Steel Go SDK, configure the client, and handle errors, retries, and pagination.
summary: Install the Steel Go SDK, configure the client, and handle errors, retries, and pagination.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/sdks/typescript.md
  - https://steel.dev/docs/reference/sdks/python.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
---

# Go SDK

The Steel SDK for Go is the module `github.com/steel-dev/sdk/go`, 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](https://steel.dev/docs/reference/api) shows the call for each endpoint.

## Install

Each Go program in these docs is the `main.go` of a module. Create the module, then add the SDK:

```sh
go mod init example
go get github.com/steel-dev/sdk/go
```

The SDK needs Go 1.22 or later. Import it as `steel`:

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

## Create a client

`steel.NewClient()` reads your API key from the `STEEL_API_KEY` environment variable. To change the key or another setting, pass options from the `option` package.

```go
import (
	"os"

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

client := steel.NewClient(
	option.WithSteelAPIKey(os.Getenv("STEEL_API_KEY")),
)
```

| Option | Default | Meaning |
| - | - | - |
| `option.WithSteelAPIKey` | `STEEL_API_KEY` | The API key. |
| `option.WithBaseURL` | `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). |
| `option.WithMaxRetries` | `2` | How many times the SDK retries a request that failed. |
| `option.WithRequestTimeout` | none | How long each attempt of a request can take. |
| `option.WithHeader` | none | A header to send with the request. |
| `option.WithHTTPClient` | an `http.Client` that waits at most 10 minutes for response headers | The HTTP client that sends the requests. |
| `option.WithMiddleware` | none | A function that runs around each request, for example to log it. |

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

You can pass the same options to a single method call. An option on a call overrides the option on the client.

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

```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()
	session, err := client.Sessions.New(ctx, steel.SessionNewParams{})
	if err != nil {
		return err
	}
	defer func() {
		if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
			log.Print(err)
		}
	}()

	fmt.Println(session.ID)
	return nil
}
```

Run the program:

```sh
go run .
```

The program prints the session's ID.

```text nocopy
ee60f12b-35e5-49f1-9eb4-6a86766a190a
```

To drive the session's browser, connect a CDP (Chrome DevTools Protocol) client to `session.WebsocketURL`. The URL holds a token for the session, so the client needs no API key.

Wrap each request field in `steel.F`. The wrapper marks the field as set, so the SDK can tell a set field from a zero value. The SDK does not send a field without the wrapper. Use `steel.Null[T]()` to send `null`.

```go
params := steel.SessionListParams{
	Status: steel.F(steel.SessionListParamsStatusLive),
}
```

[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

A response with the `x-should-retry` header overrides this rule.

A request has no time limit by default. Set one for the whole call, retries included, with the context. Set one for each attempt with `option.WithRequestTimeout`.

```go
import (
	"time"

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

ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()

session, err := client.Sessions.New(
	ctx,
	steel.SessionNewParams{},
	option.WithRequestTimeout(20*time.Second),
	option.WithMaxRetries(5),
)
```

## Handle errors

Every method returns an `error` as its last value. When the API returns a status outside 2xx, the error is a `*steel.Error`. It holds `StatusCode`, the `*http.Request`, the `*http.Response` and the response's JSON body. Use `errors.As` to read it:

```go
import "errors"

_, err := client.Sessions.New(ctx, steel.SessionNewParams{})
if err != nil {
	var apierr *steel.Error
	if errors.As(err, &apierr) {
		fmt.Println(apierr.StatusCode)
		fmt.Println(string(apierr.DumpResponse(true)))
	}
	return err
}
```

For other failures, the method returns the underlying error. When the network fails, for example, you get a `*url.Error`.

[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. `ListAutoPaging` reads every item and fetches the next page when it needs it:

```go
iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
	Status: steel.F(steel.SessionListParamsStatusLive),
})
for iter.Next() {
	session := iter.Current()
	fmt.Println(session.ID, "started at", session.CreatedAt)
}
if err := iter.Err(); err != nil {
	return err
}
```

To read one page at a time, call `List`, then `GetNextPage()` on each page:

```go
page, err := client.Sessions.List(ctx, steel.SessionListParams{})
for page != nil {
	for _, session := range page.Sessions {
		fmt.Println(session.ID)
	}
	page, err = page.GetNextPage()
}
if err != nil {
	return err
}
```

## Methods

The Go SDK has the methods of the other SDKs, with Go names. Groups of methods are fields of the client, such as `client.Sessions` and `client.Profiles`. `create` is `New` and `retrieve` is `Get`, so `sessions.create` is `client.Sessions.New`. Each method takes a `context.Context`, then the path parameters, then a params struct.

The [API reference](https://steel.dev/docs/reference/api) documents each endpoint and its parameters. The SDK's own list of methods is [api.md](https://github.com/steel-dev/sdk/tree/main/go/api.md), and the types are on [pkg.go.dev](https://pkg.go.dev/github.com/steel-dev/sdk/go).
