Skip to main content
Create, manage, and set up Browser Context Profiles — reusable saved browser sessions. Full setup flow and SDK connection examples: Browser Context Profiles API. All requests require the X-API-Key header unless noted otherwise. See Authentication.

​
Quick Setup

1

Create a profile

POST /v1/profiles with a name. Start a setup session, sign in through it, then save it — full request and response schemas: Browser Context Profiles API.
2

Run with the saved session

Pass use_profile: true (and optionally profile_id) on an automation request to start the run already signed in.
The sections below are the exact request/response schema for every Browser Context Profiles endpoint.

​
Endpoints

​
List Profiles

GET /v1/profiles List every Browser Context Profile on the account.

​
Create a Profile

POST /v1/profiles Create a named profile.
​
string
required
Profile display name.
​
boolean
Makes this the default profile for use_profile: true.
​
string | null
Supported country code, or null for no profile proxy.
Response (201):
​
string
Browser Context Profile ID.
​
string
Profile display name.
​
string | null
​
boolean
​
string
​
integer
​
string
​
string

​
Get Profile Details

GET /v1/profiles/{profileId}
​
string
required
Browser Context Profile ID.
Same response fields as create, plus:
​
array
Saved domains and their capture state.

​
Update a Profile

PATCH /v1/profiles/{profileId}
​
string
required
Browser Context Profile ID.
​
string
New display name.
​
boolean
​
string | null
Returns the same shape as GET /v1/profiles/{profileId}.

​
Delete a Profile

DELETE /v1/profiles/{profileId}
​
string
required
Browser Context Profile ID.
​
boolean

​
Start a Setup Session

POST /v1/profiles/{profileId}/setup-session
​
string
required
Browser Context Profile ID.
​
string
Target URL the browser session will navigate to on startup. Bare domains (e.g. tinyfish.ai) are automatically prefixed with https://.
​
integer
Inactivity timeout in seconds (5–86400). Defaults to your plan maximum.
​
string
Unique identifier for this browser session.
​
string
WebSocket URL for browser connection. Pass this to Playwright’s connect_over_cdp or any CDP client.
​
string
HTTPS base URL for the session. Use to access session endpoints such as /pages — don’t pass this to Playwright.
​
integer
​
string

​
Cancel a Setup Session

POST /v1/profiles/{profileId}/setup-session/cancel
​
string
required
Browser Context Profile ID.
​
string
required
From the setup-session response.
​
boolean

​
Save a Setup Session

POST /v1/profiles/{profileId}/save
​
string
required
Browser Context Profile ID.
​
string
required
From the setup-session response.
​
array
Sites the caller believes were signed into during setup, as hosts or URLs.
​
array
​
array
​
integer
​
object
​
integer
​
integer
​
array
Sites this save recorded as signed in. Present only when sign-in tracking is enabled for the account.

​
Upload Cookies and Storage

POST /v1/profiles/{profileId}/upload Upload exported browser state directly, without opening a setup browser.
​
string
required
Browser Context Profile ID.
​
array
required
​
array
​
array
​
array
​
array
​
integer
​
object

​
Delete a Domain

DELETE /v1/profiles/{profileId}/domains/{domain} Delete one stored domain’s saved state from a profile, without deleting the profile itself.
​
string
required
Browser Context Profile ID.
​
string
required
Domain to remove from the profile.
​
boolean