Skip to main content
Manage browser profiles programmatically. Profiles store persistent Chrome browser data — cookies, local storage, extensions — that you can reuse across sessions.

​
Authentication

All profile endpoints require an API key with task:create permission. 
Authorization: Bearer <api_key>

​
Base URL

https://connect.webrun.ai/profiles

​
List Profiles

Returns all profiles for the authenticated user, sorted by newest first. 
GET /profiles
Example: 
curl https://connect.webrun.ai/profiles \
  -H "Authorization: Bearer enig_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

FieldTypeDescription
_idstringUnique profile identifier
userIdstringOwner’s user ID
namestringProfile name
descriptionstringProfile description
blobSizenumberSize of profile data in bytes
blobUploadedAtstringISO 8601 timestamp of last upload
lastUsedAtstringISO 8601 timestamp of last session usage
usageCountnumberNumber of times used in sessions
statusstringProfile status: empty, uploading, or ready
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp

​
Create Profile

Creates a new empty profile. You can populate it by uploading data or by running a session with the profile attached. 
POST /profiles
Content-Type: application/json

​
Request Body

FieldTypeRequiredDescription
namestringYesProfile name (max 100 characters)
descriptionstringNoProfile description (max 500 characters)
Example: 
curl -X POST https://connect.webrun.ai/profiles \
  -H "Authorization: Bearer enig_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

StatusMessageCause
400Profile name is requiredMissing or empty name field
400Maximum of 20 profiles allowedUser already has 20 profiles

​
Delete Profile

Permanently deletes a profile and its stored browser data. 
DELETE /profiles/:id

​
Parameters

ParameterLocationDescription
idURL pathThe profile ID
Example: 
curl -X DELETE https://connect.webrun.ai/profiles/683a1f2e4b0c1d2e3f4a5b6c \
  -H "Authorization: Bearer enig_abc123..."
Response: 
{
  "success": true,
  "message": "Profile deleted"
}

​
Errors

StatusMessageCause
404Profile not foundInvalid ID or profile belongs to another user

​
Download Profile Data

Returns a temporary signed URL to download the profile’s browser data as a .tar.gz archive. The URL expires after 1 hour. 
GET /profiles/:id/download

​
Parameters

ParameterLocationDescription
idURL pathThe profile ID
Example: 
curl https://connect.webrun.ai/profiles/683a1f2e4b0c1d2e3f4a5b6c/download \
  -H "Authorization: Bearer enig_abc123..."
Response: 
{
  "success": true,
  "downloadUrl": "https://storage.example.com/profiles/683a1f2e4b0c1d2e3f4a5b6c.tar.gz?token=eyJhbGciOi..."
}
Use the downloadUrl to download the file directly: 
curl -o profile-backup.tar.gz "<downloadUrl>"

​
Errors

StatusMessageCause
400Profile has no data to downloadProfile status is not ready or has no uploaded data
404Profile not foundInvalid ID or profile belongs to another user

​
Upload Profile Data

Uploads browser profile data as a .tar.gz archive. Replaces any existing data on the profile. 
POST /profiles/:id/upload
Content-Type: multipart/form-data

​
Parameters

ParameterLocationDescription
idURL pathThe profile ID
fileForm fieldThe .tar.gz file (max 500 MB)
Example: 
curl -X POST https://connect.webrun.ai/profiles/683a1f2e4b0c1d2e3f4a5b6c/upload \
  -H "Authorization: Bearer enig_abc123..." \
  -F "[email protected]"
Response: 
{
  "success": true,
  "message": "Profile uploaded successfully",
  "profile": {
    "_id": "683a1f2e4b0c1d2e3f4a5b6c",
    "name": "My Profile",
    "status": "ready",
    "blobSize": 4521984,
    "blobUploadedAt": "2026-02-09T12:30:00.000Z"
  }
}
Accepted file types: .tar.gz, .tgz

​
Errors

StatusMessageCause
400No file providedMissing file field in form data
400Only .tar.gz files are allowedFile is not a valid tar.gz archive
404Profile not foundInvalid ID or profile belongs to another user

​
Profile Status Values

StatusDescription
emptyCreated but has no browser data
uploadingData upload in progress
readyHas browser data and can be used in sessions

​
Rate Limits

Profile endpoints share the server’s global rate limit of 100 requests per 15 minutes per IP.

​
Common Error Responses

All error responses follow this format: 
{
  "success": false,
  "message": "Description of the error"
}
StatusMessageCause
401API key requiredMissing Authorization header
401Invalid or revoked API keyAPI key is incorrect or has been revoked
403Account is deactivatedUser account is disabled
403API key missing required permission: task:createAPI key lacks the task:create permission
500Authentication errorServer-side authentication failure