---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/api/profiles
markdown_url: https://steel.dev/docs/reference/api/profiles.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Profiles API
description: Create, list, get and update the browser profiles that new sessions start from, with the Steel API.
summary: Create, list, get and update the browser profiles that new sessions start from, with the Steel API.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/api/sessions.md
  - https://steel.dev/docs/reference/api/quick-actions.md
  - https://steel.dev/docs/reference/api/credentials.md
  - https://steel.dev/docs/reference/api/files.md
  - https://steel.dev/docs/reference/api/extensions.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Profiles API

A profile is a saved browser state that a new session can start from. These endpoints create, list, get and update profiles. For the base URL and authentication, see [API conventions](https://steel.dev/docs/reference/api). For the error codes, see [Errors](https://steel.dev/docs/reference/errors).

The first example is a complete program. The later examples use its `client`, and the ID of a profile in `PROFILE_ID` (cURL), `profileId` (TypeScript), `profile_id` (Python and Rust) or `profileID` (Go).

## Endpoints

### List profiles

```http
GET /v1/profiles
```

Lists the profiles of a project, the most recently updated first.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `projectId` | query | string (uuid) | no | | The project whose profiles to list. Required with an organization key. |

| Field | Type | Description |
| - | - | - |
| `profiles` | object\[] | The profiles. Each one is a profile object, as in [Create a profile](https://steel.dev/docs/reference/api/profiles#create-a-profile). |
| `count` | number | The total number of profiles. |

**cURL**

```sh
curl https://api.steel.dev/v1/profiles \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

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

const client = new Steel();
const result = await client.profiles.list();

for (const profile of result.profiles) {
  console.log(profile.id, profile.status);
}
```

**Python**

```python file=list-profiles.py
from steel import Steel

client = Steel()
result = client.profiles.list()

for profile in result.profiles:
    print(profile.id, profile.status)
```

**Go**

```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()
	result, err := client.Profiles.List(ctx, steel.ProfileListParams{})
	if err != nil {
		return err
	}

	for _, profile := range result.Profiles {
		fmt.Println(profile.ID, profile.Status)
	}
	return nil
}
```

**Rust**

```rust file=src/main.rs
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = steel_rs::Client::new();
    let result = client
        .profiles()
        .list(steel_rs::ProfileListParams::default())
        .await?;

    for profile in result.profiles {
        println!("{} {:?}", profile.id, profile.status);
    }
    Ok(())
}
```

See [Profiles](https://steel.dev/docs/logins/profiles).

### Create a profile

```http
POST /v1/profiles
```

Creates a profile from a ZIP archive of a browser user data directory. The request is `multipart/form-data`.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `userDataDir` | body | file | yes | | The user data directory, as a ZIP archive. |
| `userAgent` | body | string | no | | The user agent that sessions from the profile use. |
| `dimensions` | body | object | no | | The window `width` and `height` that sessions from the profile use, as JSON. |
| `proxyUrl` | body | string (uri) | no | | Ignored. Steel does not save `proxyUrl` in a profile, so pass it when you create each session. |
| `useProxy` | body | string | no | | The Steel proxy settings for sessions from the profile, as JSON. For a dedicated IP, send `{"type":"fixed","id":"fixed:ID"}`. |
| `projectId` | body | string (uuid) | no | | The project to create the profile in. Required with an organization key. |

The response is `201` with the profile object:

| Field | Type | Description |
| - | - | - |
| `id` | string (uuid) | The ID of the profile. |
| `status` | string | `UPLOADING`, `READY` or `FAILED`. |
| `projectId` | string (uuid) or null | The project of the profile. |
| `sourceSessionId` | string (uuid) or null | The last session that saved the profile, or the session that is creating it. A session that only loads the profile does not change this field. `null` for a profile created from a ZIP archive, until a session saves it. |
| `userAgent` | string or null | The user agent that sessions from the profile use. |
| `dimensions` | object or null | The window `width` and `height` that sessions from the profile use. |
| `fingerprint` | object or null | The browser fingerprint that the profile keeps. |
| `extensionIds` | string\[] or null | The IDs of the extensions that the profile keeps. |
| `credentialsConfig` | object or null | The `credentials` settings that the profile keeps. |
| `useProxyConfig` | object or null | The proxy settings that the profile keeps. |
| `createdAt` | string (date-time) | When the profile was created. |
| `updatedAt` | string (date-time) | When the profile last changed. |

**cURL**

```sh
curl -X POST https://api.steel.dev/v1/profiles \
  -H "steel-api-key: $STEEL_API_KEY" \
  -F "userDataDir=@profile.zip" \
  -F 'dimensions={"width":1280,"height":800}'
```

**TypeScript**

```ts
import { createReadStream } from "node:fs";

const profile = await client.profiles.create({
  userDataDir: createReadStream("profile.zip"),
  dimensions: { width: 1280, height: 800 },
});
console.log(profile.id, profile.status);
```

**Python**

```python
from pathlib import Path

profile = client.profiles.create(
    user_data_dir=Path("profile.zip"),
    dimensions={"width": 1280, "height": 800},
)
print(profile.id, profile.status)
```

**Go**

```go
import (
	"io"
	"os"
)

userDataDir, err := os.Open("profile.zip")
if err != nil {
	return err
}
defer userDataDir.Close()
profile, err := client.Profiles.New(ctx, steel.ProfileNewParams{
	UserDataDir: steel.F[io.Reader](userDataDir),
	Dimensions: steel.F(steel.ProfileNewParamsDimensions{
		Width:  steel.F(1280.0),
		Height: steel.F(800.0),
	}),
})
if err != nil {
	return err
}
fmt.Println(profile.ID, profile.Status)
```

**Rust**

```rust
let profile = client
    .profiles()
    .create(steel_rs::ProfileCreateParams {
        dimensions: Some(steel_rs::ProfileCreateParamsDimensions {
            width: 1280.0,
            height: 800.0,
        }),
        ..steel_rs::ProfileCreateParams::new(steel_rs::Upload::open("profile.zip").await?)
    })
    .await?;
println!("{} {:?}", profile.id, profile.status);
```

To create a profile from a session instead of an archive, create the session with `persistProfile`. See [Profiles](https://steel.dev/docs/logins/profiles).

### Get a profile

```http
GET /v1/profiles/{id}
```

Returns one profile.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the profile. |
| `projectId` | query | string (uuid) | no | | The profile's project. Required with an organization key. |

The response is the profile object, with the fields in [Create a profile](https://steel.dev/docs/reference/api/profiles#create-a-profile).

**cURL**

```sh
curl https://api.steel.dev/v1/profiles/$PROFILE_ID \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
const profile = await client.profiles.get(profileId);
console.log(profile.status);
```

**Python**

```python
profile = client.profiles.get(profile_id)
print(profile.status)
```

**Go**

```go
profile, err := client.Profiles.Get(ctx, profileID, steel.ProfileGetParams{})
if err != nil {
	return err
}
fmt.Println(profile.Status)
```

**Rust**

```rust
let profile = client
    .profiles()
    .get(&profile_id, steel_rs::ProfileGetParams::default())
    .await?;
println!("{:?}", profile.status);
```

See [Profiles](https://steel.dev/docs/logins/profiles).

### Update a profile

```http
PATCH /v1/profiles/{id}
```

Replaces a profile's user data directory, and changes its settings. The request is `multipart/form-data`.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `id` | path | string (uuid) | yes | | The ID of the profile. |
| `projectId` | query | string (uuid) | no | | The profile's project. Required with an organization key, in the query or in the body. |
| `userDataDir` | body | file | yes | | The new user data directory, as a ZIP archive. |
| `userAgent` | body | string | no | | The user agent that sessions from the profile use. |
| `dimensions` | body | object | no | | The window `width` and `height` that sessions from the profile use, as JSON. |
| `proxyUrl` | body | string (uri) | no | | Ignored. Steel does not save `proxyUrl` in a profile, so pass it when you create each session. |
| `useProxy` | body | string | no | | The Steel proxy settings for sessions from the profile, as JSON. For a dedicated IP, send `{"type":"fixed","id":"fixed:ID"}`. |
| `projectId` | body | string (uuid) | no | | The profile's project, as in the query. |

The response is the profile object, with the fields in [Create a profile](https://steel.dev/docs/reference/api/profiles#create-a-profile).

**cURL**

```sh
curl -X PATCH https://api.steel.dev/v1/profiles/$PROFILE_ID \
  -H "steel-api-key: $STEEL_API_KEY" \
  -F "userDataDir=@profile.zip"
```

**TypeScript**

```ts
import { createReadStream } from "node:fs";

const profile = await client.profiles.update(profileId, {
  userDataDir: createReadStream("profile.zip"),
});
console.log(profile.updatedAt);
```

**Python**

```python
from pathlib import Path

profile = client.profiles.update(profile_id, user_data_dir=Path("profile.zip"))
print(profile.updated_at)
```

**Go**

```go
import (
	"io"
	"os"
)

userDataDir, err := os.Open("profile.zip")
if err != nil {
	return err
}
defer userDataDir.Close()
profile, err := client.Profiles.Update(ctx, profileID, steel.ProfileUpdateParams{
	UserDataDir: steel.F[io.Reader](userDataDir),
})
if err != nil {
	return err
}
fmt.Println(profile.UpdatedAt)
```

**Rust**

```rust
let profile = client
    .profiles()
    .update(
        &profile_id,
        steel_rs::ProfileUpdateParams::new(steel_rs::Upload::open("profile.zip").await?),
    )
    .await?;
println!("{}", profile.updated_at);
```

See [Profiles](https://steel.dev/docs/logins/profiles).
