Profiles API

Overview

Profiles are Chrome user data directories that store:

Cookies and sessions
Browser history
Saved passwords
Extensions
Settings and preferences
Local storage

Each profile is isolated and can be used across multiple instance launches.

List Profiles

GET /profiles

curl http://localhost:9867/profiles | jq .

Query Parameters

all

boolean

default:"false"

Include temporary (auto-generated) profiles

Response

[
  {
    "id": "278be873adeb",
    "name": "Pinchtab org",
    "created": "2026-02-27T20:37:13.599Z",
    "diskUsage": 534952089,
    "source": "created",
    "running": false,
    "accountEmail": "admin@gi-ago.com",
    "accountName": "Luigi Agosti",
    "chromeProfileName": "Your Chrome",
    "hasAccount": true,
    "useWhen": "For gmail related to giago org",
    "description": ""
  }
]

Response Fields

string

required

Profile ID (hash format or name)

name

string

required

Human-readable profile name

created

string

required

ISO 8601 timestamp of profile creation

diskUsage

integer

required

Disk space used in bytes

source

string

required

Source: created (manual), imported (from Chrome), temporary (auto-generated)

running

boolean

required

true if profile is currently in use by an instance

accountEmail

string

Chrome account email if signed in

accountName

string

Chrome account name if signed in

chromeProfileName

string

Internal Chrome profile name

hasAccount

boolean

true if profile has a Chrome account signed in

useWhen

string

Description of when to use this profile (for AI agents)

description

string

Profile description

Get Profile

Retrieve details for a single profile.

GET /profiles/{id}

curl http://localhost:9867/profiles/278be873adeb | jq .

Response (200 OK)

{
  "id": "278be873adeb",
  "name": "Pinchtab org",
  "created": "2026-02-27T20:37:13.599Z",
  "diskUsage": 534952089,
  "source": "created",
  "running": false
}

Create Profile

Create a new browser profile.

POST /profiles

curl -X POST http://localhost:9867/profiles \
  -H "Content-Type: application/json" \
  -d '{"name": "my-profile"}'

Request Body

name

string

required

Profile name (must be unique)

description

string

Optional description

useWhen

string

Guidance for when to use this profile (helpful for AI agents)

Response (201 Created)

{
  "status": "created",
  "name": "my-profile"
}

Update Profile

Update profile metadata.

PATCH /profiles/{id}

curl -X PATCH http://localhost:9867/profiles/my-profile \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "useWhen": "Updated use case"
  }'

Request Body

description

string

New description

useWhen

string

New use case guidance

Response (200 OK)

{
  "status": "updated",
  "id": "my-profile",
  "name": "my-profile"
}

Delete Profile

Permanently delete a profile and all its data.

DELETE /profiles/{id}

curl -X DELETE http://localhost:9867/profiles/my-profile

Response (200 OK)

{
  "status": "deleted",
  "id": "my-profile",
  "name": "my-profile"
}

Deletion is permanent and cannot be undone. All cookies, history, and settings will be lost.

Reset Profile

Clear profile data (cookies, cache, history) without deleting the profile.

POST /profiles/{id}/reset

curl -X POST http://localhost:9867/profiles/my-profile/reset

Response (200 OK)

{
  "status": "reset",
  "id": "my-profile",
  "name": "my-profile"
}

What Gets Cleared

Sessions
Session Storage
Cache
Code Cache
GPU Cache
Service Workers
Cookies
History
Visited Links

Profile directory structure remains intact. You can re-login after reset.

Import Profile

Import an existing Chrome profile from your system.

POST /profiles/import

curl -X POST http://localhost:9867/profiles/import \
  -H "Content-Type: application/json" \
  -d '{
    "name": "imported-chrome",
    "sourcePath": "/Users/you/Library/Application Support/Google/Chrome/Default",
    "description": "Imported from my Chrome browser",
    "useWhen": "For existing Chrome accounts"
  }'

Request Body

name

string

required

Name for the imported profile

sourcePath

string

required

Path to Chrome profile directory

description

string

Optional description

useWhen

string

Optional use case guidance

Common Chrome Profile Paths

macOS:

/Users/<username>/Library/Application Support/Google/Chrome/Default
/Users/<username>/Library/Application Support/Google/Chrome/Profile 1

Linux:

~/.config/google-chrome/Default
~/.config/google-chrome/Profile 1
~/.config/chromium/Default

Windows:

C:\Users\<username>\AppData\Local\Google\Chrome\User Data\Default
C:\Users\<username>\AppData\Local\Chromium\User Data\Default

Response (201 Created)

{
  "status": "imported",
  "name": "imported-chrome"
}

Get Profile Logs

Retrieve action history for a profile.

GET /profiles/{id}/logs

curl 'http://localhost:9867/profiles/my-profile/logs?limit=50' | jq .

Query Parameters

limit

integer

default:"100"

Maximum number of log entries to return

Response

[
  {
    "timestamp": "2026-03-01T05:12:45Z",
    "action": "navigate",
    "url": "https://example.com"
  },
  {
    "timestamp": "2026-03-01T05:12:50Z",
    "action": "click",
    "selector": "e5"
  },
  {
    "timestamp": "2026-03-01T05:12:55Z",
    "action": "type",
    "text": "search query"
  }
]

Get Profile Analytics

