Run a robot - Browse AI

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.

curl --location --request POST 'http://dev-cn.your-api-server.com/robots/c3689adb-50aa-44af-b265-a7e0d4e5846e/tasks' \ --header 'authorization: Bearer YOUR_SECRET_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "recordVideo": false, "inputParameters": { "originUrl": "https://www.ycombinator.com/companies/airbnb", "companies_skip": 0, "companies_limit": 10 } }'

{ "statusCode": 200, "messageCode": "success", "result": { "id": "f6fb62b6-f06a-4bf7-a623-c6a35c2e70b0", "inputParameters": { "originUrl": "https://www.ycombinator.com/companies/airbnb", "companies_skip": 0, "companies_limit": 10 }, "robotId": "4f5cd7ff-6c98-4cac-8cf0-d7d0cb050b06", "status": "failed", "runByUserId": null, "robotBulkRunId": null, "runByTaskMonitorId": null, "runByAPI": true, "createdAt": 1678795867879, "startedAt": 1678795867879, "finishedAt": 1678795867879, "userFriendlyError": null, "triedRecordingVideo": true, "videoUrl": "https://prod-browseai-captured-data.s3.amazonaws.com/1fae674a-2788-46a8-83c8-95c4664c6d25/6326b3c1-7b16-4256-a323-7d8d8954bd4e/1061671f-7f71-42ac-bb9a-207d126d1f3a/system-1620230966-b1a9688b-05d3-4682-beeb-9ce035e482b1.mp4", "videoRemovedAt": 1678795867879, "retriedOriginalTaskId": "673da019-bf0c-476e-9c4f-d35252a151dc", "retriedByTaskId": null, "capturedDataTemporaryUrl": "https://prod-browseai-captured-data.s3.amazonaws.com/1fae674a-2788-46a8-83c8-95c4664c6d25/6326b3c1-7b16-4256-a323-7d8d8954bd4e/1061671f-7f71-42ac-bb9a-207d126d1f3a/system-1620230966-b1a9688b-05d3-4682-beeb-9ce035e482b1.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAQVG3TPBVXHSCAX63%2F20221031%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20221031T185642Z&X-Amz-Expires=1800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEJP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQDfX8VNAl5kBgttrCU85U5wc1ZtSOmshO6%2FPilXOv8nvgIhAIveFfsk%2B2CnEkrMZWriodEPsj0osO5a5zV6eVu%2FXfuZKp8DCHwQAhoMMDQ1NTU3NzA4OTA3IgyrbhVK0MP1WMFBXh0q%2FAJulP5qfaV5mn3NRbINqZN4hy4Dg3IujNrZjw8ef32sWE1Gj2D%2Fc0YTJUzvx%2Fnm7LxyNO6AR35mrVy%2FBm9Q80UIspkcLMl45EK%2FoUDO0fAvoUF8g6iZ905qS3MvnOTxXkObhM1PVmpFeJFMw3jksnOPfKE4X7Ut%2FJXNwD%2F5QzdkQCXkGem%2BlrYSSSf8jB8lihTAjT%2FNXmOKMv3jktmZ13T8J1R8F8zeuLPMQf7QphUzlKn5joPb28cConluQC97y%2BjwxqIYjvIFKXY9cZEoaHGh4c6FbXsia714zG3CQp8NSGLbqCCu93oJI1Z61E%2BZ6PhB3vZGdBvXi61AlJcxZ7sti6i0h4VAbWspiJIgWwoZzrsTtneBNNpUW9tvtacGgEZIwAKV%2F3AhVEZu3WC1eQ9HtfjT9%2FjW99SEB8VVGXwkM%2FA9mtT%2FuiL0cAfQZRMhtbQJXXDRdkYEw%2FWuhjJ3zxEtEB2m3uH%2B%2BUEzOzGTd5Knm%2Bero%2BhMfN8X%2Botm3DDbtICbBjqcAf5Riii0XE1w2TZvpm%2FPNHTchCu7FnNz5hfvflv8scpgO5M4bGpy%2FadI4%2F7AUQqCQXFw4scF0FCCdb8AKJZsFGG18W1jjDHyR0YuxZFQ%2FJQRt0JP3yr%2BkVxjAH7qTtc0AzF%2FnGTgy3MOF%2Bm6Y7EkyCWyV2r6o1JTBQMftlf7MI8Uvw4cSZE6JoZviaFtmKVLGGgR4F3cDiyU56augA%3D%3D&X-Amz-Signature=a7bb4d7597ad37cdf1f260890c3c474f7f49334db58c9650d75302a34126f7bc&X-Amz-SignedHeaders=host", "capturedTexts": { "Product Name": "Alexis", "Width": "15", "Pattern Repeat": "PATTERN REPEAT", "Construction": "Hand woven", "Fiber": "100% Wool", "Color": null, "Main Image": "https://isteam.wsimg.com/ip/e31f7bba-252b-4669-9209-639d1c00765d/ols/258_original" }, "capturedScreenshots": { "top-ads": { "id": "b4d132f3-12d9-4770-ac7d-88e481fc5b47", "name": "Top ads", "src": "https://prod-browseai-captured-data.s3.amazonaws.com/1fae674a-2788-46a8-83c8-95c4664c6d25/6326b3c1-7b16-4256-a323-7d8d8954bd4e/1061671f-7f71-42ac-bb9a-207d126d1f3a/00001-user-1620230947-6f113cf2-90ef-4c66-a448-9d5c6bd64873.png", "width": 600, "height": 120, "x": 201, "y": 142, "deviceScaleFactor": 1.2, "full": "page", "comparedToScreenshotId": "29d742c2-6f45-4f29-9d48-ba6fe66e6e3d", "diffImageSrc": "https://prod-browseai-captured-data.s3.amazonaws.com/1fae674a-2788-46a8-83c8-95c4664c6d25/6326b3c1-7b16-4256-a323-7d8d8954bd4e/1061671f-7f71-42ac-bb9a-207d126d1f3a/00001-user-1620230947-6f113cf2-90ef-4c66-a448-9d5c6bd64873.png", "changePercentage": 20, "diffThreshold": 5, "fileRemovedAt": 1678795867879 } }, "capturedLists": { "companies": [ { "Position": "1", "name": "Airbnb", "location": "San Francisco, CA, USA", "description": "Book accommodations around the world." }, { "Position": "2", "name": "Coin base", "location": "San Francisco, CA, USA", "description": "Buy, sell, and manage crypto currencies." }, { "Position": "3", "name": "DoorDash", "location": "San Francisco, CA, USA", "description": "Restaurant delivery." } ] } } }

