Browserbear API Reference
Browserbear is a browser automation service.
- You design a browser automation in Browserbear
- We turn it into an API
- You use the API to run the automation and get the output
https://api.browserbear.com
Authentication
Browserbear uses API keys to allow access to the API.
Browserbear expects the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: Bearer API_KEY
You can find your workspace API Keys in API Keys ↗.
All API requests on Browserbear are scoped to a Workspace.
get | /v2/auth |
{
"message": "Authorized",
"workspace": "My Workspace"
}
Account
To check your account status at any time you can use this endpoint. It will respond with your quota levels and current usage levels. Usage resets at the start of every month.
get | /v1/account |
{
"created_at": "2022-12-01T03:48:23.228Z",
"uid": "x4p71qmnY1nD5obLdG",
"plan_name": "Browserbear Automate",
"api_usage": 28,
"api_quota": 36000
}
Errors
The Browserbear API uses the following status / error codes. The Browserbear API rate limit is 30 requests per 10 seconds.
202 | Accepted -- Your request is has been accepted for processing |
200 | OK |
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
402 | Payment Required -- Your have run out of quota. |
404 | Not Found -- The specified request could not be found. |
429 | Too Many Requests -- Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Async
The Browserbear API is asynchronous. When creating a new run, you POST a request, the API responds immediately with 202 Accepted and you either receive the generated result via webhook or via polling.
You can run as many concurrent tasks as you want, as long as you request them within the API rate limit.
Tasks
A Task is a set of instructions that make up a browser automation. Tasks are created and edited via the Browserbear dashboard. The API can be used to list and retrieve Tasks.
To execute a Task, create a run.
get | /v1/tasks/:uid |
get | /v1/tasks |
The task object
Attributes
- uid stringThe unique ID for this object.
- name stringThe name of this task.
- viewport_width integerStarting viewport width.
- viewport_height integerStarting viewport height.
- steps arrayArray of steps that make up this task.
{
"created_at": "2022-12-01T03:48:43.728Z",
"name": "Elon Screenshot",
"uid": "851LyQMwvZw2lrXKpq",
"viewport_width": 1024,
"viewport_height": 768,
"steps": [
{
"action": "go",
"config": {
"url": "https://twitter.com/elonmusk"
},
"uid": "GNqV2ngBmly7O9dPRe"
},
{
"action": "take_screenshot",
"uid": "Km0k2XNbnlBA6Pplde"
}
]
}
Retrieve a task
Parameters
- uid stringrequiredThe task uid that you want to retrieve.
get | /v1/tasks/:uid |
fetch(`https://api.browserbear.com/v1/tasks/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all tasks
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v1/tasks |
fetch(`https://api.browserbear.com/v1/tasks`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
Runs
A Run is an execution of a task. You can start a new Run via API.
Runs execute asynchronously. When you make a new POST request you will receive a 202 Accepted response. The Run will then begin to execute.
To get the status of a Run you can query the GET endpoint.
To be notified when a Run finishes you can use a webhook.
The run object
Attributes
- uid stringThe unique ID for this object.
- task stringThe uid of the parent task.
- video_url stringLink to a video of the task running.
- outputs arrayArray of data outputs from steps, if any
- steps arrayArray of task steps at the time of this run.
{
"created_at": "2022-12-06T04:34:15.238Z",
"video_url": "https://media.browserbear.com/videos/oZwrg1DnX5qQM0v7Wq/2843a2b0a90c09b80d6d81f037854b5a3f33f2fa.mp4",
"uid": "5dDvA47kyWQ2N61w3R",
"task": "851LyQMwvZw2lrXKpq",
"steps": [
{
"action": "go",
"config": {
"url": "https://twitter.com/elonmusk"
},
"uid": "GNqV2ngBmly7O9dPRe"
},
{
"action": "take_screenshot",
"uid": "Km0k2XNbnlBA6Pplde",
"output": "https://media.browserbear.com/screenshots/oZwrg1DnX5qQM0v7Wq/o2Wm9xgbkrEzpqDZ0Y/1.jpg"
}
],
"status": "finished",
"finished_in_seconds": 6,
"webhook_url": null,
"outputs": [],
"metadata": null
}
Create a run
Parameters
- steps arrayArray of step overrides. You must include the uid, action and a config object for each step you want to modify. If you don't add any overrides the step will run according to its default config.
- webhook_url stringA url to POST the full Run object to upon finishing.
- metadata stringAny metadata you need to store e.g. ID of a record in your DB.
post | /v1/tasks/:task_uid/runs |
//go to a different url
var data = {
"steps": [
{
"uid": "GNqV2ngBmly7O9dPRe",
"action": "go",
"config": {
"url": "https://twitter.com/apple"
}
}
]
}
fetch('https://api.browserbear.com/v1/tasks/:task_uid/runs', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Retrieve a run
Parameters
- task_uid stringrequiredThe task uid.
- uid stringrequiredThe run uid that you want to retrieve.
get | /v1/tasks/:task_uid/runs/:uid |
fetch(`https://api.browserbear.com/v1/tasks/${TASK_UID}/runs/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all runs
Parameters
- task_uid stringrequiredThe task uid.
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v1/tasks/:task_uid/runs |
fetch(`https://api.browserbear.com/v1/tasks/${TASK_UID}/runs`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})