---
title: "Create a remote browser session"
method: POST
path: "/browser"
tags: ["Browser"]
---

# Create a remote browser session

`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`

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

## Request body

- object: 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.
  - `timeout_seconds` integer, nullable: Inactivity timeout in seconds (5–86400). If omitted, null, or greater than your plan maximum, the plan maximum is used.
  - `proxy_config` object: Proxy for the session. Omit to use the TinyFish proxy in the US.
    - `enabled` boolean: Route the session through a proxy. false means direct egress.
    - `type` 'tinyfish' | 'custom': "tinyfish" uses the TinyFish residential proxy, pinned to one exit IP per session. "custom" routes through your own proxy — requires url.
    - `country_code` string: Exit country for the TinyFish proxy (ISO 3166-1 alpha-2). Defaults to US.
    - `url` string, uri: Your HTTP or HTTPS proxy server URL. Required when type is "custom".
    - `username` string: Username for the custom proxy.
    - `password` string: Password for the custom proxy.

## Response `201`

Browser session created successfully.

- object: Browser session created successfully. Connect to the browser via cdp_url.
  - `session_id` string, required: Unique identifier for this browser session.
  - `cdp_url` string, uri, required: WebSocket URL for browser connection. Pass this to Playwright's connect_over_cdp or any WebSocket-based CDP client.
  - `base_url` string, uri, required: HTTPS base URL for the session. Use to access session endpoints such as /pages.

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `402`: Forbidden - Insufficient credits or no active subscription
- `404`: Browser API is not available
- `409`: Upstream conflict creating the session — retry shortly (RETRY_REQUIRED)
- `429`: Rate limited by browser infrastructure (RATE_LIMIT_EXCEEDED) — honor Retry-After
- `500`: Internal server error, including non-retryable upstream failures
- `503`: Browser infrastructure temporarily unavailable (SERVICE_BUSY) — retryable, honor Retry-After; error.details.upstream_status carries the observed upstream status
- `504`: Browser infrastructure timed out creating the session (TIMEOUT)

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/c48ef855099d?raw)