> ## 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 API
> Create a remote browser session and control it programmatically
The Browser API 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](/key-concepts/endpoints).
Browser API sessions are isolated and do not persist cookies or storage by themselves. For reusable login state, use [Browser Context Profiles](/agent-api/browser-context-profiles): create a setup session, connect your controller to `cdp_url`, save it, then run Agent API automations with `use_profile: true`.
```bash theme={null}
POST https://api.browser.tinyfish.ai
```
***
## Before You Start
Create a key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).
```bash theme={null}
export TINYFISH_API_KEY="your_api_key_here"
```
```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](/authentication) for the full setup and troubleshooting guide.
## Your First Request
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 = ""
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 = '';
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());
```
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.
## 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 **1 hour of inactivity**. A session is considered inactive when no CDP commands are being sent. |
| **No explicit delete** | There is no endpoint to delete a session. Sessions are cleaned up automatically when the inactivity timeout elapses. |
| **Session isolation** | Each direct Browser API session is isolated. For reusable cookies and storage, set up a [Browser Context Profile](/agent-api/browser-context-profiles) instead. |
***
## Read Next
Request and response schema
API key setup
Persist login state for future Agent API runs
Configure browser runtime behavior for automation runs
Understand when to use Agent vs Browser
One page that routes an agent to the right TinyFish API