> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webrun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Profile Management API

> Upload, download, and manage browser profile data stored in environments

These endpoints operate on browser profile data stored within environments. They use the `/profiles` path and provide operations like **downloading** profile archives that complement the [Environments API](/environments/environments-api).

<Tip>
  To create, list, or delete environments, use the [Environments API](/environments/environments-api). The endpoints below focus on managing the browser profile data inside an environment.
</Tip>

## Authentication

All endpoints require an API key with `task:create` permission:

```bash theme={null}
Authorization: Bearer <api_key>
```

## Base URL

```
https://api.webrun.ai
```

***

## List Profiles

Returns all environments with their profile metadata, sorted by newest first. This is equivalent to listing environments but includes additional profile-specific fields like `blobSize`, `lastUsedAt`, and `usageCount`.

```
GET /profiles
```

```bash theme={null}
curl https://api.webrun.ai/profiles \
  -H "Authorization: Bearer wr_abc123..."
```

**Response:**

```json theme={null}
{
  "success": true,
  "profiles": [
    {
      "_id": "683a1f2e4b0c1d2e3f4a5b6c",
      "userId": "67f1a2b3c4d5e6f7a8b9c0d1",
      "name": "My Shopping Profile",
      "description": "Amazon and eBay sessions",
      "blobSize": 4521984,
      "blobUploadedAt": "2026-02-08T14:30:00.000Z",
      "lastUsedAt": "2026-02-09T10:15:00.000Z",
      "usageCount": 12,
      "status": "ready",
      "createdAt": "2026-02-01T09:00:00.000Z",
      "updatedAt": "2026-02-09T10:15:00.000Z"
    }
  ]
}
```

### Response Fields

| Field            | Type   | Description                                         |
| ---------------- | ------ | --------------------------------------------------- |
| `_id`            | string | Environment identifier (same as the environment ID) |
| `name`           | string | Environment name                                    |
| `description`    | string | Environment description                             |
| `blobSize`       | number | Size of profile data in bytes                       |
| `blobUploadedAt` | string | ISO 8601 timestamp of last profile upload           |
| `lastUsedAt`     | string | ISO 8601 timestamp of last session usage            |
| `usageCount`     | number | Number of times used in sessions                    |
| `status`         | string | `empty`, `uploading`, or `ready`                    |
| `createdAt`      | string | ISO 8601 creation timestamp                         |
| `updatedAt`      | string | ISO 8601 last update timestamp                      |

***

## Create Profile

