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

# API Reference

> Complete API reference for the Browserable JavaScript SDK

## Class: Browserable

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

### Constructor

```typescript theme={null}
constructor(config: BrowserableConfig)
```

#### Parameters

```typescript theme={null}
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.

```typescript theme={null}
async createTask(options: CreateTaskOptions): Promise<ApiResponse<{ taskId: string }>>
```

#### Parameters

```typescript theme={null}
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.

```typescript theme={null}
async listTasks(options?: PaginationOptions): Promise<ApiResponse<Task[]>>
```

#### Parameters

```typescript theme={null}
interface PaginationOptions {
  page?: number;
  limit?: number;
}

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

### listTaskRuns

List all runs for a specific task.

```typescript theme={null}
async listTaskRuns(taskId: string, options?: PaginationOptions): Promise<ApiResponse<TaskRun[]>>
```

#### Parameters

```typescript theme={null}
interface TaskRun {
  id: string;
  created_at: string;
}
```

### getTaskRunStatus

Get the status of a specific task run.

```typescript theme={null}
async getTaskRunStatus(taskId: string, runId?: string): Promise<ApiResponse<TaskRunStatus>>
```

#### Response Type

```typescript theme={null}
interface TaskRunStatus {
  status: 'scheduled' | 'running' | 'completed' | 'error';
  detailedStatus?: string;
  toolCall?: any;
  liveStatus?: any;
}
```

### getTaskRunResult

Get the results of a specific task run.

```typescript theme={null}
async getTaskRunResult(taskId: string, runId?: string): Promise<ApiResponse<TaskRunResult>>
```

#### Response Type

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

### stopTaskRun

Stop a running task execution.

```typescript theme={null}
async stopTaskRun(taskId: string, runId?: string): Promise<ApiResponse<void>>
```

### stopTask

Stop a task from running future executions.

```typescript theme={null}
async stopTask(taskId: string): Promise<ApiResponse<void>>
```

### waitForRun

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

```typescript theme={null}
async waitForRun(
  taskId: string,
  runId?: string,
  options?: WaitForRunOptions
): Promise<ApiResponse<TaskRunResult>>
```

#### Parameters

```typescript theme={null}
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.

```typescript theme={null}
async getTaskRunGifStatus(taskId: string, runId?: string): Promise<ApiResponse<TaskRunGifResult>>
```

#### Parameters

```typescript theme={null}
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.

```typescript theme={null}
async check(): Promise<ApiResponse<'ok'>>
```

## Common Types

### ApiResponse

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

```typescript theme={null}
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:

```typescript theme={null}
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.