Profile Management API

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.

To create, list, or delete environments, use the Environments API. The endpoints below focus on managing the browser profile data inside an environment.

Authentication

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

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

curl https://api.webrun.ai/profiles \
  -H "Authorization: Bearer wr_abc123..."

Response:

{
  "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, syncing from your local machine, 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)

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:

{
  "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

curl -X DELETE https://api.webrun.ai/profiles/683a1f2e4b0c1d2e3f4a5b6c \
  -H "Authorization: Bearer wr_abc123..."

Response:

{
  "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

curl https://api.webrun.ai/profiles/683a1f2e4b0c1d2e3f4a5b6c/download \
  -H "Authorization: Bearer wr_abc123..."

Response:

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

Use the returned URL to download the file:

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)

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

Response:

{
  "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

You can also upload profile data via the Environments API at POST /environments/<ENV_ID>/upload. Both endpoints produce the same result.

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:

{
  "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

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

Authentication

Base URL

List Profiles

Response Fields

Create Profile

Errors

Delete Profile

Errors

Download Profile Data

Errors

Upload Profile Data

Errors

Rate Limits

Common Errors

​Authentication

​Base URL

​List Profiles

​Response Fields

​Create Profile

​Errors

​Delete Profile

​Errors

​Download Profile Data

​Errors

​Upload Profile Data

​Errors

​Rate Limits

​Common Errors

Browser Profiles

Environments API

Sync Profiles

Authentication

Base URL

List Profiles

Response Fields

Create Profile

Errors

Delete Profile

Errors

Download Profile Data

Errors

Upload Profile Data

Errors

Rate Limits

Common Errors