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:
- Poll the task status at regular intervals
- Provide status updates through the
onStatusChange
callback
- Automatically handle completion and error states
- Return the final result when the task completes
- 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
- Task Description: Write clear, specific task descriptions
- Status Monitoring: Regularly check task status for long-running tasks
- Error Handling: Always handle errors and edge cases
- Resource Management: Stop unused tasks to free up resources
- Pagination: Use pagination for listing tasks and runs to manage large datasets