> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Context Profiles API

> Create, set up, and use Browser Context Profiles from the TinyAgent 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.

> [!NOTE]
>
> This page covers the setup flow. For the exact request/response schema of every profile endpoint, see **Full API Spec** under [TinyAgent Reference](https://docs.tinyfish.ai/agent/api/profiles).

> [card] [Browser Context Profiles overview](https://docs.tinyfish.ai/key-concepts/browser-context-profiles.md)
>
> Learn when to use Browser Context Profile state

> [card] [Vault Credentials](https://docs.tinyfish.ai/key-concepts/credentials.md)
>
> 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 `POST /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.

## 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:

```typescript TypeScript theme={null}
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.
```

```python Python theme={null}
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](https://docs.tinyfish.ai/agent/how-to/create-google-form-with-profile.md) for a
full worked example.

> [!NOTE]
>
> 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:

```json theme={null}
{
  "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

> [card] [Full API Spec](https://docs.tinyfish.ai/agent/api/profiles)
>
> Exact request/response schema for every profile endpoint

> [card] [Browser Context Profiles overview](https://docs.tinyfish.ai/key-concepts/browser-context-profiles.md)
>
> Learn when to use Browser Context Profile state

> [card] [Vault Credentials](https://docs.tinyfish.ai/key-concepts/credentials.md)
>
> Add stale-session repair


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.