API Documentation (v1)

API docs by Redocly

API Documentation (v1)

Download OpenAPI specification:Download

This version (v1) is an older API version that will be deprecated soon. To see the documentation for the most recent version (v2), click here.

Tasks

A task is an automation that can do almost anything you do manually on the web. For example:

  • Open a webpage,
  • Log in,
  • Click on buttons,
  • Fill out forms,
  • Extract structured data from a webpage into a spreadsheet,
  • Take screenshots,
  • Monitor specific parts of webpages for visual or content changes.

Tasks are created either using 1-Click Automations or using Browse AI Recorder and its click-and-extract interface. Every task has a few variables (like the webpage address) that you can adjust every time you run it.

Retrieve list of tasks under your account

If you have already created a few tasks on your dashboard, you can use this endpoint to retrieve a list of them.

You can then use other endpoints to retrieve more information about your tasks or run tasks.

path Parameters
teamId
required
string

Team ID.

Even single-user personal accounts have a team ID. Feel free to ask us if you do not know your ID.

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v1/teams/{teamId}/tasks/");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_SECRET_API_KEY");
IRestResponse response = client.Execute(request);

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "messageCode": "success",
  • "tasks": {}
}

Task Execution

Every time Browse AI runs a task for you, it counts as one execution. For example, if you set up a monitoring task to monitor a webpage for changes daily, Browse AI will have to execute the task every day or about 30 times per month for you.

Note: Task executions used to be called jobs. The word job is still used in some API endpoints and parameters for backwards-compatibility.

Run a task

Run a task on-demand with custom variable inputs.

When you need to run a task and get its captured data, you can use this endpoint to run the task, and then use webhooks to receive the captured data as soon as the execution is finished. Alternatively, you can poll the GET endpoint to retrieve an execution's details as soon as it is finished.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

query Parameters
waitForJob
boolean
Deprecated
Default: false

Set this to false if you want to receive the execution ID and other details immediately, as soon as the task starts running.

Set it to true if you want to wait for the running task to finish and then receive a response containing captured data. Please note that if the execution lasts longer than 20 seconds, this endpoint will respond with the pending execution's details. In that case, you will need to poll the GET endpoint or use webhooks to retrieve the captured data once execution is finished.

This option has been fully deprecated. Its value is always assumed false. You should use webhooks or polling to retrieve a task execution's results.

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v1/tasks/{taskId}/jobs?waitForJob=false");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer YOUR_SECRET_API_KEY");
request.AddParameter("undefined", "{\"variables\":{\"originUrl\":\"https://www.espressozone.com/espresso-machines/semi-automatic-espresso-machines\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Response samples

Content type
application/json
{}

Retrieve a task execution

Retrieve a task execution's details and captured data.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

jobId
required
string

Unique execution ID

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v1/tasks/{taskId}/jobs/{jobId}");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_SECRET_API_KEY");
IRestResponse response = client.Execute(request);

Response samples

Content type
application/json
{}

Monitors

Each task on Browse AI can optionally have one or more monitors. Monitoring tasks come with one monitor by default.

For example, if you set up a monitoring task to monitor a category page on an e-commerce site for changes daily, you can set up additional monitors to monitor other category pages on the same site using the same task.

Each monitor can have different variables and schedule.

Retrieve a task's monitors

Retrieve a task's monitors list.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v1/tasks/{taskId}/monitors");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_SECRET_API_KEY");
IRestResponse response = client.Execute(request);

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "messageCode": "success",
  • "monitors": [
    ]
}

Create a new monitor on a task

Create a new monitor on a task.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters

Monitor name

variables
object

An object of variable values to override default variables.

Array of Fixed interval schedule (object) or null (Schedules)

Array of schedules.

notifyOnCapturedScreenshotChange
boolean

If set to true, an email notification will be sent to you when a change is detected in captured screenshots.

notifyOnCapturedTextChange
boolean

If set to true, an email notification will be sent to you when a change is detected in captured texts.

