Skip to main content
Use the Browser Context 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.

Browser Context Profiles overview

Learn when to use Browser Context Profile state

Vault Credentials

Add stale-session repair

API setup lifecycle

Browser Context Profiles are API-controlled saved state. The hosted setup UI is a manual helper; API users should bring their own Playwright, Puppeteer, or CDP controller and connect to the setup session’s cdp_url. Use base_url only for TinyFish HTTP session endpoints such as /pages; do not pass base_url to Playwright.
1

Create or list profiles

Create a named Browser Context Profile with /v1/profiles, or list existing profiles and choose one.
2

Start setup

Call POST /v1/profiles/{profileId}/setup-session and keep the returned session_id, cdp_url, base_url, timeout_seconds, and expires_at.
3

Connect and log in

Connect your browser automation framework to cdp_url, then log in manually or programmatically.
4

Save or discard

Save with POST /v1/profiles/{profileId}/save and { "session_id": "..." }. Cancelling setup or letting it time out discards unsaved setup state.
5

Run with saved state

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

Create a profile

Set up a profile

Start a setup browser:
Connect to cdp_url with Playwright, Puppeteer, Selenium, or another CDP client. For example, with Playwright:
After login, save the setup session:

Save, cancel, or time out

The setup browser is temporary. If you do not save it before expires_at, or if you cancel it, TinyFish discards the unsaved setup state. Cancel explicitly when you know you do not want to save:

Run with a Browser Context Profile

Use your default Browser Context Profile:
Use a specific Browser Context Profile:
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 Browser Context Profiles with Vault so stale sessions can be repaired:
The Browser Context 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

Inspect and update

Upload cookies manually

Use manual upload when you already have exported browser state and do not need to open a setup browser.
Manual upload supports cookies plus local and session storage.

Common errors

Profile endpoints

All requests require X-API-Key.

Next steps

Browser Context Profiles overview

Learn when to use Browser Context Profile state

Vault Credentials

Add stale-session repair