Create a remote browser session

Creates a remote tf-browser session and returns CDP connection details. Optionally accepts a target URL to select the best proxy for that domain. Connect to the browser via CDP WebSocket at cdp_url.

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 /v1/browser

Create a remote browser session

cURL

curl --request POST \
  --url https://api.browser.tinyfish.ai/v1/browser \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "url": "https://www.tinyfish.ai",
  "timeout_seconds": 300
}
'

201

{
  "session_id": "tf-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cdp_url": "wss://tetra-abc123.cluster.unikraft.cloud/cdp",
  "base_url": "https://tetra-abc123.cluster.unikraft.cloud"
}

Authorizations

X-API-Key · string · header · required

API key for authentication. Get your key from the API Keys page.

Body

application/json

Browser session parameters

Browser session creation parameters

url · string

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.

Example:

"https://www.tinyfish.ai"

timeout_seconds · integer | null

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

Required range: 5 <= x <= 86400

Example:

300

Response

201

application/json

Browser session created successfully.

Browser session created successfully. Connect to the browser via cdp_url.

session_id · string · required

Unique identifier for this browser session.

Example:

"br-a1b2c3d4-e5f6-7890-abcd-ef1234567890"

cdp_url · string · required

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

Example:

"wss://browser.example.tinyfish.io/session/cdp"

base_url · string · required

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

Example:

"https://browser.example.tinyfish.io/session"