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

# TinyBrowser

> Create a remote browser session and control it programmatically

The TinyBrowser creates a remote browser session and returns a WebSocket connection URL. Use it when you need direct, low-level browser control — scripting page interactions, running your own automation framework, or tasks that go beyond the [automation run API](https://docs.tinyfish.ai/tinyagent/api/agent/endpoints.md).

> [!NOTE]
>
> TinyBrowser sessions are isolated and do not persist cookies or storage by themselves. For reusable login state, use [TinyProfiles](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md): create a setup session, connect your controller to `cdp_url`, save it, then run TinyAgent automations with `use_profile: true`.

```bash theme={null}
POST https://api.browser.tinyfish.ai
```

***

## Before You Start

**1. Get your API key**

Create a key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).

**2. Store it in your environment**

```bash theme={null}
export TINYFISH_API_KEY="your_api_key_here"
```

**3. Install the required packages**

```bash Python theme={null}
pip install -U tinyfish playwright
playwright install chromium
```

```bash Node theme={null}
npm install @tiny-fish/sdk@latest playwright
npx playwright install chromium
```

All requests require the `X-API-Key` header. See [Authentication](https://docs.tinyfish.ai/authentication.md) for the full setup and troubleshooting guide.

## Your First Request

> [!NOTE]
>
> Session creation typically takes 10-30 seconds. Set your HTTP client timeout to at least 60 seconds.

```python Python theme={null}
from tinyfish import TinyFish

client = TinyFish()
session = client.browser.sessions.create(url="https://www.tinyfish.ai")
print(session.session_id)
print(session.cdp_url)
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const session = await client.browser.sessions.create({
  url: "https://www.tinyfish.ai",
});
console.log(session.session_id);
console.log(session.cdp_url);
```

```bash cURL theme={null}
curl -X POST https://api.browser.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tinyfish.ai"}'
```

## What Success Looks Like

```json theme={null}
{
  "session_id": "br-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cdp_url": "wss://example.tinyfish.io/cdp",
  "base_url": "https://example.tinyfish.io"
}
```

Then connect with Playwright using `cdp_url`:

```python Python theme={null}
import asyncio
from playwright.async_api import async_playwright

CDP_URL = "<cdp_url from API response>"

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(CDP_URL)
        await asyncio.sleep(2)  # let startup navigation settle

        page = browser.contexts[0].pages[0]
        await page.wait_for_load_state("domcontentloaded")
        print(await page.title())

asyncio.run(main())
```

```typescript TypeScript theme={null}
import { chromium } from 'playwright';

const CDP_URL = '<cdp_url from API response>';

const browser = await chromium.connectOverCDP(CDP_URL);
await new Promise(r => setTimeout(r, 2000)); // let startup navigation settle

const page = browser.contexts()[0].pages()[0];
await page.waitForLoadState('domcontentloaded');
console.log(await page.title());
```

> [!NOTE]
>
> Pass `cdp_url` (the WebSocket URL) to `connect_over_cdp`. Do not use `base_url` — it is for polling session status via `/pages`, not for Playwright connections.

## Proxies

By default, every session connects through the TinyFish residential proxy in the US and keeps the same exit IP across all of its connections. Use `proxy_config` to pick another country, bring your own proxy, or connect directly:

```bash Another country theme={null}
curl -X POST https://api.browser.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tinyfish.ai", "proxy_config": {"country_code": "DE"}}'
```

```bash Your own proxy theme={null}
curl -X POST https://api.browser.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_config": {"type": "custom", "url": "http://proxy.example.com:8080", "username": "user", "password": "pass"}}'
```

```bash No proxy theme={null}
curl -X POST https://api.browser.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxy_config": {"enabled": false}}'
```

See the [reference](https://docs.tinyfish.ai/tinybrowser/reference.md#parameters) for every `proxy_config` field.

## When to Use Browser vs the Other APIs

* Use **Browser** when you want direct Playwright or CDP control.
* Use **Agent** when TinyFish should decide the browser actions from a goal.
* Use **Fetch** when you only need extracted content from one or more URLs.
* Use **Search** when you need ranked search results, not a browser session.

***

## Session Lifecycle

| Behavior | Details |
| - | - |
| **Startup navigation** | If `url` was provided at session creation, the browser navigates there immediately. The 201 response is returned before navigation completes — the page may still be loading when you connect. |
| **Inactivity timeout** | Sessions automatically terminate after the inactivity timeout — `timeout_seconds` if set, otherwise your plan maximum (15 minutes on free plans, 60 minutes on paid). A session is considered inactive when no CDP commands are being sent. |
| **Explicit termination** | Send `DELETE https://api.browser.tinyfish.ai/{session_id}` to end a session immediately. See the [reference](https://docs.tinyfish.ai/tinybrowser/reference.md). |
| **Network** | Sessions connect through the TinyFish residential proxy in the US by default, with one exit IP per session. See [Proxies](#proxies). |
| **Session isolation** | Each direct TinyBrowser session is isolated. For reusable cookies and storage, set up a [TinyProfile](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md) instead. |

***

## Read Next

> [card] [API Reference](https://docs.tinyfish.ai/tinybrowser/reference.md)
>
> Request and response schema

> [card] [Authentication](https://docs.tinyfish.ai/authentication.md)
>
> API key setup

> [card] [TinyProfiles](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md)
>
> Persist login state for future TinyAgent runs

> [card] [Browser Profiles](https://docs.tinyfish.ai/key-concepts/browser-profiles.md)
>
> Configure browser runtime behavior for automation runs

> [card] [Key Concepts](https://docs.tinyfish.ai/tinyagent/api/agent/endpoints.md)
>
> Understand when to use Agent vs Browser

> [card] [For coding agents](https://docs.tinyfish.ai/for-coding-agents.md)
>
> One page that routes an agent to the right TinyFish API


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