OpenAPI Workflow

Base URL

Code

https://api.browseract.com

Authorization

Bearer authentication header in the format Bearer <API_KEY>, where <API_KEY> is your API key.

Code

Authorization: Bearer <API_KEY>

Code Examples

Java: https://github.com/browseract-ai/browseract/tree/main/Workflow-Java
NodeJs: https://github.com/browseract-ai/browseract/tree/main/Workflow-NodeJs
Python: https://github.com/browseract-ai/browseract/tree/main/Workflow-Python

POST/v2/workflow/run-task

Run Task

Start a new workflow task and return a task ID for progress tracking.

Request Body

Name
workflow_id
Type
string
required
Description
The workflow ID used to create and spawn a new task.
Name
input_parameters
Type
array
Description
Parameters entered when running a workflow task
Name
name
Type
string
Description
The name of the parameter
Name
value
Type
string
Description
Input value of the parameter
Name
save_browser_data
Type
boolean
Description
Specify whether a profile_id should be returned in the response upon successful task submission. The profile stores browser session data, including cookies and other browsing state, that is generated during task execution.
Name
profile_id
Type
string
Description
The browser profile to use for this workflow task. Browser profiles store session data, such as cookies, and other browsing state, that can be reused across tasks.
Name
callback_url
Type
string
Description
HTTP / HTTPS URL to receive task completion notifications via POST request.
The callback payload structure is identical to the Get Task API response.
Triggered when: Task completes, fails, or is canceled.
Requirements:

Valid HTTP/HTTPS URL (max 2048 characters)

Publicly accessible endpoint

Must return 2xx status within 30 seconds

Redirects (3xx) are not allowed
Retry: Automatic retry (max 3 attempts) for 5xx errors only.
See Get Task API response for the exact callback payload structure.
Name
status_change_callback_url
Type
string
Description
HTTP / HTTPS URL to receive task status change notifications via POST request.
The callback payload structure is identical to the Get Task API response.
Triggered when: Task running, finished, canceled, paused, failed.
Requirements:

Valid HTTP/HTTPS URL (max 2048 characters)

Publicly accessible endpoint

Must return 2xx status within 30 seconds

Redirects (3xx) are not allowed
Retry: Automatic retry (max 3 attempts) for 5xx errors only.
See Get Task API response for the exact callback payload structure.

Response 200

Name
id
Type
string
Description
The unique task_id for this task, which can be used to track its progress or result.
Name
profile_id
Type
string
Description
The ID of the browser profile used during workflow task execution. This field is only populated when save_browser_data is enabled.

Request

POST

/v2/workflow/run-task

  curl -X POST 'https://api.browseract.com/v2/workflow/run-task' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
   "workflow_id": "<string>",
   "input_parameters": "<array>",
    "save_browser_data": "<boolean>",
    "profile_id": "<string>",
    "callback_url": "<string>"
  }'

Response

{
  "id": "<string>",
  "profile_id": "<string>"
}

PUT/v2/workflow/stop-task

Stop Task

Permanently terminate the currently running task. This action is irreversible - once stopped, the task cannot be resumed or restarted.

Query

Name
task_id
Type
string
required
Description
The ID of the workflow task to terminate, returned by endpoints like /run-task.

Response 200

No content

Request

PUT

/v2/workflow/stop-task

  curl -X PUT 'https://api.browseract.com/v2/workflow/stop-task?task_id=<string>' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json'

GET/v2/workflow/get-task

Get Task

Retrieve detailed information about the workflow task, including current status, completed steps, output from finished tasks, and other metadata.

Query

Name
task_id
Type
string
required
Description
The ID of the workflow task to retrieve, returned by endpoints like /run-task.

Response 200

