Skip to main content
BBU Profiles are in beta and are opt-in. If beta access is not enabled, profile management endpoints return 404 NOT_FOUND. Run requests with profile_id return 400, and use_profile alone has no effect. Request access at agent.tinyfish.ai/beta.
Use the BBU Profiles API to create persistent browser state, set it up once, and reuse it in future Agent API runs. The happy path is simple: create a profile, save a logged-in setup session, then pass use_profile: true when you run automation.

BBU Profiles overview

Learn when to use saved browser state

Request beta access

Enable BBU Profiles for your account

​
Quick path

1

Create a profile

Create a named BBU Profile and optionally make it your default.
2

Save a logged-in setup session

Start a setup browser, sign in, then save the session back to the profile.
3

Run with saved state

Pass use_profile: true, or pass both use_profile: true and profile_id for a specific profile.

​
Create a profile

curl -X POST https://agent.tinyfish.ai/v1/profiles \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salesforce Production",
    "set_as_default": true,
    "proxy_country_code": "US"
  }'

{
  "id": "prof_abc123def4567890",
  "name": "Salesforce Production",
  "proxy_country_code": "US",
  "fingerprint_seed": "12345678",
  "created_at": "2026-06-04T18:00:00.000Z"
}
Create fieldTypeNotes
namestringRequired. 1–100 characters.
set_as_defaultbooleanOptional. Makes this the default profile for use_profile: true.
proxy_country_codestring | nullOptional. Supported country code, or null for no profile proxy.

​
Set up a profile

Start a setup browser: 
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/setup-session \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/login",
    "timeout_seconds": 900
  }'

{
  "session_id": "sess_123",
  "cdp_url": "wss://...",
  "base_url": "https://...",
  "timeout_seconds": 900,
  "expires_at": "2026-06-04T18:15:00.000Z"
}
Connect to cdp_url with Playwright, Puppeteer, Selenium, or another CDP client. Sign in, then save the session: 
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/save \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sess_123" }'

{
  "domains_updated": ["example.com"],
  "domains_failed": [],
  "cookie_count": 12,
  "pages_captured": 1,
  "target_reads_skipped": 0,
  "domains_skipped": {
    "cookies_skipped": [],
    "local_storage_skipped": [],
    "session_storage_skipped": [],
    "blob_too_large": []
  }
}

​
Run with a BBU Profile

Use your default BBU Profile: 
curl -X POST https://agent.tinyfish.ai/v1/automation/run \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "goal": "Summarize the account health dashboard",
    "use_profile": true
  }'
Use a specific BBU Profile: 
curl -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "goal": "Download the latest invoice",
    "use_profile": true,
    "profile_id": "prof_abc123def4567890"
  }'
FieldTypeRequiredNotes
use_profilebooleanNoUse saved browser state. Without profile_id, TinyFish uses your default BBU Profile.
profile_idstringNoBeta. Selects a specific profile. Requires use_profile: true.
If use_profile: true is set and no default profile exists, the run returns 400. Create a profile and set it as default first.

​
Pair with Vault

For authenticated workflows, pair BBU Profiles with Vault so stale sessions can be repaired: 
{
  "url": "https://app.example.com/dashboard",
  "goal": "Check the dashboard and summarize anything urgent",
  "use_profile": true,
  "use_vault": true
}
The BBU Profile starts the run with saved logged-in state. If the session expires and a matching Vault credential is available, TinyFish can use the credential to sign in again and repair the saved state for future runs.

​
List profiles

curl https://agent.tinyfish.ai/v1/profiles \
  -H "X-API-Key: $TINYFISH_API_KEY"

​
Inspect and update

# Inspect saved domains
curl https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890 \
  -H "X-API-Key: $TINYFISH_API_KEY"

# Rename, make default, or update proxy location
curl -X PATCH https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890 \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Salesforce", "set_as_default": true, "proxy_country_code": "US" }'

# Delete one stored domain
curl -X DELETE https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/domains/example.com \
  -H "X-API-Key: $TINYFISH_API_KEY"

# Delete the profile
curl -X DELETE https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890 \
  -H "X-API-Key: $TINYFISH_API_KEY"

​
Upload cookies manually

Use manual upload when you already have exported browser state and do not need to open a setup browser. 
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/upload \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cookies": [
      { "name": "session", "value": "...", "domain": "example.com" }
    ]
  }'
Manual upload supports cookies plus local and session storage.
LimitValue
Upload payload5 MB
Cookies per upload3,000
Domains per profile100

​
Common errors

StatusMeaningFix
400Invalid body, missing default profile, or profile_id without use_profile: trueFix the request or create a default profile
401Missing or invalid API keySet X-API-Key
404BBU Profiles beta not enabled or profile/domain not foundRequest beta access or check the ID
409Setup/save/delete cleanup needs a retry, or the setup browser is no longer runningRetry the operation or start a new setup session

​
Profile endpoints

All requests require X-API-Key.
EndpointMethodPurpose
/v1/profilesGETList profiles
/v1/profilesPOSTCreate a profile
/v1/profiles/{profileId}GETGet profile details and saved domains
/v1/profiles/{profileId}PATCHRename a profile, set default, or update proxy location
/v1/profiles/{profileId}DELETEDelete a profile
/v1/profiles/{profileId}/setup-sessionPOSTStart an interactive setup browser
/v1/profiles/{profileId}/savePOSTSave a setup browser session
/v1/profiles/{profileId}/uploadPOSTUpload cookies and storage manually
/v1/profiles/{profileId}/domains/{domain}DELETEDelete stored state for one domain

​
Next steps

BBU Profiles overview

Learn when to use saved browser state

Vault Credentials

Add stale-session repair