API Reference

​

Class: Browserable

The main SDK class that provides access to all Browserable functionality.

​

Constructor

constructor(config: BrowserableConfig)

​

Parameters

interface BrowserableConfig {
  apiKey: string;
  baseURL?: string;
}

• apiKey (required): Your Browserable API key
• baseURL (optional): Override the default API base URL

​

Task Methods

​

createTask

Create a new automated browser task.

async createTask(options: CreateTaskOptions): Promise<ApiResponse<{ taskId: string }>>

​

Parameters

interface CreateTaskOptions {
  task: string;
  agent?: string;
}

• task: Natural language description of what you want to automate
• agent: Agent (defaults to 'BROWSER_AGENT')

​

listTasks

List all tasks for the authenticated user.

async listTasks(options?: PaginationOptions): Promise<ApiResponse<Task[]>>

​

Parameters

interface PaginationOptions {
  page?: number;
  limit?: number;
}

interface Task {
  id: string;
  status: 'active' | 'inactive';
  readable_name: string;
}

​

listTaskRuns

List all runs for a specific task.

async listTaskRuns(taskId: string, options?: PaginationOptions): Promise<ApiResponse<TaskRun[]>>

​

Parameters

interface TaskRun {
  id: string;
  created_at: string;
}

​

getTaskRunStatus

Get the status of a specific task run.

async getTaskRunStatus(taskId: string, runId?: string): Promise<ApiResponse<TaskRunStatus>>

​

Response Type

interface TaskRunStatus {
  status: 'scheduled' | 'running' | 'completed' | 'error';
  detailedStatus?: string;
  toolCall?: any;
  liveStatus?: any;
}

​

getTaskRunResult

Get the results of a specific task run.

async getTaskRunResult(taskId: string, runId?: string): Promise<ApiResponse<TaskRunResult>>

​

Response Type

interface TaskRunResult {
  status: 'scheduled' | 'running' | 'completed' | 'error';
  error?: string;
  output?: any;
  dataTable?: any[];
}

​

stopTaskRun

Stop a running task execution.

async stopTaskRun(taskId: string, runId?: string): Promise<ApiResponse<void>>

​

stopTask

Stop a task from running future executions.

async stopTask(taskId: string): Promise<ApiResponse<void>>

​

waitForRun

Wait for a task run to complete or error out, with status monitoring.

async waitForRun(
  taskId: string,
  runId?: string,
  options?: WaitForRunOptions
): Promise<ApiResponse<TaskRunResult>>

​

Parameters

interface WaitForRunOptions {
  /**
   * Interval in milliseconds between status checks
   * @default 1000
   */
  pollInterval?: number;

  /**
   * Maximum time in milliseconds to wait for completion
   * @default 300000 (5 minutes)
   */
  timeout?: number;

  /**
   * Callback function that will be called on every status change
   */
  onStatusChange?: (status: TaskRunStatus) => void;
}

• taskId (required): The ID of the task to monitor
• runId (optional): The specific run ID to monitor. If not provided, monitors the most recent run
• options (optional): Configuration options for the wait operation
  • pollInterval: Time in milliseconds between status checks (default: 1000ms)
  • timeout: Maximum time to wait in milliseconds (default: 5 minutes)
  • onStatusChange: Callback function for status updates

This method will continuously poll the task status until one of the following occurs:

• The task completes successfully (returns the result)
• The task errors out (returns the error result)
• The timeout is reached (throws an error)
• A network or other error occurs (throws an error)

​

getTaskRunGifStatus

Get the GIF status and URL for a task run. The GIF is automatically generated from the browser screenshots taken during the task execution.

async getTaskRunGifStatus(taskId: string, runId?: string): Promise<ApiResponse<TaskRunGifResult>>

​

Parameters

interface TaskRunGifResult {
  status: 'pending' | 'error' | 'completed';
  url?: string;
  error?: string;
}

• taskId (required): The ID of the task
• runId (optional): The specific run ID to get the GIF for. If not provided, returns the GIF status for the most recent run

The GIF generation is an asynchronous process that starts after a task run completes. The status field indicates:

• pending: GIF is being generated
• completed: GIF is ready and can be accessed via the url field
• error: GIF generation failed, check the error field for details

​

check

Verify if your API key is valid.

async check(): Promise<ApiResponse<'ok'>>

​

Common Types

​

ApiResponse

All methods return a Promise that resolves to an ApiResponse object:

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  total?: number;
  page?: number;
  limit?: number;
}

​

Error Handling

All methods can throw errors in case of network issues or invalid parameters. Always wrap API calls in try-catch blocks:

try {
  const result = await browserable.createTask({
    task: 'find the top trending GitHub repos of the day.'
  });
  // Handle success
} catch (error) {
  // Handle error
  console.error('API error:', error);
}

​

Rate Limits

The SDK respects the API rate limits. When limits are exceeded, the API will return an error response. Implement appropriate retry logic in your application if needed.