> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TinyBrowser API Reference

> Complete reference for the TinyBrowser 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](https://docs.tinyfish.ai/authentication.md).

> [!NOTE]
>
> 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.

> [!NOTE]
>
> Session creation typically takes 10-30 seconds. Set your HTTP client timeout to at least 60 seconds. Direct TinyBrowser sessions are isolated; use [TinyProfiles](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md) when you need reusable cookies or storage.

***

## Request

```json theme={null}
{
  "url": "https://www.tinyfish.ai",
  "timeout_seconds": 300,
  "proxy_config": { "country_code": "DE" }
}
```

### 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 account's maximum.

**proxy\_config** `object`

How the session connects to the internet. Omit to use the TinyFish residential proxy in the US.

| Field | Type | Default | Description |
| - | - | - | - |
| `enabled` | `boolean` | `true` | Set `false` to connect directly, with no proxy. Other fields are ignored. |
| `type` | `"tinyfish"` \| `"custom"` | `"tinyfish"` | `tinyfish` uses the TinyFish residential proxy. `custom` routes through your own proxy. |
| `country_code` | `string` | `"US"` | Exit country for the `tinyfish` proxy. Any [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, case-insensitive (e.g. `DE`, `jp`). Not allowed with `custom`. |
| `url` | `string` | — | Your proxy URL. Required with `custom`. Must be `http://` or `https://`. |
| `username` | `string` | — | Username for your custom proxy. |
| `password` | `string` | — | Password for your custom proxy. |

Unknown fields are rejected with `400`.

### Proxy Behavior

* **Sticky exit IP.** With the `tinyfish` proxy, a session keeps the same exit IP across all its connections, including after idle periods. Different sessions get different IPs. Residential IPs can occasionally go offline; the session then moves to a new IP in the same country.
* **Default.** Sessions created without `proxy_config` use the `tinyfish` proxy in the US.
* **Custom proxies.** TinyFish connects to your proxy as given and does not rotate or pin its IP. Only `http://` and `https://` proxies are supported.

***

## Response

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

```json theme={null}
{
  "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

```bash theme={null}
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. |
| 409 | `RETRY_REQUIRED` | Conflicting operation on the session. Termination not confirmed — retry the delete shortly. |
| 429 | `RATE_LIMIT_EXCEEDED` | Browser infrastructure rate limit. Honor `Retry-After`. |
| 500 | `INTERNAL_ERROR` | Unexpected or non-retryable infrastructure failure. Termination is not confirmed — the session may still be running; retry the delete. |
| 503 | `SERVICE_BUSY` | Browser infrastructure temporarily unavailable. Termination not confirmed — retry, honoring `Retry-After`. |
| 504 | `TIMEOUT` | Browser infrastructure timed out terminating the session. Retry. |

Infrastructure errors include `error.details.upstream_status` — the backend status when one was received, otherwise the status TinyFish synthesized (502 for transport failures, 504 for timeouts). Every error also carries `request_id`, echoed in the `X-Request-ID` header; quote it when contacting support.

***

## 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 Python theme={null}
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")
```

```typescript TypeScript theme={null}
async function getInspectorUrl(baseUrl: string): Promise<string> {
  for (let i = 0; i < 20; i++) {
    const res = await fetch(`${baseUrl}/pages`);
    const pages: { url: string; devtoolsFrontendUrl: string }[] = await res.json();
    const nav = pages.find(p => !['', 'about:blank', 'about:newtab'].includes(p.url));
    if (nav) return nav.devtoolsFrontendUrl;
    await new Promise(r => setTimeout(r, 1000));
  }
  throw new Error('navigation never completed');
}
```

> [!NOTE]
>
> 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 TinyBrowser session is isolated. For reusable cookies and storage, use [TinyProfiles](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md). |

***

## SDK Methods

```python Python theme={null}
from tinyfish import TinyFish

client = TinyFish()
session = client.browser.sessions.create(url="https://www.tinyfish.ai")
print(session.session_id)
print(session.cdp_url)
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const session = await client.browser.sessions.create({
  url: "https://www.tinyfish.ai",
});
console.log(session.session_id);
console.log(session.cdp_url);
```

***

## End-to-End Example

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

```python Python theme={null}
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 ends after its inactivity timeout, or DELETE it explicitly

asyncio.run(main())
```

```typescript TypeScript theme={null}
import { TinyFish } from "@tiny-fish/sdk";
import { chromium } from "playwright";

const client = new TinyFish();

// 1. Create a browser session
const session = await client.browser.sessions.create({
  url: "https://scrapeme.live/shop",
});

// 2. Connect via Playwright CDP
const browser = await chromium.connectOverCDP(session.cdp_url);
await new Promise((r) => setTimeout(r, 2000)); // let startup navigation settle

const page = browser.contexts()[0].pages()[0];
await page.waitForLoadState("domcontentloaded");

// 3. Interact with the page
console.log(await page.title());
await page.screenshot({ path: "shop.png" });

// Session ends after its inactivity timeout, or DELETE it explicitly
```

***

## Error Reference

| HTTP Status | Error Code | Cause | Resolution |
| - | - | - | - |
| 400 | `INVALID_INPUT` | `url` field is not a valid URL, or `proxy_config` is invalid (unknown field, unknown `country_code`, `custom` without `url`, non-HTTP(S) proxy 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](https://agent.tinyfish.ai/api-keys). |
| 402 | `INSUFFICIENT_CREDITS` | Your TinyFish wallet balance is too low to start this run. | Check `GET /v1/wallet` and add money at the [wallet page](https://agent.tinyfish.ai/wallet) — minimum top-up \$10. |
| 404 | `NOT_FOUND` | TinyBrowser is not enabled for your account. | Contact support to enable access. |
| 409 | `RETRY_REQUIRED` | Upstream conflict creating the session. | Retry after a brief delay. |
| 429 | `RATE_LIMIT_EXCEEDED` | Browser infrastructure rate limit. | Back off and honor the `Retry-After` header. |
| 500 | `INTERNAL_ERROR` | Unexpected server error, including non-retryable infrastructure failures. | Not resolved by retrying. If persistent, check [agent.tinyfish.ai/status](https://agent.tinyfish.ai/status). |
| 503 | `SERVICE_BUSY` | Browser infrastructure temporarily unavailable. Session creation was not confirmed. | Retry, honoring the `Retry-After` header. `error.details.upstream_status` carries the backend status, or the status TinyFish synthesized when the call never completed. |
| 504 | `TIMEOUT` | Browser infrastructure timed out starting the session. | Retry after a brief delay. |

## Related

> [card] [Browser Overview](https://docs.tinyfish.ai/tinybrowser.md)
>
> First request, success shape, and product routing

> [card] [Authentication](https://docs.tinyfish.ai/authentication.md)
>
> API key setup

> [card] [TinyProfiles](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md)
>
> Persist login state for future TinyAgent runs

> [card] [Error Codes](https://docs.tinyfish.ai/error-codes.md)
>
> Full list of API error codes

> [card] [Key Concepts](https://docs.tinyfish.ai/tinyagent/api/agent/endpoints.md)
>
> Understand where Browser fits in the overall API surface


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.