Browse AI API Documentation (v2)

API docs by Redocly

Browse AI API Documentation (v2)

Download OpenAPI specification:Download

If you are still using the deprecated API v1 version, you can see its documentation here.

System

This tag is used for endpoints that are used to check the status of Browse AI infrastructure

Endpoint for checking the status of Browse AI infrastructure

This endpoint provides you with real-time information regarding the operational status of the Browse AI infrastructure. It gives insights into the condition of the tasks queue, thus allowing you to understand if the services are running smoothly or are under maintenance.

Responses

Request samples 

var client = new RestClient("https://api.browse.ai/v2/status");
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",
  • "tasksQueueStatus": "OK"
}

Robots

A robot can be trained 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.

Robots are created either by using Prebuilt Robots or using Browse AI Recorder and its click-and-extract interface. Every robot has a few input parameters (like the webpage address) that you can adjust every time you run it.

Retrieve list of robots under your account

If you have already created a few robots 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 robots or run robots.

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/v2/robots");
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",
  • "robots": {}
}

Retrieve single robot by ID

You can use this endpoint to retrieve a single robot by ID.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID You can find a robot'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/v2/robots/{robotId}");
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
{}

Update a robot's cookies

Update a robot's cookies

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

You can find a robot'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
Array
name
required
string

The name of the cookie.

value
required
string

The value of the cookie.

domain
string

The domain associated with the cookie. Specifies the domains to which the cookie should be sent.

expirationDate
number <int64>

The expiration date of the cookie in seconds since the UNIX epoch (e.g., POSIX time). If not provided, the cookie will be treated as a session cookie.

path
string

The URL path to which the cookie should be sent. If not provided, it defaults to the current path of the document location.

secure
boolean

Indicates whether the cookie should only be sent over secure (HTTPS) connections. If true, the cookie will not be sent over unencrypted HTTP connections.

httpOnly
boolean

If true, the cookie is accessible only through the HTTP(S) protocol and cannot be accessed through JavaScript or other client-side scripts.

hostOnly
boolean

If true, the cookie is only sent to the exact domain specified in the "domain" property. If false, the cookie is sent to subdomains as well, provided that the "domain" property allows it.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Tasks

Each robot is trained to perform a certain task. Every time you run that robot, it will perform that task and the details, including the extracted data, will be stored under that task.

If you set up a monitoring robot to monitor a webpage for changes daily, it will have to run a task every day or about 30 tasks per month for you.

Get all tasks by a robot

Get all of a robot's tasks

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

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

query Parameters
page
integer >= 1
Example: page=1

Page number

pageSize
integer [ 1 .. 10 ]
Default: 10
Example: pageSize=10

Page size

status
string
Enum: "failed" "successful" "in-progress"
Example: status=successful

Task status

robotBulkRunId
string
Example: robotBulkRunId=f6fb62b6-f06a-4bf7-a623-c6a35c2e70b0

filter the result based on robot bulk run ID

sort
string
Example: sort=-createdAt,finishedAt

A comma separated list of fields to sort by. Default sorting is ascending and prefixing field names with a hyphen '-' yields a descending order.

includeRetried
boolean
Example: includeRetried=false

by passing false you can exclude the retried tasks

fromDate
integer
Example: fromDate=1678795867879

From task creation date and time in the form of a Unix timestamp

toDate
integer
Example: toDate=1678795867879

To task creation date and time in the form of a Unix timestamp

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/v2/robots/{robotId}/tasks?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
{}

Run a robot

Run a robot on-demand with custom input parameters.

When you need to run a robot 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 task is finished. Alternatively, you can poll the GET endpoint to retrieve a task's details as soon as it is finished.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

You can find a robot'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
optional
recordVideo
boolean [ 1 .. 200 ] characters

Try to record a video while running the task. This is not guaranteed to work as the robot might skip video recording if the site is too heavy.

object (InputParameters)

An object of input parameters to override default input parameters.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Retrieve a task

Retrieve a task's details and captured data.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

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

taskId
required
string
Example: f3672790-4561-424b-8a7b-7b7df182b236

Unique task 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/v2/robots/{robotId}/tasks/{taskId}");
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 robot on Browse AI can optionally have one or more monitors. Monitoring robots come with one monitor by default.

For example, if you set up a monitoring robot 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 robot.

Each monitor can have different input parameters and schedule.

Retrieve a robot's monitors

Retrieve a robot's monitors list.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

You can find a robot'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/v2/robots/{robotId}/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 robot

Create a new monitor on a robot.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

You can find a robot'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
required
string [ 1 .. 200 ] characters

Monitor name

required
object (InputParameters)

An object of input parameters to override default input parameters.

Array of objects (Schedules)
Deprecated

Array of schedules.

schedule
string (Schedule)

recurring schedule.

notifyOnCapturedScreenshotChange
required
boolean

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

notifyOnCapturedTextChange
required
boolean

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

