Browser API Reference

Complete reference for the Browser API endpoints

Endpoints

Method	Path	Description
POST	https://api.browser.tinyfish.ai	Create a browser session
DELETE	https://api.browser.tinyfish.ai/{session_id}	Terminate a browser session

All requests require an X-API-Key header. See Authentication.

The SDKs (tinyfish for Python and @tiny-fish/sdk for TypeScript) target https://agent.tinyfish.ai/v1/browser by default, while the REST host documented here is https://api.browser.tinyfish.ai. Both hosts are supported and behave identically.

Session creation typically takes 10-30 seconds. Set your HTTP client timeout to at least 60 seconds. Direct Browser API sessions are isolated; use Browser Context Profiles when you need reusable cookies or storage.

---

Request

{
  "url": "https://www.tinyfish.ai",
  "timeout_seconds": 300
}

Parameters

url · string

Target URL the session will navigate to on startup. Bare domains (e.g. tinyfish.ai) are automatically prefixed with https://. Omit to start at about:blank.

timeout_seconds · integer

Inactivity timeout in seconds (5–86400). Defaults to your plan maximum.

---

Response

On success, returns 201 Created with a JSON body containing session_id, cdp_url, and base_url.

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

session_id · string

Unique identifier for this session.

cdp_url · string

WebSocket URL for browser connection. Pass this to Playwright’s connect_over_cdp or any CDP client.

base_url · string

HTTPS base URL for the session. Use to access session endpoints such as /pages.

---

DELETE — Terminate a Session

DELETE https://api.browser.tinyfish.ai/{session_id}

Terminates the session immediately. If the session is already ended this call is a no-op and still returns 204.

Path Parameters

session_id · string · required

The session_id returned when the session was created.

Response

Returns 204 No Content with an empty body on success.

Error Codes

HTTP Status	Error Code	Cause
400	INVALID_INPUT	session_id is missing or empty.
401	MISSING_API_KEY / INVALID_API_KEY	Missing or invalid X-API-Key.
404	NOT_FOUND	Session does not exist or belongs to a different API key.
502	INTERNAL_ERROR	Browser infrastructure failed to terminate the session. Retry.

---

Debugging — Open DevTools Inspector

Poll GET {base_url}/pages and open the devtoolsFrontendUrl of the first non-blank page to inspect the live browser session.

Python

async def get_inspector_url(base_url: str) -> str:
    async with httpx.AsyncClient() as client:
        for _ in range(20):
            pages = (await client.get(f"{base_url}/pages", timeout=5)).json()
            nav = next((p for p in pages if p.get("url") not in ("", "about:blank", "about:newtab")), None)
            if nav:
                return nav["devtoolsFrontendUrl"]
            await asyncio.sleep(1)
    raise TimeoutError("navigation never completed")

The page starts at about:blank and navigates asynchronously — skip blank pages when polling to get the correct inspector URL.

---

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 configured inactivity timeout. A session is considered inactive when no CDP commands are being sent.
Explicit termination	Send DELETE https://api.browser.tinyfish.ai/{session_id} to terminate a session immediately. Returns 204 No Content on success. Deleting an already-ended session is idempotent.
Session isolation	Each direct Browser API session is isolated. For reusable cookies and storage, use Browser Context Profiles.

---

SDK Methods

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)

---

End-to-End Example

Create a session, connect with Playwright, take a screenshot, and extract the page title.

Python

import asyncio
from tinyfish import TinyFish
from playwright.async_api import async_playwright

client = TinyFish()

async def main():
    # 1. Create a browser session
    session = client.browser.sessions.create(url="https://scrapeme.live/shop")

    # 2. Connect via Playwright CDP
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(session.cdp_url)
        await asyncio.sleep(2)  # let startup navigation settle

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

        # 3. Interact with the page
        print(await page.title())
        await page.screenshot(path="shop.png")

    # Session auto-cleans up after 1 hour of inactivity

asyncio.run(main())

---

Error Reference

HTTP Status	Error Code	Cause	Resolution
400	INVALID_INPUT	url field is not a valid URL.	Check the details field in the error response for specifics.
401	MISSING_API_KEY / INVALID_API_KEY	Missing or invalid X-API-Key header.	Verify your API key at the dashboard.
402	INSUFFICIENT_CREDITS	No credits or active subscription.	Add credits or upgrade your plan.
404	NOT_FOUND	Browser API is not available on your plan.	Contact support to enable access.
500	INTERNAL_ERROR	Unexpected server error.	Retry after a brief delay. If persistent, check agent.tinyfish.ai/status.
502	INTERNAL_ERROR	Browser infrastructure failed to start the session.	Retry — this is usually transient.

Related

Browser Overview

First request, success shape, and product routing

Authentication

API key setup

Browser Context Profiles

Persist login state for future Agent API runs

Error Codes

Full list of API error codes

Key Concepts

Understand where Browser fits in the overall API surface