Get usage statistics for a profile.

GET /profiles/{id}/analytics

curl http://localhost:9867/profiles/my-profile/analytics | jq .

Response

{
  "totalActions": 256,
  "averageActionDuration": 2.5,
  "topActions": {
    "navigate": 128,
    "click": 98,
    "type": 30
  },
  "lastUsed": "2026-03-01T05:12:50Z",
  "commonHosts": [
    "example.com",
    "google.com",
    "github.com"
  ],
  "last24h": {
    "actions": 50,
    "uniqueHosts": 5
  }
}

Complete Workflow Example

import requests

BASE = "http://localhost:9867"

# 1. Create profile
resp = requests.post(f"{BASE}/profiles", json={
    "name": "test-profile",
    "description": "Test profile for automation"
})
print(f"Created: {resp.json()}")

# 2. Update metadata
requests.patch(f"{BASE}/profiles/test-profile", json={
    "useWhen": "For testing automation scripts"
})

# 3. Use profile in instance
inst = requests.post(f"{BASE}/instances/start", json={
    "profileId": "test-profile",
    "mode": "headed"
}).json()

print(f"Instance: {inst['id']}")

# ... do work ...

# 4. Stop instance
requests.post(f"{BASE}/instances/{inst['id']}/stop")

# 5. View analytics
analytics = requests.get(f"{BASE}/profiles/test-profile/analytics").json()
print(f"Total actions: {analytics['totalActions']}")

# 6. Reset profile (clear cookies/history)
requests.post(f"{BASE}/profiles/test-profile/reset")

# 7. Delete when done
# requests.delete(f"{BASE}/profiles/test-profile")

Best Practices

Profile Naming

✅ Good:

work-email
github-scraper
testing-v2
production-accounts

❌ Avoid:

Generic names: test, temp, profile
Very long names (>50 chars)
Special characters requiring URL encoding

Using Descriptions and UseWhen

Include metadata for team collaboration and AI agent selection:

{
  "name": "github-automation",
  "description": "For automated GitHub operations",
  "useWhen": "When scheduled workflows need to access GitHub repos"
}

Profile Isolation

Each profile is completely isolated:

Separate cookies and sessions
Independent browser cache
Isolated browser storage
No data sharing between profiles

Use different profiles for:

Different user accounts
Different environments (dev/staging/prod)
Different projects
Security isolation

Error Handling

Profile Already Exists (400)

curl -X POST $BASE/profiles -d '{"name":"existing-profile"}'

Response:

{
  "error": "profile \"existing-profile\" already exists",
  "statusCode": 400
}

Profile Not Found (404)

curl $BASE/profiles/nonexistent

Response:

{
  "error": "profile \"nonexistent\" not found",
  "code": "ERR_PROFILE_NOT_FOUND",
  "statusCode": 404
}

Invalid Source Path (400)

curl -X POST $BASE/profiles/import \
  -d '{"name":"imp","sourcePath":"/invalid/path"}'

Response:

{
  "error": "source path invalid: stat /invalid/path: no such file or directory",
  "statusCode": 400
}

Overview

List Profiles

Query Parameters

Response

Response Fields

Get Profile

Response (200 OK)

Create Profile

Request Body

Response (201 Created)

Update Profile

Request Body

Response (200 OK)

Delete Profile

Response (200 OK)

Reset Profile

Response (200 OK)

What Gets Cleared

Import Profile

Request Body

Common Chrome Profile Paths

Response (201 Created)

Get Profile Logs

Query Parameters

Response

Get Profile Analytics

Response

Complete Workflow Example

Best Practices

Profile Naming

Using Descriptions and UseWhen

Profile Isolation

Error Handling

Profile Already Exists (400)

Profile Not Found (404)

Invalid Source Path (400)

Next Steps

Instances API

Tabs API

Documentation Index

​Overview

​List Profiles

​Query Parameters

​Response

​Response Fields

​Get Profile

​Response (200 OK)

​Create Profile

​Request Body

​Response (201 Created)

​Update Profile

​Request Body

​Response (200 OK)

​Delete Profile

​Response (200 OK)

​Reset Profile

​Response (200 OK)

​What Gets Cleared

​Import Profile

​Request Body

​Common Chrome Profile Paths

​Response (201 Created)

​Get Profile Logs

​Query Parameters

​Response

​Get Profile Analytics

​Response

​Complete Workflow Example

​Best Practices

​Profile Naming

​Using Descriptions and UseWhen

​Profile Isolation

​Error Handling

​Profile Already Exists (400)

​Profile Not Found (404)

​Invalid Source Path (400)

​Next Steps

Instances API

Tabs API

Overview

List Profiles

Query Parameters

Response

Response Fields

Get Profile

Response (200 OK)

Create Profile

Request Body

Response (201 Created)

Update Profile

Request Body

Response (200 OK)

Delete Profile

Response (200 OK)

Reset Profile

Response (200 OK)

What Gets Cleared

Import Profile

Request Body

Common Chrome Profile Paths

Response (201 Created)

Get Profile Logs

Query Parameters

Response

Get Profile Analytics

Response

Complete Workflow Example

Best Practices

Profile Naming

Using Descriptions and UseWhen

Profile Isolation

Error Handling

Profile Already Exists (400)

Profile Not Found (404)

Invalid Source Path (400)

Next Steps