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.

Browser API sessions are isolated and do not persist cookies or storage by themselves. For reusable login state, use Browser Context Profiles: create a setup session, connect your controller to cdp_url, save it, then run Agent API automations with use_profile: true.

POST https://api.browser.tinyfish.ai

---

Before You Start

1. Get your API key

   Create a key at agent.tinyfish.ai/api-keys.

2. Store it in your environment

   export TINYFISH_API_KEY="your_api_key_here"
   
3. Install the required packages

   Python

   pip install -U tinyfish playwright
   playwright install chromium
   

All requests require the X-API-Key header. See 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

from tinyfish import TinyFish

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

What Success Looks Like

{
  "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

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())

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

---

Read Next

API Reference

Request and response schema

Authentication

API key setup

Browser Context Profiles

Persist login state for future Agent API runs

Browser Profiles

Configure browser runtime behavior for automation runs

Key Concepts

Understand when to use Agent vs Browser

For coding agents

One page that routes an agent to the right TinyFish API