Name
id
Type
string
Description
Task ID
Name
input_parameters
Type
string
Description
Workflow input parameters as key=value pairs when running the workflow task, separated by semicolons. Example: key1=value1;key2=value2
Name
status
Type
string
Description
Task status (created, running, finished, canceled, pausing, paused, failed)
Name
created_at
Type
string
Description
Task created time
Name
finished_at
Type
string
Description
Task finished time
Name
profile_id
Type
string
Description
The ID of the browser profile used during task execution. This field is only populated when save_browser_data is enabled.
Name
live_url_info
Type
object
Description
Status information about task execution live view URL. Available only when the workflow task is actively running.
Name
live_url
Type
string
Description
The live view URL of task execution, which can be directly embedded in an <iframe> tag.
Name
width
Type
integer
Description
Screen width
Name
height
Type
integer
Description
Screen height
Name
output
Type
object
Description
The results and output data generated by the task execution. Only available after task completion.
Name
string
Type
string
Description
Task output as a plain string
Name
files
Type
array
Description
Download URL list for output files
Name
steps
Type
array
Description
List of sub-steps within the task
Name
id
Type
string
Description
Step ID
Name
status
Type
string
Description
Step status (running, succeed, failed)
Name
evaluation_previous_goal
Type
string
Description
Evaluation result of the previous step
Name
step_goal
Type
string
Description
Execution objective of the current step
Name
screenshots_url
Type
string
Description
Screenshot URL from current step
Name
task_failure_info
Type
object
Description
Error details and results from failed task execution. Only available after task failure.
Name
code
Type
string
Description
Error code
Name
message
Type
string
Description
Error message

Request

GET

/v2/workflow/get-task

  curl -X GET 'https://api.browseract.com/v2/workflow/get-task?task_id=<string>' \
  -H 'Authorization: Bearer <API_KEY>'

Response

{
  "id": "<string>",
  "input_parameters": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "finished_at": "<string>",
  "profile_id": "<string>",
  "live_url_info": {
    "live_url": "<string>",
    "width": "<integer>",
    "height": "<integer>"
  },
  "output": {
    "string": "<string>",
    "files": "<array[string]>"
  },
  "steps": [
    {
      "id": "<string>",
      "status": "<string>",
      "evaluation_previous_goal": "<string>",
      "step_goal": "<string>",
      "screenshots_url": "<string>"
    }
  ],
  "task_failure_info": {
    "code": "<string>",
    "message": "<string>"
  }
}

GET/v2/workflow/get-task-status

Get Task Status

Returns only the current status of the task.

Query

Name
task_id
Type
string
required
Description
The task ID, returned by endpoints like /run-task.

Response 200

Name
status
Type
string
Description
Task status (created, running, finished, canceled, pausing, paused, failed)

Request

GET

/v2/workflow/get-task-status

  curl -X GET 'https://api.browseract.com/v2/workflow/get-task-status?task_id=<string>' \
  -H 'Authorization: Bearer <API_KEY>'

Response

{
  "status": "<string>"
}

GET/v2/workflow/list-tasks

List Tasks

Returns a paginated list of all tasks, sorted by creation time. Each task includes basic information such as status and creation time.

Query

Name
workflow_id
Type
string
Description
Specify the workflow ID to filter tasks. When provided, return only tasks associated with the specified workflow. If omitted, return tasks from all workflows.
Name
page
Type
integer
Description
Page number (minimum: 1, default: 1)
Name
limit
Type
integer
Description
Number of items per page (minimum: 1, maximum: 500, default: 1)

Response 200

Name
page
Type
integer
Description
Current page number of the data
Name
limit
Type
integer
Description
Number of items per page
Name
total_pages
Type
integer
Description
Total number of pages
Name
total_count
Type
integer
Description
Total number of task entries
Name
items
Type
array
Description
List of task items.
Name
workflow_id
Type
string
Description
Workflow ID
Name
id
Type
string
Description
Task ID
Name
input_parameters
Type
string
Description
Workflow input parameters as key=value pairs when running the workflow task, separated by semicolons. Example: key1=value1;key2=value2
Name
status
Type
string
Description
Task status (created, running, finished, canceled, pausing, paused, failed)
Name
created_at
Type
string
Description
Task created time
Name
finished_at
Type
string
Description
Task finished time
Name
profile_id
Type
string
Description
The ID of the browser profile used during task execution.
Name
live_url_info
Type
object
Description
Status information about task execution live view URL. Available only when the task is actively running.
Name
live_url
Type
string
Description
The live view URL of task execution, which can be directly embedded in an <iframe> tag.
Name
width
Type
integer
Description
Screen width
Name
height
Type
integer
Description
Screen height
Name
output
Type
object
Description
The results and output data generated by the task execution. Only available after task completion.
Name
string
Type
string
Description
Task output as a plain string
Name
files
Type
array
Description
Download URL list for output files
Name
task_failure_info
Type
object
Description
Error details and results from failed task execution. Only available after task failure.
Name
code
Type
string
Description
Error code
Name
message
Type
string
Description
Error message

