Skip to main content

​
Endpoint

POST https://api.browser.tinyfish.ai
All requests require an X-API-Key header. See Authentication.

​
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

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

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

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.

​
Error Reference

HTTP StatusError CodeCauseResolution
400INVALID_INPUTurl field is not a valid URL.Check the details field in the error response for specifics.
401MISSING_API_KEY / INVALID_API_KEYMissing or invalid X-API-Key header.Verify your API key at the dashboard.
402INSUFFICIENT_CREDITSNo credits or active subscription.Add credits or upgrade your plan.
404NOT_FOUNDBrowser API is not available on your plan.Contact support to enable access.
500INTERNAL_ERRORUnexpected server error.Retry after a brief delay. If persistent, check status.agent.tinyfish.ai.
502INTERNAL_ERRORBrowser infrastructure failed to start the session.Retry — this is usually transient.

Browser Overview

First request, success shape, and product routing

Authentication

API key setup

Error Codes

Full list of API error codes

Key Concepts

Understand where Browser fits in the overall API surface