capturedScreenshotNotificationThreshold
required
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",
  • "inputParameters": {},
  • "schedules": [
    ],
  • "schedule": "FREQ=HOURLY;INTERVAL=1;BYWEEKDAY=MO,TU,WE,TH,FR",
  • "notifyOnCapturedScreenshotChange": true,
  • "notifyOnCapturedTextChange": true,
  • "capturedScreenshotNotificationThreshold": 15
}

Response samples

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

Retrieve a robot's monitor

Retrieve a robot's monitor.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

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

monitorId
required
string
Example: e524ab69-4269-4d9d-b3d8-678112a10d29

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/v2/robots/{robotId}/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 robot's monitor

Update a robot's monitor

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

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

monitorId
required
string
Example: e524ab69-4269-4d9d-b3d8-678112a10d29

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

status
string or null
Enum: "active" "paused"

If set to paused, the monitor will stop working until an active status is sent.

object or null (InputParameters)

An object of input parameters to override default input parameters.

Array of objects (Schedules)
Deprecated

Array of schedules.

schedule
string (Schedule)

recurring schedule.

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",
  • "status": "active",
  • "inputParameters": {},
  • "schedules": [
    ],
  • "schedule": "FREQ=HOURLY;INTERVAL=1;BYWEEKDAY=MO,TU,WE,TH,FR",
  • "notifyOnCapturedScreenshotChange": true,
  • "notifyOnCapturedTextChange": true,
  • "capturedScreenshotNotificationThreshold": 15
}

Response samples

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

Delete a robot's monitor

Delete a robot's monitor.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

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

monitorId
required
string
Example: e524ab69-4269-4d9d-b3d8-678112a10d29

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/v2/robots/{robotId}/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"
}

Webhooks

After a robot finishes a task, its webhooks will be called.

Task Finished Webhook

Request Body schema: application/json
event
required
string
Enum: "task.finishedSuccessfully" "task.finishedWithError" "task.capturedDataChanged"

The event type that triggered the webhook

required
object (RobotTaskWebhook)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "success"
}

Table Export Finished (Beta) Webhook

This webhook is called when a table export is finished. The exported file can be a CSV, JSON, or zip file.

Request Body schema: application/json
exportId
required
string

The unique ID of the export

robotId
required
string

The unique ID of the robot

filesTemporaryUrl
Array of strings

The URLs of the exported files

filesTemporaryUrlExpiresAt
number <timestamp>

The unix timestamp of when the file URL expires in milliseconds

exportFinishedAt
required
number <timestamp>

The unix timestamp of when the export was finished in milliseconds

exportCreatedAt
required
number <timestamp>

The unix timestamp of when the export was created in milliseconds

Responses

Request samples

Content type
application/json
{
  • "exportId": "f6fb62b6-f06a-4bf7-a623-c6a35c2e70b0",
  • "robotId": "c3689adb-50aa-44af-b265-a7e0d4e5846e",
  • "filesTemporaryUrl": [],
  • "filesTemporaryUrlExpiresAt": 1678795867879,
  • "exportFinishedAt": 1678795867879,
  • "exportCreatedAt": 1678795867879
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Retrieve a robot's webhooks

Retrieve a robot's webhook list.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

You can find a robot'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/v2/robots/{robotId}/webhooks");
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",
  • "webhooks": {}
}

Create a new webhook on a robot

Create a new webhook on a robot

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

You can find a robot'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
hookUrl
required
string

Webhook URL

eventType
required
string
Enum: "taskCapturedDataChanged" "taskFinished" "taskFinishedSuccessfully" "taskFinishedWithError" "tableExportFinishedSuccessfully"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete a robot's webhook

Delete a robot's webhook.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

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

webhookId
required
string
Example: 6d7f1218-43fb-4735-ac71-21e81b1ab23e

Unique webhookId 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/v2/robots/{robotId}/webhooks/{webhookId}");
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"
}

Bulk Runs

You can run up to 50,000 tasks at once using a robot with different input parameters for each task.

Bulk run tasks

Bulk run up to 50,000 tasks at a time using a robot.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

You can find a robot'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.

required
Array of objects (ArrayOfUserInputParameters)

An array of input parameters to override the task's default input parameters.

Responses

Request samples

Content type
application/json
{}

Response samples

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

Retrieve a robot's bulk runs list

Retrieve a robot's bulk runs list.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

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

query Parameters
page
integer >= 1
Example: page=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/v2/robots/{robotId}/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 robot's bulk run

Retrieve a robot's bulk run along with a list of tasks run within the bulk run.

path Parameters
robotId
required
string
Example: c3689adb-50aa-44af-b265-a7e0d4e5846e

Unique robot ID

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

bulkRunId
required
string
Example: 5aa4df52-25bb-48da-bf38-ce4f2bd98dd5

Unique bulk run ID

query Parameters
page
integer >= 1
Example: page=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/v2/robots/{robotId}/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
{}