Request

GET

/v2/workflow/list-tasks

  curl -X GET 'https://api.browseract.com/v2/workflow/list-tasks?workflow_id=<string>&page=<integer>&limit=<integer>' \
  -H 'Authorization: Bearer <API_KEY>'

Response

{
  "page": "<integer>",
  "limit": "<integer>",
  "total_pages": "<integer>",
  "total_count": "<integer>",
  "items": [
    {
      "workflow_id": "<string>",
      "id": "<string>",
      "input_parameters": "<string>",
      "status": "<string>",
      "created_at": "<string>",
      "finished_at": "<string>",
      "profile_id": "<string>",
      "live_url_info": {
        "live_url": "<string>",
        "width": "<integer>",
        "height": "<integer>"
      },
      "output": {
        "string": "<string>",
        "files": "<array[string]>"
      },
      "task_failure_info": {
        "code": "<string>",
        "message": "<string>"
      }
    }
  ]
}

GET/v2/workflow/list-workflows

List Workflows

Returns a paginated list of all Workflows, sorted by creation time.

Query

Name
page
Type
integer
Description
Page number (minimum: 1, default: 1)
Name
limit
Type
integer
Description
Number of items per page (minimum: 1, maximum: 500, default: 1)

Response 200

Name
page
Type
integer
Description
Current page number of the data
Name
limit
Type
integer
Description
Number of items per page
Name
total_pages
Type
integer
Description
Total number of pages
Name
total_count
Type
integer
Description
Total number of Workflow entries
Name
items
Type
array
Description
List of Workflow items.
Name
id
Type
string
Description
Workflow ID
Name
name
Type
string
Description
Workflow's name
Name
description
Type
string
Description
Workflow's description
Name
created_at
Type
string
Description
Workflow created time
Name
publish_at
Type
string
Description
Workflow's most recent release time

Request

GET

/v2/workflow/list-workflows

  curl -X GET 'https://api.browseract.com/v2/workflow/list-workflows?page=<integer>&limit=<integer>' \
  -H 'Authorization: Bearer <API_KEY>'

Response

{
  "page": "<integer>",
  "limit": "<integer>",
  "total_pages": "<integer>",
  "total_count": "<integer>",
  "items": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "created_at": "<string>",
      "publish_at": "<string>",
    }
  ]
}

GET/v2/workflow/get-workflow

Get Workflow

Get workflow details, including required input parameters

Query

Name
workflow_id
Type
string
required
Description
The ID of the desired workflow

Response 200

Name
id
Type
string
Description
Workflow ID
Name
name
Type
string
Description
Workflow's name
Name
description
Type
string
Description
Workflow's description
Name
created_at
Type
string
Description
Workflow created time
Name
publish_at
Type
string
Description
Workflow's most recent publish time
Name
input_parameters
Type
array
Description
Parameters entered when running the workflow task
Name
name
Type
string
Description
The name of the parameter
Name
default_enabled
Type
boolean
Description
Specify whether the default value is enabled

Request

GET

/v2/workflow/get-workflow

  curl -X GET 'https://api.browseract.com/v2/workflow/get-workflow?workflow_id=<string>' \
  -H 'Authorization: Bearer <API_KEY>'

Response

{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "created_at": "<string>",
  "publish_at": "<string>",
  "input_parameters": [
    {
      "name": "<string>",
      "default_enabled": "<boolean>",
    }
  ],
}