OpenAPI Agent

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>
POST/v2/agent/run-task

Run Task

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

Request Body

  • Name
    agent_id
    Type
    string
    required
    Description

    The ID of the agent that this task is assigned to.

  • Name
    task
    Type
    string
    required
    Description

    The task description that you want the agent to perform, in natural language.

  • Name
    secrets
    Type
    object
    Description
    Sensitive data required for task execution. For security and privacy purposes, this data will not be submitted to the LLM. Usage Example: {"https://github.com/login": {"login": "username","password": "xxxx"}}, where the "login" and "password" values are only used when accessing the URL "https://github.com/login"
  • 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 task. Browser profiles store session data, such as cookies, and other browsing state, that can be reused across tasks.

  • Name
    structured_output_json
    Type
    string
    Description

    Define the expected structured output JSON format.

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
    profileId
    Type
    string
    Description

    The ID of the browser profile used during task execution. This field is only populated when save_browser_data is enabled.

Request

POST
/v2/agent/run-task
  curl -X POST 'https://api.browseract.com/v2/agent/run-task' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{\
    "agent_id": "<string>",\
    "task": "<string>",\
    "secrets": "<object>",\
    "save_browser_data": "<boolean>",\
    "profile_id": "<string>",\
    "structured_output_json": "<string>"\
  }'

Response

{
  "id": "<string>",
  "profileId": "<string>"
}
PUT/v2/agent/stop-task

Stop Task

Permanently terminate the currently running task. This action is irreversible - once stopped, the task cannot be resumed or restarted. For temporary task suspension that allows resumption, use the /pause-task endpoint instead.

Query

  • Name
    task_id
    Type
    string
    required
    Description

    The ID of the task to terminate, returned by endpoints like /run-task.

Response 200

No content

Request

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

Pause Task

Temporarily pause the task. Use the /resume-task endpoint to resume. Useful for manual intervention or inspection.

Query

  • Name
    task_id
    Type
    string
    required
    Description

    The ID of the task to pause, returned by endpoints like /run-task.

Response 200

No content

Request

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

Resume Task

Resume a paused task and continue execution from where it left off. This operation is only available for tasks that are currently in a paused state - stopped or completed tasks cannot be resumed.

Query

  • Name
    task_id
    Type
    string
    required
    Description

    The ID of the task to resume, returned by endpoints like /run-task.

Response 200

No content

Request

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

Get Task

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

Query

  • Name
    task_id
    Type
    string
    required
    Description

    The ID of the task to retrieve, returned by endpoints like /run-task.

Response 200

  • Name
    id
    Type
    string
    Description

    Task ID

  • Name
    task
    Type
    string
    Description

    Natural language description of the desired task.

  • 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 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
    task_gif_url
    Type
    string
    Description

    A GIF generated from step-by-step screenshots during task execution; available only after the task has finished.

  • 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/agent/get-task
  curl -X GET 'https://api.browseract.com/v2/agent/get-task?task_id=<string>' \
  -H 'Authorization: Bearer <API_KEY>'

Response

{
  "id": "<string>",
  "task": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "finished_at": "<string>",
  "profile_id": "<string>",
  "live_url_info": {
    "live_url": "<string>",
    "width": "<integer>",
    "height": "<integer>"
  },
  "task_gif_url": "<string>",
  "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/agent/get-task-status

Get Task Status

Returns only the current status of the task.

Query

  • Name
    task_id
    Type
    string
    required
    Description

    The ID of the task, 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/agent/get-task-status
  curl -X GET 'https://api.browseract.com/v2/agent/get-task-status?task_id=<string>' \
  -H 'Authorization: Bearer <API_KEY>'

Response

{
  "status": "<string>"
}
GET/v2/agent/list-tasks

List Tasks

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

Query

  • Name
    agent_id
    Type
    string
    Description

    Specify the Agent ID to filter tasks. When provided, return only tasks associated with the specified Agent. If omitted, return tasks from all Agents.

  • 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
    agent_id
    Type
    string
    Description

    Agent ID

  • Name
    id
    Type
    string
    Description

    Task ID

  • Name
    task
    Type
    string
    Description

    Natural language description of the queried task.

  • 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/agent/list-tasks
  curl -X GET 'https://api.browseract.com/v2/agent/list-tasks?agent_id=<string>&page=<integer>&limit=<integer>' \
  -H 'Authorization: Bearer <API_KEY>'

Response

{
  "page": "<integer>",
  "limit": "<integer>",
  "total_pages": "<integer>",
  "total_count": "<integer>",
  "items": [
    {
      "agent_id": "<string>",
      "id": "<string>",
      "task": "<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/agent/list-agents

List Agents

Returns a paginated list of all Agents, 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 Agent entries

  • Name
    items
    Type
    array
    Description

    List of Agents

  • Name
    id
    Type
    string
    Description

    Agent ID

  • Name
    name
    Type
    string
    Description

    Agent's name

  • Name
    description
    Type
    string
    Description

    Agent's description

  • Name
    created_at
    Type
    string
    Description

    Agent created time

Request

GET
/v2/agent/list-agents
  curl -X GET 'https://api.browseract.com/v2/agent/list-agents?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>",
    }
  ]
}