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

# About TinyProfile

> Persist logged-in browser state across TinyFish runs

Stop logging in from scratch on every run.

TinyProfiles let TinyFish save browser state — cookies, local storage, and session storage — and
reuse it later. Recurring automations can start where a real returning user would: already signed in,
with the right workspace, preferences, and site context loaded.

> [!NOTE]
>
> **TinyProfiles are not Browser Profiles.**
> [Browser Profiles](https://docs.tinyfish.ai/key-concepts/browser-profiles.md) choose the runtime mode with
> `browser_profile: "lite" | "stealth"`. TinyProfiles save session state across runs.

> [card] [Use the API](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md)
>
> Create and run with TinyProfiles programmatically

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

## The flow

> [card] 1. Set up once
>
> Open a setup browser, sign in, and save the session.

> [card] 2. Run many times
>
> Reuse saved state so recurring runs start authenticated.

> [card] 3. Repair when stale
>
> Add Vault so TinyFish can log back in if the session expires.

## Set up a TinyProfile

> [tab] Dashboard
>
> 1. Go to **TinyProfiles** in the TinyFish dashboard.
>
> 2. Click **Create Profile**.
>
> 3. Name the profile.
>
> 4. Optional: mark it as the default profile.
>
> 5. Optional: choose a proxy location for the profile.
>
> 6. Click **Create and set up**.
>
> 7. Sign in to the target site in the setup browser.
>
> 8. Save the setup session.
>
> > [!TIP]
> >
> > Use one TinyProfile per account or environment, such as `Salesforce Production` and
> > `Salesforce Sandbox`.

> [tab] API
>
> Create the profile, start a setup session, connect your own Playwright/Puppeteer/CDP controller
> to `cdp_url`, sign in, then save it with the returned `session_id`. The hosted setup UI is
> only a manual helper; API setup is controlled through these endpoints.
>
> ```bash theme={null}
> curl -X POST https://agent.tinyfish.ai/v1/profiles \
>   -H "X-API-Key: $TINYFISH_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Salesforce Production",
>     "set_as_default": true
>   }'
> ```
>
> ```bash theme={null}
> curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/setup-session \
>   -H "X-API-Key: $TINYFISH_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{ "url": "https://app.example.com/login" }'
> ```
>
> The setup-session response includes `session_id`, `cdp_url`, `base_url`, `timeout_seconds`, and
> `expires_at`. Use `cdp_url` for Playwright/Puppeteer/CDP. Use `base_url` only for TinyFish HTTP
> session endpoints such as `/pages`. After signing in, save the setup browser state:
>
> ```bash theme={null}
> curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/save \
>   -H "X-API-Key: $TINYFISH_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{ "session_id": "sess_123" }'
> ```
>
> > [card] [TinyProfiles API](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md)
> >
> > Full setup, upload, update, and cleanup reference

## Use a TinyProfile

> [tab] Playground
>
> 1. Open the Playground.
> 2. Click the profile icon in the toolbar.
> 3. Turn on **Use TinyProfile**.
> 4. Choose a profile, or use your default profile.
> 5. Run the automation.
>
> If no profile exists, click **Go to TinyProfiles** to create one first.

> [tab] API: default profile
>
> Use your default TinyProfile with `use_profile: true`:
>
> ```bash theme={null}
> curl -X POST https://agent.tinyfish.ai/v1/automation/run \
>   -H "X-API-Key: $TINYFISH_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "url": "https://app.example.com/dashboard",
>     "goal": "Open the dashboard and summarize the latest alerts",
>     "use_profile": true
>   }'
> ```

> [tab] API: specific profile
>
> Target a specific TinyProfile by ID:
>
> ```bash theme={null}
> curl -X POST https://agent.tinyfish.ai/v1/automation/run-async \
>   -H "X-API-Key: $TINYFISH_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "url": "https://app.example.com/dashboard",
>     "goal": "Export the weekly usage report",
>     "use_profile": true,
>     "profile_id": "prof_abc123def4567890"
>   }'
> ```

## Manage TinyProfiles

On the **TinyProfiles** page, you can:

* Rename TinyProfiles
* Set a default TinyProfile
* Copy a profile ID
* View saved domains
* Set or clear a profile proxy location
* Upload cookies manually
* Delete individual domains
* Delete TinyProfiles

> [!NOTE]
>
> You cannot delete your only active profile. Create another profile first.

## TinyProfiles + Vault

The best authenticated setup is TinyProfiles plus [Vault Credentials](https://docs.tinyfish.ai/key-concepts/credentials.md).

> [card] TinyProfiles
>
> Keep persistent logged-in browser state across runs.

> [card] Vault
>
> Provide matching credentials when a login form appears.

> [card] Together
>
> Repair stale sessions instead of logging in cold every run.

Use this pairing for authenticated workflows where sessions expire over time. The TinyProfile starts
the run with saved state. If that state has gone stale and a matching Vault credential is available,
TinyFish can sign in again and refresh the profile state for future runs.

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

**1. Start with saved state**

TinyFish opens the site with the cookies and storage saved in the TinyProfile.

**2. Detect stale login**

If the site asks for login again, the agent proceeds through the normal login flow.

**3. Repair with Vault**

When `use_vault: true` is set and a matching credential exists, TinyFish can use it to restore
the session and keep future profile runs healthy.

> [!TIP]
>
> Start with TinyProfiles for persistence, then add Vault for stale-session repair. This is usually
> more reliable than asking the agent to log in from scratch on every run.

## When to use TinyProfiles

| Use TinyProfiles when... | Start fresh when... |
| - | - |
| A run should stay logged in | The site is public or anonymous |
| You repeat the same workflow often | Browser history or cookies would bias the result |
| Logging in every run is slow, fragile, or MFA-heavy | The task must prove it can work from a blank browser |
| The account has site preferences, workspace context, or saved filters | You are testing a first-time visitor flow |

## Proxies and stealth mode

TinyProfiles answer “what state should this run start with?” Proxies and Browser Profiles answer
“how should the browser connect and behave?”

| Capability | Use it for |
| - | - |
| TinyProfile | Reusing saved cookies and storage |
| Profile proxy location | Keeping a logged-in session tied to one country |
| Per-run proxy | Choosing a location for one run when the profile has no proxy location |
| `browser_profile: "stealth"` | Using the anti-detection browser runtime |

Choose a profile proxy location when a logged-in session should consistently come from the same
country. Leave it blank when location should be decided per run with [Proxies](https://docs.tinyfish.ai/key-concepts/proxies.md).
Use [Browser Profiles](https://docs.tinyfish.ai/key-concepts/browser-profiles.md) when you need `lite` or `stealth` runtime mode.

## Limits and expectations

| Limit | What to expect |
| - | - |
| Account scope | TinyProfiles are scoped to your TinyFish account and API key owner. Organization workflow keys can't use them; use a personal key |
| Session expiry | Sites can still expire cookies, require MFA, or force re-authentication |
| CAPTCHA | TinyProfiles reduce repeated-login friction, but do not solve reCAPTCHA or hCaptcha |
| Fresh-browser tasks | Disable `use_profile` when the run should start with no saved state |

## Next steps

> [card] [TinyProfiles API](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md)
>
> Manage profiles programmatically

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

> [card] [Browser Profiles](https://docs.tinyfish.ai/key-concepts/browser-profiles.md)
>
> Choose lite or stealth runtime mode


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