browser-use-sdk

Official TypeScript SDK for the Browser Use API -- run AI-powered browser agents in the cloud.

Installation

npm install browser-use-sdk
# or
pnpm add browser-use-sdk
# or
yarn add browser-use-sdk
# or
bun add browser-use-sdk

Quick Start (v2)

The default import exposes the v2 API client.

import { BrowserUse } from "browser-use-sdk";

const client = new BrowserUse();

const result = await client.run("Find the top post on Hacker News");
console.log(result.output);
console.log(result.id, result.status);

V3 (Experimental)

The v3 API uses a unified session model. Import from browser-use-sdk/v3:

import { BrowserUse } from "browser-use-sdk/v3";

const client = new BrowserUse();

const output = await client.run("Find the top post on HN");
console.log(output);

Client Options

const client = new BrowserUse({
  apiKey: "bu_...",           // Or set BROWSER_USE_API_KEY env var
  baseUrl: "https://...",     // Override API base URL
  maxRetries: 3,              // Retry on 429 (default: 3)
  timeout: 30_000,            // Request timeout in ms (default: 30s)
});

Structured Output

Pass a Zod schema to get typed results:

import { z } from "zod";

const Product = z.object({ name: z.string(), price: z.number() });

const result = await client.run("Find the price of the MacBook Air", { schema: Product });
console.log(`${result.output.name}: $${result.output.price}`);

Polling and Streaming

client.run() returns a dual-purpose handle: await it for the output, or for await...of it for step-by-step progress.

Wait for Result

const result = await client.run("Search for AI news");
console.log(result.output, result.id, result.status);

Stream Steps

for await (const step of client.run("Search for AI news")) {
  console.log(`[${step.number}] ${step.nextGoal} — ${step.url}`);
}

V2 API Reference

Billing

| Method | Description | |-----------------------|--------------------------------------| | billing.account() | Get account info and credit balance |

Tasks

| Method | Description | |------------------------------|-----------------------------------------| | tasks.create(body) | Create and start a new task | | tasks.list(params?) | List tasks with optional filtering | | tasks.get(taskId) | Get detailed task information | | tasks.stop(taskId) | Stop a running task | | tasks.status(taskId) | Lightweight status for polling | | tasks.wait(taskId, opts?) | Poll until terminal, return TaskView | | tasks.logs(taskId) | Get download URL for task logs |

Sessions

| Method | Description | |------------------------------------|--------------------------------------| | sessions.create(body?) | Create a new session | | sessions.list(params?) | List sessions | | sessions.get(sessionId) | Get session details | | sessions.stop(sessionId) | Stop session and running tasks | | sessions.delete(sessionId) | Delete session and all tasks | | sessions.getShare(sessionId) | Get public share info | | sessions.createShare(sessionId) | Create public share link | | sessions.deleteShare(sessionId) | Remove public share |

Files

| Method | Description | |-----------------------------------------|----------------------------------------| | files.sessionUrl(sessionId, body) | Presigned URL for session file upload | | files.browserUrl(sessionId, body) | Presigned URL for browser file upload | | files.taskOutput(taskId, fileId) | Download URL for task output file |

Profiles

| Method | Description | |-----------------------------------|------------------------------| | profiles.create(body?) | Create a browser profile | | profiles.list(params?) | List profiles | | profiles.get(profileId) | Get profile details | | profiles.update(profileId, body) | Update a profile | | profiles.delete(profileId) | Delete a profile |

Browsers

| Method | Description | |-------------------------------|------------------------------------| | browsers.create(body) | Create a browser session | | browsers.list(params?) | List browser sessions | | browsers.get(sessionId) | Get browser session details | | browsers.stop(sessionId) | Stop a browser session |

Skills

| Method | Description | |------------------------------------------------|--------------------------------------| | skills.create(body) | Create a skill via generation | | skills.list(params?) | List skills | | skills.get(skillId) | Get skill details | | skills.delete(skillId) | Delete a skill | | skills.update(skillId, body) | Update skill metadata | | skills.cancel(skillId) | Cancel in-progress generation | | skills.execute(skillId, body) | Execute a skill | | skills.refine(skillId, body) | Refine a skill with feedback | | skills.rollback(skillId) | Rollback to previous version | | skills.executions(skillId, params?) | List skill executions | | skills.executionOutput(skillId, executionId) | Download execution output |

Marketplace

| Method | Description | |-------------------------------------|-------------------------------------| | marketplace.list(params?) | List public marketplace skills | | marketplace.get(skillSlug) | Get marketplace skill by slug | | marketplace.clone(skillId) | Clone a marketplace skill | | marketplace.execute(skillId, body) | Execute a marketplace skill |

V3 API Reference

Sessions

| Method | Description | |--------------------------------------|--------------------------------------| | sessions.create(body) | Create session and run a task | | sessions.list(params?) | List sessions | | sessions.get(sessionId) | Get session details | | sessions.stop(sessionId) | Stop a session | | sessions.files(sessionId, params?) | List files in session workspace |

Error Handling

All API errors throw BrowserUseError:

import { BrowserUse, BrowserUseError } from "browser-use-sdk";

try {
  await client.tasks.get("nonexistent-id");
} catch (err) {
  if (err instanceof BrowserUseError) {
    console.error(err.statusCode); // 404
    console.error(err.message);    // "Task not found"
    console.error(err.detail);     // Raw error body
  }
}

The client automatically retries on 429 (rate limit) with exponential backoff.

TypeScript

Types are re-exported from browser-use-sdk and browser-use-sdk/v3. The SDK ships with full type definitions for all request/response shapes.

import type { TaskView, CreateTaskRequest } from "browser-use-sdk";

License

MIT