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. For the error codes, see 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
GET/v1/profiles
Lists the profiles of a project, the most recently updated first.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) · query | No | The project whose profiles to list. Required with an organization key. |
Response
| Field | Type | Description |
|---|---|---|
profiles | object[] | The profiles. Each one is a profile object, as in Create a profile. |
count | number | The total number of profiles. |
See Profiles.
curl https://api.steel.dev/v1/profiles \
-H "steel-api-key: $STEEL_API_KEY"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);
}from steel import Steel
client = Steel()
result = client.profiles.list()
for profile in result.profiles:
print(profile.id, profile.status)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
}#[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(())
}Create a profile
POST/v1/profiles
Creates a profile from a ZIP archive of a browser user data directory. The request is multipart/form-data.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
userDataDir | file · body | Yes | The user data directory, as a ZIP archive. |
userAgent | string · body | No | The user agent that sessions from the profile use. |
dimensions | object · body | No | The window width and height that sessions from the profile use, as JSON. |
proxyUrl | string (uri) · body | No | Ignored. Steel does not save proxyUrl in a profile, so pass it when you create each session. |
useProxy | string · body | No | The Steel proxy settings for sessions from the profile, as JSON. For a dedicated IP, send {"type":"fixed","id":"fixed:ID"}. |
projectId | string (uuid) · body | No | The project to create the profile in. Required with an organization key. |
The response is 201 with the profile object:
Response
| 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. |
To create a profile from a session instead of an archive, create the session with persistProfile. See Profiles.
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}'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);from pathlib import Path
profile = client.profiles.create(
user_data_dir=Path("profile.zip"),
dimensions={"width": 1280, "height": 800},
)
print(profile.id, profile.status)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)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);Get a profile
GET/v1/profiles/{id}
Returns one profile.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the profile. |
projectId | string (uuid) · query | No | The profile's project. Required with an organization key. |
The response is the profile object, with the fields in Create a profile.
See Profiles.
curl https://api.steel.dev/v1/profiles/$PROFILE_ID \
-H "steel-api-key: $STEEL_API_KEY"const profile = await client.profiles.get(profileId);
console.log(profile.status);profile = client.profiles.get(profile_id)
print(profile.status)profile, err := client.Profiles.Get(ctx, profileID, steel.ProfileGetParams{})
if err != nil {
return err
}
fmt.Println(profile.Status)let profile = client
.profiles()
.get(&profile_id, steel_rs::ProfileGetParams::default())
.await?;
println!("{:?}", profile.status);Update a profile
PATCH/v1/profiles/{id}
Replaces a profile's user data directory, and changes its settings. The request is multipart/form-data.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) · path | Yes | The ID of the profile. |
projectId | string (uuid) · query | No | The profile's project. Required with an organization key, in the query or in the body. |
userDataDir | file · body | Yes | The new user data directory, as a ZIP archive. |
userAgent | string · body | No | The user agent that sessions from the profile use. |
dimensions | object · body | No | The window width and height that sessions from the profile use, as JSON. |
proxyUrl | string (uri) · body | No | Ignored. Steel does not save proxyUrl in a profile, so pass it when you create each session. |
useProxy | string · body | No | The Steel proxy settings for sessions from the profile, as JSON. For a dedicated IP, send {"type":"fixed","id":"fixed:ID"}. |
projectId | string (uuid) · body | No | The profile's project, as in the query. |
The response is the profile object, with the fields in Create a profile.
See Profiles.
curl -X PATCH https://api.steel.dev/v1/profiles/$PROFILE_ID \
-H "steel-api-key: $STEEL_API_KEY" \
-F "userDataDir=@profile.zip"import { createReadStream } from "node:fs";
const profile = await client.profiles.update(profileId, {
userDataDir: createReadStream("profile.zip"),
});
console.log(profile.updatedAt);from pathlib import Path
profile = client.profiles.update(profile_id, user_data_dir=Path("profile.zip"))
print(profile.updated_at)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)let profile = client
.profiles()
.update(
&profile_id,
steel_rs::ProfileUpdateParams::new(steel_rs::Upload::open("profile.zip").await?),
)
.await?;
println!("{}", profile.updated_at);