capturedScreenshotNotificationThreshold
number

The "screenshot changed" email notification will be sent to you if the change is greater than this threshold (in percent).

Responses

Request samples

Content type
application/json
{
  • "name": "Monitor Products",
  • "variables": {
    },
  • "schedules": [
    ],
  • "notifyOnCapturedScreenshotChange": true,
  • "notifyOnCapturedTextChange": true,
  • "capturedScreenshotNotificationThreshold": 15
}

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "messageCode": "success",
  • "monitor": {
    }
}

Retrieve a task's monitor

Retrieve a task's monitor.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

monitorId
required
string

Unique monitor ID

You can find a monitor's ID by opening it on the dashboard and copying its ID in the browser address bar.

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v1/tasks/{taskId}/monitors/{monitorId}");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_SECRET_API_KEY");
IRestResponse response = client.Execute(request);

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "messageCode": "success",
  • "monitor": {
    }
}

Update a task monitor

Update a task monitor

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

monitorId
required
string

Unique monitor ID

You can find a monitor's ID by opening it on the dashboard and copying its ID in the browser address bar.

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Request Body schema: application/json
required
name
string or null

Monitor name

variables
object or null

An object of variable values to override default variables.

Array of Fixed interval schedule (object) or null (Schedules)

Array of schedules.

notifyOnCapturedScreenshotChange
boolean or null

If set to true, an email notification will be sent to you when a change is detected in captured screenshots.

notifyOnCapturedTextChange
boolean or null

If set to true, an email notification will be sent to you when a change is detected in captured texts.

capturedScreenshotNotificationThreshold
number or null

The "screenshot changed" email notification will be sent to you if the change is greater than this threshold (in percent).

Responses

Request samples

Content type
application/json
{
  • "name": "Monitor Products",
  • "variables": {
    },
  • "schedules": [
    ],
  • "notifyOnCapturedScreenshotChange": true,
  • "notifyOnCapturedTextChange": true,
  • "capturedScreenshotNotificationThreshold": 15
}

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "messageCode": "success",
  • "monitor": {
    }
}

Delete a task's monitor

Delete a task's monitor.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

monitorId
required
string

Unique monitor ID

You can find a monitor's ID by opening it on the dashboard and copying its ID in the browser address bar.

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v1/tasks/{taskId}/monitors/{monitorId}");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer YOUR_SECRET_API_KEY");
IRestResponse response = client.Execute(request);

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "messageCode": "success",
  • "monitor": {
    }
}

Bulk Runs

You can run a task up to 1,000 times at once with different variables for each run.

Bulk run a task

Create a new bulk run on a task.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Request Body schema: application/json
required
title
string [ 1 .. 200 ] characters

A string that describes the bulk run.

variables
Array of objects

An array of variables to override the task's default variables.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "messageCode": "success",
  • "result": {
    }
}

Retrieve a task's bulk runs list

Retrieve a task's bulk runs list.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

query Parameters
page
integer >= 1

Page number

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v1/tasks/{taskId}/bulk-runs?page=1");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_SECRET_API_KEY");
IRestResponse response = client.Execute(request);

Response samples

Content type
application/json
{
  • "statusCode": 200,
  • "messageCode": "success",
  • "result": {
    }
}

Retrieve a task's bulk run

Retrieve a task's bulk run along with a list of task executions triggered through the bulk run.

path Parameters
taskId
required
string

Unique task ID

You can find a task's ID by opening it on the dashboard and copying its ID in the browser address bar.

bulkRunId
required
string

Unique bulk run ID

query Parameters
page
integer >= 1

Page number

header Parameters
authorization
required
string
Example: Bearer YOUR_SECRET_API_KEY

You can generate a new API key on your dashboard if you do not have one.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v1/tasks/{taskId}/bulk-runs/{bulkRunId}?page=1");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer YOUR_SECRET_API_KEY");
IRestResponse response = client.Execute(request);

Response samples

Content type
application/json
{}