请求参数

Path 参数

robotId

string

必需

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.

示例值:

c3689adb-50aa-44af-b265-a7e0d4e5846e

Header 参数

authorization

string

必需

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

示例值:

Bearer YOUR_SECRET_API_KEY

Body 参数application/json

recordVideo

boolean

可选

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.

示例值:

false

inputParameters

object (InputParameters)

可选

An object of input parameters to override default input parameters.

示例值:

{"originUrl":"https://www.ycombinator.com/companies/airbnb","companies_skip":0,"companies_limit":10}

额外字段

可选

示例

返回响应

🟢200A JSON including robots list.

application/json

Body

statusCode

enum<number>

必需

枚举值:

200

messageCode

enum<string>

必需

枚举值:

success

result

object (RobotTask)

必需

string

必需

Unique task ID

示例值:

f6fb62b6-f06a-4bf7-a623-c6a35c2e70b0

inputParameters

object (InputParameters)

必需

An object of input parameters to override default input parameters.

示例值:

{"originUrl":"https://www.ycombinator.com/companies/airbnb","companies_skip":0,"companies_limit":10}

robotId

string

必需

Unique robot ID

示例值:

4f5cd7ff-6c98-4cac-8cf0-d7d0cb050b06

status

enum<string>

可选

task status

枚举值:

failedsuccessfulin-progress

示例值:

successful

runByUserId

string | null

可选

User ID who ran the robot on the dashboard

示例值:

null

robotBulkRunId

string | null

可选

Robot bulk run ID associated with this task

示例值:

null

runByTaskMonitorId

string | null

可选

Monitor ID that ran this check

示例值:

null

runByAPI

boolean

必需

Whether the robot was ran through the API

示例值:

true

createdAt

integer

必需

Task creation date and time in the form of a Unix timestamp

示例值:

1678795867879

startedAt

integer | null

可选

Task start date and time in the form of a Unix timestamp

示例值:

1678795867879

finishedAt

integer | null

可选

Task finish date and time in the form of a Unix timestamp.

If null, it means robot is still running and capturing data.

Tasks time out with an error if they are not finished within 15 minutes (or the maximum duration allowed on your plan).

示例值:

1678795867879

userFriendlyError

string | null

可选

If task fails, a user-friendly error will be provided here.

示例值:

null

triedRecordingVideo

boolean

必需

Whether the robot tried to record a video while performing this task.

You can change a robot's video recording setting on its Settings page.

Robots try to record a video when a task is failed and auto-retried as well.

示例值:

true

videoUrl

string | null

可选

If a video was recorded for this task, this is the link to the video.

示例值:

videoRemovedAt

integer | null

可选

After your account's data retention period, task videos get removed and this field will be video removal date and time in the form of a Unix timestamp.

示例值:

1678795867879

retriedOriginalTaskId

string | null

可选

The ID of the original failed task this task was retrying. For example, if task A failed and was retried by task B, and task B was retried by task C, retriedOriginalTaskId will point to task A in both task B and C.

示例值:

673da019-bf0c-476e-9c4f-d35252a151dc

retriedByTaskId

string | null

可选

The ID of the task that retried this task, if this task failed with an error and was retried.

Failed tasks get retried if "Double Check" option is enabled on robot Settings page. "Double Check" is enabled by default.

示例值:

null

capturedDataTemporaryUrl

string | null

可选

If your task's captured data exceeds 100KB, the data will be only accessible through this link. There's a 24 hours expiration time for this link (you need to call this API again to get a new link if it expires).

示例值:

https://prod-browseai-captured-data.s3.amazonaws.com/1fae674a-2788-46a8-83c8-95c4664c6d25/6326b3c1-7b16-4256-a323-7d8d8954bd4e/1061671f-7f71-42ac-bb9a-207d126d1f3a/system-1620230966-b1a9688b-05d3-4682-beeb-9ce035e482b1.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAQVG3TPBVXHSCAX63%2F20221031%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20221031T185642Z&X-Amz-Expires=1800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEJP%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQDfX8VNAl5kBgttrCU85U5wc1ZtSOmshO6%2FPilXOv8nvgIhAIveFfsk%2B2CnEkrMZWriodEPsj0osO5a5zV6eVu%2FXfuZKp8DCHwQAhoMMDQ1NTU3NzA4OTA3IgyrbhVK0MP1WMFBXh0q%2FAJulP5qfaV5mn3NRbINqZN4hy4Dg3IujNrZjw8ef32sWE1Gj2D%2Fc0YTJUzvx%2Fnm7LxyNO6AR35mrVy%2FBm9Q80UIspkcLMl45EK%2FoUDO0fAvoUF8g6iZ905qS3MvnOTxXkObhM1PVmpFeJFMw3jksnOPfKE4X7Ut%2FJXNwD%2F5QzdkQCXkGem%2BlrYSSSf8jB8lihTAjT%2FNXmOKMv3jktmZ13T8J1R8F8zeuLPMQf7QphUzlKn5joPb28cConluQC97y%2BjwxqIYjvIFKXY9cZEoaHGh4c6FbXsia714zG3CQp8NSGLbqCCu93oJI1Z61E%2BZ6PhB3vZGdBvXi61AlJcxZ7sti6i0h4VAbWspiJIgWwoZzrsTtneBNNpUW9tvtacGgEZIwAKV%2F3AhVEZu3WC1eQ9HtfjT9%2FjW99SEB8VVGXwkM%2FA9mtT%2FuiL0cAfQZRMhtbQJXXDRdkYEw%2FWuhjJ3zxEtEB2m3uH%2B%2BUEzOzGTd5Knm%2Bero%2BhMfN8X%2Botm3DDbtICbBjqcAf5Riii0XE1w2TZvpm%2FPNHTchCu7FnNz5hfvflv8scpgO5M4bGpy%2FadI4%2F7AUQqCQXFw4scF0FCCdb8AKJZsFGG18W1jjDHyR0YuxZFQ%2FJQRt0JP3yr%2BkVxjAH7qTtc0AzF%2FnGTgy3MOF%2Bm6Y7EkyCWyV2r6o1JTBQMftlf7MI8Uvw4cSZE6JoZviaFtmKVLGGgR4F3cDiyU56augA%3D%3D&X-Amz-Signature=a7bb4d7597ad37cdf1f260890c3c474f7f49334db58c9650d75302a34126f7bc&X-Amz-SignedHeaders=host

capturedTexts

object (CapturedTexts)

必需

Captured texts

示例值:

{"Product Name":"Alexis","Width":"15","Pattern Repeat":"PATTERN REPEAT","Construction":"Hand woven","Fiber":"100% Wool","Color":null,"Main Image":"https://isteam.wsimg.com/ip/e31f7bba-252b-4669-9209-639d1c00765d/ols/258_original"}

capturedScreenshots

object (CapturedScreenshots)

必需

All screenshots captured in this task.

示例值:

{"top-ads":{"id":"b4d132f3-12d9-4770-ac7d-88e481fc5b47","name":"Top ads","src":"https://prod-browseai-captured-data.s3.amazonaws.com/1fae674a-2788-46a8-83c8-95c4664c6d25/6326b3c1-7b16-4256-a323-7d8d8954bd4e/1061671f-7f71-42ac-bb9a-207d126d1f3a/00001-user-1620230947-6f113cf2-90ef-4c66-a448-9d5c6bd64873.png","width":600,"height":120,"x":201,"y":142,"deviceScaleFactor":1.2,"full":"page","comparedToScreenshotId":"29d742c2-6f45-4f29-9d48-ba6fe66e6e3d","diffImageSrc":"https://prod-browseai-captured-data.s3.amazonaws.com/1fae674a-2788-46a8-83c8-95c4664c6d25/6326b3c1-7b16-4256-a323-7d8d8954bd4e/1061671f-7f71-42ac-bb9a-207d126d1f3a/00001-user-1620230947-6f113cf2-90ef-4c66-a448-9d5c6bd64873.png","changePercentage":20,"diffThreshold":5,"fileRemovedAt":1678795867879}}

capturedLists

object (CapturedLists)

必需

All lists captured in this task.

示例值:

{"companies":[{"Position":"1","name":"Airbnb","location":"San Francisco, CA, USA","description":"Book accommodations around the world."},{"Position":"2","name":"Coin base","location":"San Francisco, CA, USA","description":"Buy, sell, and manage crypto currencies."},{"Position":"3","name":"DoorDash","location":"San Francisco, CA, USA","description":"Restaurant delivery."}]}

🟠400A JSON containing error attributes. This will happen if any of the parameters are not valid.

🟠401The request is not authorized

🟠403The request can not be processed

🟠404The resource is not found

🔴500There was an error on the server

🔴503A JSON containing error attributes.