Browser Context Profiles

Stop logging in from scratch on every run. Browser Context Profiles let TinyFish save browser state — cookies, local storage, and session storage — and reuse it later. Recurring automations can start where a real returning user would: already signed in, with the right workspace, preferences, and site context loaded.

Browser Context Profiles are not Browser Profiles. Browser Profiles choose the runtime mode with browser_profile: "lite" | "stealth". Browser Context Profiles save session state across runs.

Use the API

Create and run with Browser Context Profiles programmatically

Vault Credentials

Add stale-session repair

The flow

1. Set up once

Open a setup browser, sign in, and save the session.

2. Run many times

Reuse saved state so recurring runs start authenticated.

3. Repair when stale

Add Vault so TinyFish can log back in if the session expires.

Set up a Browser Context Profile

Dashboard
API

Go to Browser Context Profiles in the TinyFish dashboard.
Click Create Profile.
Name the profile.
Optional: mark it as the default profile.
Optional: choose a proxy location for the profile.
Click Create and set up.
Sign in to the target site in the setup browser.
Save the setup session.

Use one Browser Context Profile per account or environment, such as Salesforce Production and Salesforce Sandbox.

Create the profile, start a setup session, sign in through the setup browser, then save it.

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
  }'

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" }'

After signing in, save the setup browser state:

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" }'

Browser Context Profiles API

Full setup, upload, update, and cleanup reference

Use a Browser Context Profile

Playground
API: default profile
API: specific profile

Open the Playground.
Click the profile icon in the toolbar.
Turn on Use Browser Context Profile.
Choose a profile, or use your default profile.
Run the automation.

If no profile exists, click Go to Browser Context Profiles to create one first.

Use your default Browser Context Profile with use_profile: true:

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": "Open the dashboard and summarize the latest alerts",
    "use_profile": true
  }'

Target a specific Browser Context Profile by ID:

curl -X POST https://agent.tinyfish.ai/v1/automation/run-async \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "goal": "Export the weekly usage report",
    "use_profile": true,
    "profile_id": "prof_abc123def4567890"
  }'

Manage Browser Context Profiles

On the Browser Context Profiles page, you can:

Rename Browser Context Profiles
Set a default Browser Context Profile
Copy a profile ID
View saved domains
Set or clear a profile proxy location
Upload cookies manually
Delete individual domains
Delete Browser Context Profiles

You cannot delete your only active profile. Create another profile first.

Browser Context Profiles + Vault

The best authenticated setup is Browser Context Profiles plus Vault Credentials.

Keep persistent logged-in browser state across runs.

Vault

Provide matching credentials when a login form appears.

Together

Repair stale sessions instead of logging in cold every run.

Use this pairing for authenticated workflows where sessions expire over time. The Browser Context Profile starts the run with saved state. If that state has gone stale and a matching Vault credential is available, TinyFish can sign in again and refresh the profile state for future runs.

{
  "url": "https://app.example.com/dashboard",
  "goal": "Check the dashboard and summarize anything urgent",
  "use_profile": true,
  "use_vault": true
}

Start with saved state

TinyFish opens the site with the cookies and storage saved in the Browser Context Profile.

Detect stale login

If the site asks for login again, the agent proceeds through the normal login flow.

Repair with Vault

When use_vault: true is set and a matching credential exists, TinyFish can use it to restore the session and keep future profile runs healthy.

Start with Browser Context Profiles for persistence, then add Vault for stale-session repair. This is usually more reliable than asking the agent to log in from scratch on every run.

When to use Browser Context Profiles

Use Browser Context Profiles when…	Start fresh when…
A run should stay logged in	The site is public or anonymous
You repeat the same workflow often	Browser history or cookies would bias the result
Logging in every run is slow, fragile, or MFA-heavy	The task must prove it can work from a blank browser
The account has site preferences, workspace context, or saved filters	You are testing a first-time visitor flow

Proxies and stealth mode

Browser Context Profiles answer “what state should this run start with?” Proxies and Browser Profiles answer “how should the browser connect and behave?”

Capability	Use it for
Browser Context Profile	Reusing saved cookies and storage
Profile proxy location	Keeping a logged-in session tied to one country
Per-run proxy	Choosing a location for one run when the profile has no proxy location
`browser_profile: "stealth"`	Using the anti-detection browser runtime

Choose a profile proxy location when a logged-in session should consistently come from the same country. Leave it blank when location should be decided per run with Proxies. Use Browser Profiles when you need lite or stealth runtime mode.

Limits and expectations

Limit	What to expect
Account scope	Browser Context Profiles are scoped to your TinyFish account and API key owner
Session expiry	Sites can still expire cookies, require MFA, or force re-authentication
CAPTCHA	Browser Context Profiles reduce repeated-login friction, but do not solve reCAPTCHA or hCaptcha
Fresh-browser tasks	Disable `use_profile` when the run should start with no saved state

Next steps

Browser Context Profiles API

Manage profiles programmatically

Vault Credentials

Add stale-session repair

Browser Profiles

Choose lite or stealth runtime mode

Use the API

Vault Credentials

​The flow

1. Set up once

2. Run many times

3. Repair when stale

​Set up a Browser Context Profile

Browser Context Profiles API

​Use a Browser Context Profile

​Manage Browser Context Profiles

​Browser Context Profiles + Vault

Browser Context Profiles

Vault

Together

​When to use Browser Context Profiles

​Proxies and stealth mode

​Limits and expectations

​Next steps

Browser Context Profiles API

Vault Credentials

Browser Profiles

The flow

Set up a Browser Context Profile

Use a Browser Context Profile

Manage Browser Context Profiles

Browser Context Profiles + Vault

When to use Browser Context Profiles

Proxies and stealth mode

Limits and expectations

Next steps