Command Execution & Querying

Commands represent actions you want the browser to perform (e.g., open a URL, click a button, execute complex multistep autonomously, extract data from the page, etc). Commands sent to an active session are pushed into a FIFO queue.

POST /v1/sessions/{session_id}/execute

Execute one or more commands sequentially.

This is the unified endpoint for all command execution. It allows you to run single or multiple commands with a single request.

Path Parameters:

• session_id (string): The unique identifier of the session.

Request Body (JSON): (Note: There is a strict 1MB size limit for the entire request payload. Requests exceeding this limit will be rejected with a 413 Payload Too Large error)

• commands (array of objects, required): A list of command objects to execute in sequential order. Each object must contain:
  • command (string, required): The specific browser action to perform (e.g., "open_url", "click_at", "act", "extract").
  • params (object, optional): Parameters associated with the command. The required/optional fields differ based on the command type.

Request Example:

json
{
  "commands": [
    {
      "command": "open_url",
      "params": {
        "url": "https://news.ycombinator.com"
      }
    },
    {
      "command": "extract",
      "params": {
        "data_instruction": "Extract the top 5 news titles and their links.",
        "json_schema": [ { "title": "<title of the material>", "url": "<link to the material>" } ],
        "model_size": "small"
      }
    }
  ]
}

Response Example:

json
{
  "success": true,
  "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "status": "pending"
}

Command Statuses:

• pending: accepted and waiting in the session queue
• running: currently executing
• done: finished successfully
• failed: execution failed
• stopped: execution was intentionally stopped by the user
• cancelled: execution was cancelled before it could finish (e.g. session timeout)

Notes:

• POST /execute always creates a single command instance, even when you send a batch.
• A batch can contain many steps, but it still has one command_id.
• A failing step stops the remaining steps in that batch.

---