​
Creating Tasks

Create a new task using the createTask method:

const result = await browserable.createTask({
  task: 'find the top trending GitHub repos of the day.',
  agent: 'BROWSER_AGENT' // Optional
});

if (result.success && result.data) {
  const taskId = result.data.taskId;
  console.log('Task created:', taskId);
}

​
Task Options

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

​
Listing Tasks

Get a list of all your tasks with pagination support:

const result = await browserable.listTasks({
  page: 1,
  limit: 10
});

if (result.success && result.data) {
  console.log('Total tasks:', result.total);
  console.log('Tasks:', result.data);
}

​
Managing Task Runs

​
List Task Runs

Get all runs for a specific task:

const runs = await browserable.listTaskRuns(taskId, {
  page: 1,
  limit: 10
});

​
Check Run Status

Monitor the status of a task run:

const status = await browserable.getTaskRunStatus(taskId, runId);

if (status.success && status.data) {
  console.log('Run status:', status.data.status);
  console.log('Detailed status:', status.data.detailedStatus);
  
  if (status.data.toolCall) {
    console.log('Waiting for input:', status.data.toolCall);
  }
}

​
Get Run Results

Retrieve the results of a completed run:

const results = await browserable.getTaskRunResult(taskId, runId);

if (results.success && results.data) {
  console.log('Output:', results.data.output);
  console.log('Data table:', results.data.dataTable);
}

​
Wait for Run Completion

Wait for a task run to complete while monitoring its status:

try {
  const result = await browserable.waitForRun(taskId, runId, {
    // Optional: customize polling interval (default: 1000ms)
    pollInterval: 2000,
    // Optional: customize timeout (default: 5 minutes)
    timeout: 300000,
    // Optional: handle status updates
    onStatusChange: (status) => {
      console.log(`Task status: ${status.status}`);
      
      // Handle live status updates
      if (status.liveStatus) {
        console.log('Live status:', status.liveStatus);
      }
      
      // Handle input wait states
      if (status.toolCall) {
        console.log('Waiting for input:', status.toolCall);
      }
    }
  });

  if (result.success && result.data) {
    console.log('Task completed!');
    console.log('Output:', result.data.output);
    console.log('Data table:', result.data.dataTable);
  }
} catch (error) {
  if (error.message.includes('Timeout')) {
    console.error('Task timed out');
  } else {
    console.error('Error while waiting for task:', error);
  }
}

This method combines status monitoring and result retrieval into a single convenient call. It will:

  1. Poll the task status at regular intervals
  2. Provide status updates through the onStatusChange callback
  3. Automatically handle completion and error states
  4. Return the final result when the task completes
  5. Throw an error if the task times out or fails

​
Get Run GIF

Get the GIF recording of a task run. The GIF is automatically generated from browser screenshots taken during task execution:

const gifResult = await browserable.getTaskRunGifStatus(taskId, runId);

if (gifResult.success && gifResult.data) {
  switch (gifResult.data.status) {
    case 'completed':
      console.log('GIF URL:', gifResult.data.url);
      break;
    case 'pending':
      console.log('GIF is still being generated');
      break;
    case 'error':
      console.error('GIF generation failed:', gifResult.data.error);
      break;
  }
}

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

​
Stopping Tasks

​
Stop a Task Run

Stop a specific run of a task:

const result = await browserable.stopTaskRun(taskId, runId);

if (result.success) {
  console.log('Run stopped successfully');
}

​
Stop a Task

Stop a task from running future executions:

const result = await browserable.stopTask(taskId);

if (result.success) {
  console.log('Task stopped successfully');
}

​
Error Handling

All methods return an ApiResponse object with the following structure:

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

Example error handling:

try {
  const result = await browserable.createTask({
    task: 'find the top trending GitHub repos of the day.'
  });

  if (!result.success) {
    console.error('Failed to create task:', result.error);
    return;
  }

  // Process successful result
  const taskId = result.data.taskId;
} catch (error) {
  console.error('An error occurred:', error);
}

​
Best Practices

  1. Task Description: Write clear, specific task descriptions
  2. Status Monitoring: Regularly check task status for long-running tasks
  3. Error Handling: Always handle errors and edge cases
  4. Resource Management: Stop unused tasks to free up resources
  5. Pagination: Use pagination for listing tasks and runs to manage large datasets