Creates a new environment with an empty browser profile. You can populate it by [uploading data](#upload-profile-data), [syncing from your local machine](/environments/sync-profiles), or by running a session with the environment attached.

```
POST /profiles
Content-Type: application/json
```

| Field         | Type   | Required | Description                           |
| ------------- | ------ | -------- | ------------------------------------- |
| `name`        | string | Yes      | Environment name (max 100 characters) |
| `description` | string | No       | Description (max 500 characters)      |

```bash theme={null}
curl -X POST https://api.webrun.ai/profiles \
  -H "Authorization: Bearer wr_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Profile", "description": "For social media automation"}'
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Profile created",
  "profile": {
    "_id": "683a1f2e4b0c1d2e3f4a5b6c",
    "userId": "67f1a2b3c4d5e6f7a8b9c0d1",
    "name": "My Profile",
    "description": "For social media automation",
    "blobSize": 0,
    "status": "empty",
    "usageCount": 0,
    "createdAt": "2026-02-09T12:00:00.000Z",
    "updatedAt": "2026-02-09T12:00:00.000Z"
  }
}
```

### Errors

| Status | Message                        | Cause                            |
| ------ | ------------------------------ | -------------------------------- |
| 400    | Profile name is required       | Missing or empty `name` field    |
| 400    | Maximum of 20 profiles allowed | User already has 20 environments |

***

## Delete Profile

Permanently deletes an environment and all its stored data (profile and files).

```
DELETE /profiles/:id
```

| Parameter | Location | Description        |
| --------- | -------- | ------------------ |
| `id`      | URL path | The environment ID |

```bash theme={null}
curl -X DELETE https://api.webrun.ai/profiles/683a1f2e4b0c1d2e3f4a5b6c \
  -H "Authorization: Bearer wr_abc123..."
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Profile deleted"
}
```

### Errors

| Status | Message           | Cause                                             |
| ------ | ----------------- | ------------------------------------------------- |
| 404    | Profile not found | Invalid ID or environment belongs to another user |

***

## Download Profile Data

Returns a temporary signed URL to download the browser profile as a `.tar.gz` archive. The URL expires after **1 hour**.

```
GET /profiles/:id/download
```

| Parameter | Location | Description        |
| --------- | -------- | ------------------ |
| `id`      | URL path | The environment ID |

```bash theme={null}
curl https://api.webrun.ai/profiles/683a1f2e4b0c1d2e3f4a5b6c/download \
  -H "Authorization: Bearer wr_abc123..."
```

**Response:**

```json theme={null}
{
  "success": true,
  "downloadUrl": "https://storage.example.com/profiles/683a1f2e4b0c1d2e3f4a5b6c.tar.gz?token=eyJhbGciOi..."
}
```

Use the returned URL to download the file:

```bash theme={null}
curl -o profile-backup.tar.gz "<downloadUrl>"
```

### Errors

| Status | Message                         | Cause                                                 |
| ------ | ------------------------------- | ----------------------------------------------------- |
| 400    | Profile has no data to download | Profile status is not `ready` or has no uploaded data |
| 404    | Profile not found               | Invalid ID or environment belongs to another user     |

***

## Upload Profile Data

Uploads browser profile data as a `.tar.gz` archive to an environment. Replaces any existing profile data and sets the status to `ready`.

```
POST /profiles/:id/upload
Content-Type: multipart/form-data
```

| Parameter | Location   | Description                 |
| --------- | ---------- | --------------------------- |
| `id`      | URL path   | The environment ID          |
| `file`    | Form field | `.tar.gz` file (max 500 MB) |

```bash theme={null}
curl -X POST https://api.webrun.ai/profiles/683a1f2e4b0c1d2e3f4a5b6c/upload \
  -H "Authorization: Bearer wr_abc123..." \
  -F "file=@my-profile.tar.gz"
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Profile uploaded successfully",
  "profile": {
    "_id": "683a1f2e4b0c1d2e3f4a5b6c",
    "name": "My Profile",
    "status": "ready",
    "blobSize": 4521984,
    "blobUploadedAt": "2026-02-09T12:30:00.000Z"
  }
}
```

### Errors

| Status | Message                        | Cause                                             |
| ------ | ------------------------------ | ------------------------------------------------- |
| 400    | No file provided               | Missing `file` field in form data                 |
| 400    | Only .tar.gz files are allowed | File is not a valid `.tar.gz` archive             |
| 404    | Profile not found              | Invalid ID or environment belongs to another user |

<Tip>
  You can also upload profile data via the [Environments API](/environments/environments-api#upload-browser-profile-data) at `POST /environments/<ENV_ID>/upload`. Both endpoints produce the same result.
</Tip>

***

## Rate Limits

Profile endpoints share the global rate limit of **100 requests per 15 minutes per IP**.

***

## Common Errors

All error responses follow this format:

```json theme={null}
{
  "success": false,
  "message": "Description of the error"
}
```

| Status | Message                                          | Cause                                      |
| ------ | ------------------------------------------------ | ------------------------------------------ |
| 401    | API key required                                 | Missing `Authorization` header             |
| 401    | Invalid or revoked API key                       | API key is incorrect or has been revoked   |
| 403    | Account is deactivated                           | User account is disabled                   |
| 403    | API key missing required permission: task:create | API key lacks the `task:create` permission |
| 500    | Authentication error                             | Server-side authentication failure         |

***

<Accordion title="Related">
  <CardGroup cols={2}>
    <Card title="Browser Profiles" icon="user-gear" href="/environments/profiles">
      How browser profiles work within environments
    </Card>

    <Card title="Environments API" icon="code" href="/environments/environments-api">
      Create, list, and delete environments; manage files
    </Card>

    <Card title="Sync Profiles" icon="arrows-rotate" href="/environments/sync-profiles">
      Upload your local Chrome profile with one command
    </Card>
  </CardGroup>
</Accordion>