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

# Theo Browser

> 來自 @hitheo/sdk 的託管無頭瀏覽器會話。創建、查看、刷新、嵌入並結束會話，全程使用完整類型化的響應。

`theo.browser` 命名空間封裝了 Theo Browser REST API。每個方法都返回強類型響應，失敗時拋出 `TheoApiError`。

## 快速示例

```typescript theme={null}
import { Theo } from "@hitheo/sdk";

const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

// 1. 啓動一個會話
const session = await theo.browser.create({
  url: "https://news.ycombinator.com",
  keep_alive: false,
  region: "us-west-2",
});

console.log(session.live_view_url); // raw BrowserBase URL
console.log(session.embed_url);     // Theo-branded embed URL

// 2. 斷開連接後刷新實時 URL
const live = await theo.browser.live(session.session_id, { force: true });
console.log(live.live_view_version); // monotonic — rekey your iframe on advance

// 3. 結束會話
await theo.browser.end(session.session_id);
```

## 方法

### `theo.browser.create(request?)`

創建一個新的託管瀏覽器會話。返回 `BrowserSessionHandle`。

```typescript theme={null}
const session = await theo.browser.create({
  url: "https://example.com",     // optional starting URL
  keep_alive: false,              // default: false
  proxies: false,                 // default: false (residential proxy pool)
  region: "us-west-2",            // default: us-west-2
});
```

### `theo.browser.list()`

列出調用方當前所有活躍的會話。返回 `BrowserSessionSnapshot[]`。

### `theo.browser.get(id)`

查看單個會話的詳情。返回 `BrowserSessionSnapshot` —— 包含當前頁面的 URL/標題/favicon，以及一個新生成的 `embed_url`（有效期 1 小時）。

### `theo.browser.live(id, options?)`

刷新可嵌入 iframe 的實時視圖 URL。返回 `BrowserLiveView`。

在嵌入的 iframe 發送 `browserbase-disconnected` 消息後傳入 `{ force: true }`，這樣返回的 URL 會立即指向新的 CDP 頁面 id。

### `theo.browser.end(id)`

結束會話並停止計費。返回 `BrowserEndResult`，其中包含最終時長、代理流量字節數以及費用。

## 類型

```typescript theme={null}
export interface BrowserSessionHandle {
  session_id: string;
  live_view_url: string | null;
  embed_url?: string | null;
  region: BrowserRegion;
  keep_alive: boolean;
  started_at: string;
  expires_at: string;
}

export interface BrowserSessionSnapshot extends BrowserSessionHandle {
  current_url?: string | null;
  current_title?: string | null;
  favicon_url?: string | null;
  last_active_at?: string;
  proxies?: boolean;
}

export interface BrowserLiveView {
  session_id: string;
  live_view_url: string;
  live_view_version: number;
  pages: Array<{
    id: string;
    url: string;
    title: string;
    favicon_url: string;
  }>;
}

export interface BrowserEndResult {
  session_id: string;
  duration_seconds: number;
  proxy_bytes: number;
  cost_cents: number;
}
```

## 相關內容

* [Browser Sessions API](/api-reference/browser/sessions) — REST endpoint reference
* [Embed the Theo Browser](/api-reference/browser/embed) — drop-in iframe integration


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