Browser

Create a remote browser session

Creates a remote tf-browser session and returns CDP connection details. Connect to the browser via CDP WebSocket at cdp_url.

By default the session egresses through the TinyFish residential proxy in the US, pinned to one exit IP for the life of the session. Use proxy_config to pick another country (country_code, any ISO 3166-1 alpha-2), bring your own proxy (type: "custom"), or disable the proxy (enabled: false).

Use timeout_seconds to set a custom inactivity timeout (5–86400 seconds). If omitted, null, or greater than your plan maximum, the plan maximum is used (15 min on free tier, 60 min on paid).

post/browser

Request

Base URL: https://api.browser.tinyfish.ai
URL: https://api.browser.tinyfish.ai/browser
Auth: API key in header X-API-Key

Request body

urlstring

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

timeout_secondsinteger nullable

Inactivity timeout in seconds (5–86400). If omitted, null, or greater than your plan maximum, the plan maximum is used.

Example request

{
  "url": "https://www.tinyfish.ai",
  "timeout_seconds": 300,
  "proxy_config": {
    "enabled": true,
    "type": "tinyfish",
    "country_code": "US",
    "url": "http://proxy.example.com:8080"
  }
}

Response

Browser session created successfully.

session_idstring required

Unique identifier for this browser session.

cdp_urlstring uri required

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

base_urlstring uri required

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

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.