Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

Nick:

Nicolasbb1df562cd83
diff --git a/apps/js-sdk/firecrawl/src/v2/client.ts b/apps/js-sdk/firecrawl/src/v2/client.ts
index 3cdbda053..31d5a182c 100644
--- a/apps/js-sdk/firecrawl/src/v2/client.ts
+++ b/apps/js-sdk/firecrawl/src/v2/client.ts
@@ -20,6 +20,12 @@ import {
} from "./methods/batch";
import { startExtract, getExtractStatus, extract as extractWaiter } from "./methods/extract";
import { startAgent, getAgentStatus, cancelAgent, agent as agentWaiter } from "./methods/agent";
+import {
+ browser as browserMethod,
+ browserExecute,
+ deleteBrowser,
+ listBrowsers,
+} from "./methods/browser";
import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
import type {
Document,
@@ -40,6 +46,10 @@ import type {
CrawlOptions,
BatchScrapeOptions,
PaginationConfig,
+ BrowserCreateResponse,
+ BrowserExecuteResponse,
+ BrowserDeleteResponse,
+ BrowserListResponse,
} from "./types";
import { Watcher } from "./watcher";
import type { WatcherOptions } from "./watcher";
@@ -298,6 +308,47 @@ export class FirecrawlClient {
return cancelAgent(this.http, jobId);
}
+ // Browser
+ /**
+ * Create a new browser session.
+ * @param args Session options (ttlTotal, ttlWithoutActivity, streamWebView).
+ * @returns Session id and CDP URL.
+ */
+ async browser(
+ args: Parameters<typeof browserMethod>[1] = {}
+ ): Promise<BrowserCreateResponse> {
+ return browserMethod(this.http, args);
+ }
+ /**
+ * Execute code in a browser session.
+ * @param sessionId Browser session id.
+ * @param args Code and language to execute.
+ * @returns Execution result.
+ */
+ async browserExecute(
+ sessionId: string,
+ args: Parameters<typeof browserExecute>[2]
+ ): Promise<BrowserExecuteResponse> {
+ return browserExecute(this.http, sessionId, args);
+ }
+ /**
+ * Delete a browser session.
+ * @param sessionId Browser session id.
+ */
+ async deleteBrowser(sessionId: string): Promise<BrowserDeleteResponse> {
+ return deleteBrowser(this.http, sessionId);
+ }
+ /**
+ * List browser sessions.
+ * @param args Optional filter (status: "active" | "destroyed").
+ * @returns List of browser sessions.
+ */
+ async listBrowsers(
+ args: Parameters<typeof listBrowsers>[1] = {}
+ ): Promise<BrowserListResponse> {
+ return listBrowsers(this.http, args);
+ }
+
// Usage
/** Current concurrency usage. */
async getConcurrency() {
diff --git a/apps/js-sdk/firecrawl/src/v2/methods/browser.ts b/apps/js-sdk/firecrawl/src/v2/methods/browser.ts
new file mode 100644
index 000000000..f952311bc
--- /dev/null
+++ b/apps/js-sdk/firecrawl/src/v2/methods/browser.ts
@@ -0,0 +1,92 @@
+import type {
+ BrowserCreateResponse,
+ BrowserExecuteResponse,
+ BrowserDeleteResponse,
+ BrowserListResponse,
+} from "../types";
+import { HttpClient } from "../utils/httpClient";
+import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";
+
+export async function browser(
+ http: HttpClient,
+ args: {
+ ttlTotal?: number;
+ ttlWithoutActivity?: number;
+ streamWebView?: boolean;
+ } = {}
+): Promise<BrowserCreateResponse> {
+ const body: Record<string, unknown> = {};
+ if (args.ttlTotal != null) body.ttlTotal = args.ttlTotal;
+ if (args.ttlWithoutActivity != null) body.ttlWithoutActivity = args.ttlWithoutActivity;
+ if (args.streamWebView != null) body.streamWebView = args.streamWebView;
+
+ try {
+ const res = await http.post<BrowserCreateResponse>("/v2/browser", body);
+ if (res.status !== 200) throwForBadResponse(res, "create browser session");
+ return res.data;
+ } catch (err: any) {
+ if (err?.isAxiosError) return normalizeAxiosError(err, "create browser session");
+ throw err;
+ }
+}
+
+export async function browserExecute(
+ http: HttpClient,
+ sessionId: string,
+ args: {
+ code: string;
+ language?: "python" | "js";
+ }
+): Promise<BrowserExecuteResponse> {
+ const body: Record<string, unknown> = {
+ code: args.code,
+ language: args.language ?? "python",
+ };
+
+ try {
+ const res = await http.post<BrowserExecuteResponse>(
+ `/v2/browser/${sessionId}/execute`,
+ body
+ );
+ if (res.status !== 200) throwForBadResponse(res, "execute browser code");
+ return res.data;
+ } catch (err: any) {
+ if (err?.isAxiosError) return normalizeAxiosError(err, "execute browser code");
+ throw err;
+ }
+}
+
+export async function deleteBrowser(
+ http: HttpClient,
+ sessionId: string
+): Promise<BrowserDeleteResponse> {
+ try {
+ const res = await http.delete<BrowserDeleteResponse>(
+ `/v2/browser/${sessionId}`
+ );
+ if (res.status !== 200) throwForBadResponse(res, "delete browser session");
+ return res.data;
+ } catch (err: any) {
+ if (err?.isAxiosError) return normalizeAxiosError(err, "delete browser session");
+ throw err;
+ }
+}
+
+export async function listBrowsers(
+ http: HttpClient,
+ args: {
+ status?: "active" | "destroyed";
+ } = {}
+): Promise<BrowserListResponse> {
+ let endpoint = "/v2/browser";
+ if (args.status) endpoint += `?status=${args.status}`;
+
+ try {
+ const res = await http.get<BrowserListResponse>(endpoint);
+ if (res.status !== 200) throwForBadResponse(res, "list browser sessions");
+ return res.data;
+ } catch (err: any) {
+ if (err?.isAxiosError) return normalizeAxiosError(err, "list browser sessions");
+ throw err;
+ }
+}
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index df9c79de8..fb8ccd833 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -683,3 +683,37 @@ export interface QueueStatusResponse {
maxConcurrency: number;
mostRecentSuccess: string | null;
}
+
+// Browser types
+export interface BrowserCreateResponse {
+ success: boolean;
+ id?: string;
+ cdpUrl?: string;
+ error?: string;
+}
+
+export interface BrowserExecuteResponse {
+ success: boolean;
+ result?: string;
+ error?: string;
+}
+
+export interface BrowserDeleteResponse {
+ success: boolean;
+ error?: string;
+}
+
+export interface BrowserSession {
+ id: string;
+ status: string;
+ cdpUrl: string;
+ streamWebView: boolean;
+ createdAt: string;
+ lastActivity: string;
+}
+
+export interface BrowserListResponse {
+ success: boolean;
+ sessions?: BrowserSession[];
+ error?: string;
+}
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index f461a8122..ada0efe08 100644
--- a/apps/python-sdk/firecrawl/v2/client.py
+++ b/apps/python-sdk/firecrawl/v2/client.py
@@ -51,6 +51,7 @@ from .methods import batch as batch_methods
from .methods import usage as usage_methods
from .methods import extract as extract_module
from .methods import agent as agent_module
+from .methods import browser as browser_module
from .watcher import Watcher
class FirecrawlClient:
@@ -949,6 +950,84 @@ class FirecrawlClient:
"""Get metrics about the team's scrape queue."""
return usage_methods.get_queue_status(self.http_client)
+ # Browser
+ def browser(
+ self,
+ *,
+ ttl_total: Optional[int] = None,
+ ttl_without_activity: Optional[int] = None,
+ stream_web_view: Optional[bool] = None,
+ ):
+ """Create a new browser session.
+
+ Args:
+ ttl_total: Total time-to-live in seconds (30-3600, default 300)
+ ttl_without_activity: TTL without activity in seconds (10-3600)
+ stream_web_view: Whether to enable webview streaming
+
+ Returns:
+ BrowserCreateResponse with session id and CDP URL
+ """
+ return browser_module.browser(
+ self.http_client,
+ ttl_total=ttl_total,
+ ttl_without_activity=ttl_without_activity,
+ stream_web_view=stream_web_view,
+ )
+
+ def browser_execute(
+ self,
+ session_id: str,
+ code: str,
+ *,
+ language: Literal["python", "js"] = "python",
+ ):
+ """Execute code in a browser session.
+
+ Args:
+ session_id: Browser session ID
+ code: Code to execute
+ language: Programming language ("python" or "js")
+
+ Returns:
+ BrowserExecuteResponse with execution result
+ """
+ return browser_module.browser_execute(
+ self.http_client,
+ session_id,
+ code,
+ language=language,
+ )
+
+ def delete_browser(self, session_id: str):
+ """Delete a browser session.
+
+ Args:
+ session_id: Browser session ID
+
+ Returns:
+ BrowserDeleteResponse
+ """
+ return browser_module.delete_browser(self.http_client, session_id)
+
+ def list_browsers(
+ self,
+ *,
+ status: Optional[Literal["active", "destroyed"]] = None,
+ ):
+ """List browser sessions.
+
+ Args:
+ status: Filter by session status ("active" or "destroyed")
+
+ Returns:
+ BrowserListResponse with list of sessions
+ """
+ return browser_module.list_browsers(
+ self.http_client,
+ status=status,
+ )
+
def watcher(
self,
job_id: str,
diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.py
index 5bd482977..7ad422ed8 100644
--- a/apps/python-sdk/firecrawl/v2/client_async.py
+++ b/apps/python-sdk/firecrawl/v2/client_async.py
@@ -46,6 +46,7 @@ from .methods.aio import map as async_map # type: ignore[attr-defined]
from .methods.aio import usage as async_usage # type: ignore[attr-defined]
from .methods.aio import extract as async_extract # type: ignore[attr-defined]
from .methods.aio import agent as async_agent # type: ignore[attr-defined]
+from .methods.aio import browser as async_browser # type: ignore[attr-defined]
from .watcher_async import AsyncWatcher
@@ -420,6 +421,86 @@ class AsyncFirecrawlClient:
"""
return await async_agent.cancel_agent(self.async_http_client, job_id)
+ # Browser
+ async def browser(
+ self,
+ *,
+ ttl_total: Optional[int] = None,
+ ttl_without_activity: Optional[int] = None,
+ stream_web_view: Optional[bool] = None,
+ ):
+ """Create a new browser session.
+
+ Args:
+ ttl_total: Total time-to-live in seconds (30-3600, default 300)
+ ttl_without_activity: TTL without activity in seconds (10-3600)
+ stream_web_view: Whether to enable webview streaming
+
+ Returns:
+ BrowserCreateResponse with session id and CDP URL
+ """
+ return await async_browser.browser(
+ self.async_http_client,
+ ttl_total=ttl_total,
+ ttl_without_activity=ttl_without_activity,
+ stream_web_view=stream_web_view,
+ )
+
+ async def browser_execute(
+ self,
+ session_id: str,
+ code: str,
+ *,
+ language: Literal["python", "js"] = "python",
+ ):
+ """Execute code in a browser session.
+
+ Args:
+ session_id: Browser session ID
+ code: Code to execute
+ language: Programming language ("python" or "js")
+
+ Returns:
+ BrowserExecuteResponse with execution result
+ """
+ return await async_browser.browser_execute(
+ self.async_http_client,
+ session_id,
+ code,
+ language=language,
+ )
+
+ async def delete_browser(self, session_id: str):
+ """Delete a browser session.
+
+ Args:
+ session_id: Browser session ID
+
+ Returns:
+ BrowserDeleteResponse
+ """
+ return await async_browser.delete_browser(
+ self.async_http_client, session_id
+ )
+
+ async def list_browsers(
+ self,
+ *,
+ status: Optional[Literal["active", "destroyed"]] = None,
+ ):
+ """List browser sessions.
+
+ Args:
+ status: Filter by session status ("active" or "destroyed")
+
+ Returns:
+ BrowserListResponse with list of sessions
+ """
+ return await async_browser.list_browsers(
+ self.async_http_client,
+ status=status,
+ )
+
# Usage endpoints
async def get_concurrency(self):
from .methods.aio import usage as async_usage # type: ignore[attr-defined]
diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/browser.py b/apps/python-sdk/firecrawl/v2/methods/aio/browser.py
new file mode 100644
index 000000000..26a468087
--- /dev/null
+++ b/apps/python-sdk/firecrawl/v2/methods/aio/browser.py
@@ -0,0 +1,139 @@
+"""
+Async browser session methods for Firecrawl v2 API.
+
+Provides async create, execute, delete, and list operations for browser sessions.
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from ...types import (
+ BrowserCreateResponse,
+ BrowserExecuteResponse,
+ BrowserDeleteResponse,
+ BrowserListResponse,
+)
+from ...utils.http_client_async import AsyncHttpClient
+
+
+def _normalize_browser_create_response(payload: Dict[str, Any]) -> Dict[str, Any]:
+ out = dict(payload)
+ if "cdpUrl" in out and "cdp_url" not in out:
+ out["cdp_url"] = out["cdpUrl"]
+ return out
+
+
+def _normalize_browser_list_response(payload: Dict[str, Any]) -> Dict[str, Any]:
+ out = dict(payload)
+ if "sessions" in out and isinstance(out["sessions"], list):
+ normalized_sessions = []
+ for s in out["sessions"]:
+ ns = dict(s)
+ if "cdpUrl" in ns and "cdp_url" not in ns:
+ ns["cdp_url"] = ns["cdpUrl"]
+ if "streamWebView" in ns and "stream_web_view" not in ns:
+ ns["stream_web_view"] = ns["streamWebView"]
+ if "createdAt" in ns and "created_at" not in ns:
+ ns["created_at"] = ns["createdAt"]
+ if "lastActivity" in ns and "last_activity" not in ns:
+ ns["last_activity"] = ns["lastActivity"]
+ normalized_sessions.append(ns)
+ out["sessions"] = normalized_sessions
+ return out
+
+
+async def browser(
+ client: AsyncHttpClient,
+ *,
+ ttl_total: Optional[int] = None,
+ ttl_without_activity: Optional[int] = None,
+ stream_web_view: Optional[bool] = None,
+) -> BrowserCreateResponse:
+ """Create a new browser session.
+
+ Args:
+ client: Async HTTP client instance
+ ttl_total: Total time-to-live in seconds (30-3600, default 300)
+ ttl_without_activity: TTL without activity in seconds (10-3600)
+ stream_web_view: Whether to enable webview streaming
+
+ Returns:
+ BrowserCreateResponse with session id and CDP URL
+ """
+ body: Dict[str, Any] = {}
+ if ttl_total is not None:
+ body["ttlTotal"] = ttl_total
+ if ttl_without_activity is not None:
+ body["ttlWithoutActivity"] = ttl_without_activity
+ if stream_web_view is not None:
+ body["streamWebView"] = stream_web_view
+
+ resp = await client.post("/v2/browser", body)
+ payload = _normalize_browser_create_response(resp.json())
+ return BrowserCreateResponse(**payload)
+
+
+async def browser_execute(
+ client: AsyncHttpClient,
+ session_id: str,
+ code: str,
+ *,
+ language: Literal["python", "js"] = "python",
+) -> BrowserExecuteResponse:
+ """Execute code in a browser session.
+
+ Args:
+ client: Async HTTP client instance
+ session_id: Browser session ID
+ code: Code to execute
+ language: Programming language ("python" or "js")
+
+ Returns:
+ BrowserExecuteResponse with execution result
+ """
+ body: Dict[str, Any] = {
+ "code": code,
+ "language": language,
+ }
+
+ resp = await client.post(f"/v2/browser/{session_id}/execute", body)
+ return BrowserExecuteResponse(**resp.json())
+
+
+async def delete_browser(
+ client: AsyncHttpClient,
+ session_id: str,
+) -> BrowserDeleteResponse:
+ """Delete a browser session.
+
+ Args:
+ client: Async HTTP client instance
+ session_id: Browser session ID
+
+ Returns:
+ BrowserDeleteResponse
+ """
+ resp = await client.delete(f"/v2/browser/{session_id}")
+ return BrowserDeleteResponse(**resp.json())
+
+
+async def list_browsers(
+ client: AsyncHttpClient,
+ *,
+ status: Optional[Literal["active", "destroyed"]] = None,
+) -> BrowserListResponse:
+ """List browser sessions.
+
+ Args:
+ client: Async HTTP client instance
+ status: Filter by session status ("active" or "destroyed")
+
+ Returns:
+ BrowserListResponse with list of sessions
+ """
+ endpoint = "/v2/browser"
+ if status is not None:
+ endpoint = f"{endpoint}?status={status}"
+
+ resp = await client.get(endpoint)
+ payload = _normalize_browser_list_response(resp.json())
+ return BrowserListResponse(**payload)
diff --git a/apps/python-sdk/firecrawl/v2/methods/browser.py b/apps/python-sdk/firecrawl/v2/methods/browser.py
new file mode 100644
index 000000000..f76b85f81
--- /dev/null
+++ b/apps/python-sdk/firecrawl/v2/methods/browser.py
@@ -0,0 +1,148 @@
+"""
+Browser session methods for Firecrawl v2 API.
+
+Provides create, execute, delete, and list operations for browser sessions.
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from ..types import (
+ BrowserCreateResponse,
+ BrowserExecuteResponse,
+ BrowserDeleteResponse,
+ BrowserListResponse,
+)
+from ..utils.http_client import HttpClient
+from ..utils.error_handler import handle_response_error
+
+
+def _normalize_browser_create_response(payload: Dict[str, Any]) -> Dict[str, Any]:
+ out = dict(payload)
+ if "cdpUrl" in out and "cdp_url" not in out:
+ out["cdp_url"] = out["cdpUrl"]
+ return out
+
+
+def _normalize_browser_list_response(payload: Dict[str, Any]) -> Dict[str, Any]:
+ out = dict(payload)
+ if "sessions" in out and isinstance(out["sessions"], list):
+ normalized_sessions = []
+ for s in out["sessions"]:
+ ns = dict(s)
+ if "cdpUrl" in ns and "cdp_url" not in ns:
+ ns["cdp_url"] = ns["cdpUrl"]
+ if "streamWebView" in ns and "stream_web_view" not in ns:
+ ns["stream_web_view"] = ns["streamWebView"]
+ if "createdAt" in ns and "created_at" not in ns:
+ ns["created_at"] = ns["createdAt"]
+ if "lastActivity" in ns and "last_activity" not in ns:
+ ns["last_activity"] = ns["lastActivity"]
+ normalized_sessions.append(ns)
+ out["sessions"] = normalized_sessions
+ return out
+
+
+def browser(
+ client: HttpClient,
+ *,
+ ttl_total: Optional[int] = None,
+ ttl_without_activity: Optional[int] = None,
+ stream_web_view: Optional[bool] = None,
+) -> BrowserCreateResponse:
+ """Create a new browser session.
+
+ Args:
+ client: HTTP client instance
+ ttl_total: Total time-to-live in seconds (30-3600, default 300)
+ ttl_without_activity: TTL without activity in seconds (10-3600)
+ stream_web_view: Whether to enable webview streaming
+
+ Returns:
+ BrowserCreateResponse with session id and CDP URL
+ """
+ body: Dict[str, Any] = {}
+ if ttl_total is not None:
+ body["ttlTotal"] = ttl_total
+ if ttl_without_activity is not None:
+ body["ttlWithoutActivity"] = ttl_without_activity
+ if stream_web_view is not None:
+ body["streamWebView"] = stream_web_view
+
+ resp = client.post("/v2/browser", body)
+ if not resp.ok:
+ handle_response_error(resp, "create browser session")
+ payload = _normalize_browser_create_response(resp.json())
+ return BrowserCreateResponse(**payload)
+
+
+def browser_execute(
+ client: HttpClient,
+ session_id: str,
+ code: str,
+ *,
+ language: Literal["python", "js"] = "python",
+) -> BrowserExecuteResponse:
+ """Execute code in a browser session.
+
+ Args:
+ client: HTTP client instance
+ session_id: Browser session ID
+ code: Code to execute
+ language: Programming language ("python" or "js")
+
+ Returns:
+ BrowserExecuteResponse with execution result
+ """
+ body: Dict[str, Any] = {
+ "code": code,
+ "language": language,
+ }
+
+ resp = client.post(f"/v2/browser/{session_id}/execute", body)
+ if not resp.ok:
+ handle_response_error(resp, "execute browser code")
+ return BrowserExecuteResponse(**resp.json())
+
+
+def delete_browser(
+ client: HttpClient,
+ session_id: str,
+) -> BrowserDeleteResponse:
+ """Delete a browser session.
+
+ Args:
+ client: HTTP client instance
+ session_id: Browser session ID
+
+ Returns:
+ BrowserDeleteResponse
+ """
+ resp = client.delete(f"/v2/browser/{session_id}")
+ if not resp.ok:
+ handle_response_error(resp, "delete browser session")
+ return BrowserDeleteResponse(**resp.json())
+
+
+def list_browsers(
+ client: HttpClient,
+ *,
+ status: Optional[Literal["active", "destroyed"]] = None,
+) -> BrowserListResponse:
+ """List browser sessions.
+
+ Args:
+ client: HTTP client instance
+ status: Filter by session status ("active" or "destroyed")
+
+ Returns:
+ BrowserListResponse with list of sessions
+ """
+ endpoint = "/v2/browser"
+ if status is not None:
+ endpoint = f"{endpoint}?status={status}"
+
+ resp = client.get(endpoint)
+ if not resp.ok:
+ handle_response_error(resp, "list browser sessions")
+ payload = _normalize_browser_list_response(resp.json())
+ return BrowserListResponse(**payload)
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 7dd452f7c..fcf34ab66 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -809,6 +809,51 @@ class AgentResponse(BaseModel):
expires_at: Optional[datetime] = None
credits_used: Optional[int] = None
+
+# Browser types
+class BrowserCreateResponse(BaseModel):
+ """Response from creating a browser session."""
+
+ success: bool
+ id: Optional[str] = None
+ cdp_url: Optional[str] = None
+ error: Optional[str] = None
+
+
+class BrowserExecuteResponse(BaseModel):
+ """Response from executing code in a browser session."""
+
+ success: bool
+ result: Optional[str] = None
+ error: Optional[str] = None
+
+
+class BrowserDeleteResponse(BaseModel):
+ """Response from deleting a browser session."""
+
+ success: bool
+ error: Optional[str] = None
+
+
+class BrowserSession(BaseModel):
+ """Information about a browser session."""
+
+ id: str
+ status: str
+ cdp_url: str
+ stream_web_view: bool
+ created_at: str
+ last_activity: str
+
+
+class BrowserListResponse(BaseModel):
+ """Response from listing browser sessions."""
+
+ success: bool
+ sessions: Optional[List["BrowserSession"]] = None
+ error: Optional[str] = None
+
+
# Usage/limits types
class ConcurrencyCheck(BaseModel):
"""Current concurrency and limits for the team/API key."""