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’scdp_url. Use base_url only for TinyFish HTTP session endpoints such as /pages; do not pass
base_url to Playwright.
Create or list profiles
Create a named Browser Context Profile with
/v1/profiles, or list existing profiles and choose one.Start setup
Call
POST /v1/profiles/{profileId}/setup-session and keep the returned session_id,
cdp_url, base_url, timeout_seconds, and expires_at.Connect and log in
Connect your browser automation framework to
cdp_url, then log in manually or programmatically.Save or discard
Save with
POST /v1/profiles/{profileId}/save and { "session_id": "..." }. Cancelling
setup or letting it time out discards unsaved setup state.Create a profile
| Create field | Type | Notes |
|---|---|---|
name | string | Required. 1–100 characters. |
set_as_default | boolean | Optional. Makes this the default profile for use_profile: true. |
proxy_country_code | string | null | Optional. Supported country code, or null for no profile proxy. |
Set up a profile
Start a setup browser:cdp_url with Playwright, Puppeteer, Selenium, or another CDP client. For example,
with Playwright:
Save, cancel, or time out
The setup browser is temporary. If you do not save it beforeexpires_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:| Field | Type | Required | Notes |
|---|---|---|---|
use_profile | boolean | No | Use Browser Context Profile state. Without profile_id, TinyFish uses your default Browser Context Profile. |
profile_id | string | No | 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 Browser Context Profiles with Vault so stale sessions can be repaired: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.| Limit | Value |
|---|---|
| Upload payload | 5 MB |
| Cookies per upload | 3,000 |
| Domains per profile | 100 |
Common errors
| Status | Meaning | Fix |
|---|---|---|
400 | Invalid body, missing default profile, or profile_id without use_profile: true | Fix the request or create a default profile |
401 | Missing or invalid API key | Set X-API-Key |
404 | Profile or saved domain not found | Check the profile ID or domain |
409 | Setup/save/delete cleanup needs a retry, or the setup browser is no longer running | Retry the operation or start a new setup session |
Profile endpoints
All requests requireX-API-Key.
| Endpoint | Method | Purpose |
|---|---|---|
/v1/profiles | GET | List profiles |
/v1/profiles | POST | Create a profile |
/v1/profiles/{profileId} | GET | Get profile details and saved domains |
/v1/profiles/{profileId} | PATCH | Rename a profile, set default, or update proxy location |
/v1/profiles/{profileId} | DELETE | Delete a profile |
/v1/profiles/{profileId}/setup-session | POST | Start an interactive setup browser |
/v1/profiles/{profileId}/setup-session/cancel | POST | Cancel a setup browser session without saving |
/v1/profiles/{profileId}/save | POST | Save a setup browser session |
/v1/profiles/{profileId}/upload | POST | Upload cookies and storage manually |
/v1/profiles/{profileId}/domains/{domain} | DELETE | Delete stored state for one domain |
Next steps
Browser Context Profiles overview
Learn when to use Browser Context Profile state
Vault Credentials
Add stale-session repair