Browser Context Profiles API

Use the Browser Context Profiles API to create persistent browser state, set it up once, and reuse it in future TinyAgent 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.

This page covers the setup flow. For the exact request/response schema of every profile endpoint, see Full API Spec under TinyAgent Reference.

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.

Create or list profiles

Create a named Browser Context Profile with POST /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.

Run with saved state

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

Set up a profile

Start a setup browser with POST /v1/profiles/{profileId}/setup-session and a target url. The response includes a cdp_url — connect to it with Playwright, Puppeteer, Selenium, or another CDP client. For example, with Playwright:

import { chromium } from "playwright";

const CDP_URL = "<cdp_url from setup-session response>";
const browser = await chromium.connectOverCDP(CDP_URL);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://app.example.com/login");
// Automate the login form here, or use your own CDP tooling to complete login.

import asyncio
from playwright.async_api import async_playwright

CDP_URL = "<cdp_url from setup-session response>"

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(CDP_URL)
        page = browser.contexts[0].pages[0]
        await page.goto("https://app.example.com/login")
        # Automate the login form here, or use your own CDP tooling to complete login.

asyncio.run(main())

After login, save the setup session with POST /v1/profiles/{profileId}/save and the session_id from the setup response.

Save, cancel, or time out

The setup browser is temporary. If you do not save it before expires_at, or if you cancel it with POST /v1/profiles/{profileId}/setup-session/cancel, TinyFish discards the unsaved setup state. Cancelling a setup session that has already ended usually returns { "cancelled": true }. Saving a session again after a successful save usually returns the first save’s result. New sites you pass in signed_in_sites are still checked against what the first save captured, and recorded if they pass. If that result is no longer available, or the profile was deleted, you get the usual not-found error.

Run with a Browser Context Profile

Pass use_profile: true to use your default profile, or add profile_id for a specific one — see Create a Google Form With a Signed-In Account for a full worked example.

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:

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

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.

Upload cookies manually

Use POST /v1/profiles/{profileId}/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.

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`
`403`	`FORBIDDEN` with `details.reason: "workflow_key_personal_credentials"`: an organization workflow key called a profile endpoint or set `use_profile`	Use a personal 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

Next steps

Full API Spec

Exact request/response schema for every profile endpoint

Browser Context Profiles overview

Learn when to use Browser Context Profile state

Vault Credentials

Add stale-session repair

Start Here

Search API

Monitor

Fetch API

Browser API

Research API

Datasets API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Browser Context Profiles API

Browser Context Profiles overview

Vault Credentials

API setup lifecycle

Set up a profile

Save, cancel, or time out

Run with a Browser Context Profile

Pair with Vault

Upload cookies manually

Common errors

Next steps

Full API Spec

Browser Context Profiles overview

Vault Credentials

Browser Context Profiles overview

Vault Credentials

​API setup lifecycle

​Set up a profile

​Save, cancel, or time out

​Run with a Browser Context Profile

​Pair with Vault

​Upload cookies manually

​Common errors

​Next steps

Full API Spec

Browser Context Profiles overview

Vault Credentials

API setup lifecycle

Set up a profile

Save, cancel, or time out

Run with a Browser Context Profile

Pair with Vault

Upload cookies manually

Common errors

Next steps