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.
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 keybaseURL (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 automateagent: 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 monitorrunId (optional): The specific run ID to monitor. If not provided, monitors the most recent runoptions (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 taskrunId (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 generatedcompleted: GIF is ready and can be accessed via the url fielderror: 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.
