Skip to main content
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. 
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

pip install playwright httpx
playwright install chromium
All requests require the X-API-Key header. See Authentication for the full setup and troubleshooting guide.

​
Your First Request

import httpx

response = httpx.post(
    "https://api.browser.tinyfish.ai",
    headers={"X-API-Key": "your_api_key_here"},
    json={"url": "https://www.tinyfish.ai"},
)
response.raise_for_status()

session = response.json()
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: 
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

BehaviorDetails
Startup navigationIf 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 timeoutSessions automatically terminate after 1 hour of inactivity. A session is considered inactive when no CDP commands are being sent.
No explicit deleteThere is no endpoint to delete a session. Sessions are cleaned up automatically when the inactivity timeout elapses.
Session isolationEach session is a fully isolated browser instance. No cookies, storage, or state is shared between sessions.

API Reference

Request and response schema

Authentication

API key setup

Browser Profiles

Configure browser 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