Command Execution

Commands represent actions you want the browser to perform.

session.execute(commands: Union[CommandPayload, List[CommandPayload]], await_completion=True)

Execute one or more commands sequentially. This method awaits the full execution by default and returns the complete result metadata once the final status is done or failed.

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:

• session.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.

session.get_commands(limit=50, start_after=None, status=None)

List all executed commands within a given session, sorted from newest to oldest.

Returns (Dictionary):

python
{
  "success": True,
  "has_more": False,
  "commands": [
    {
      "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "status": "done",
      "command": "open_url",
      "created_at": "2026-05-01T12:05:00Z",
      "finished_at": "2026-05-01T12:05:15Z"
    },
    {
      "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "status": "done",
      "command": "extract",
      "created_at": "2026-05-01T12:04:58Z",
      "finished_at": "2026-05-01T12:05:00Z"
    }
  ]
}

session.get_command(command_id)

Check the execution status and retrieve the response of a specific command. This method utilizes a smart long-polling mechanism (up to a set timeout, generally 15-30 seconds). If the command's status is "pending" or "running", it will hold the connection open, returning immediately when the status changes to "done" or "failed".

If the response data (e.g., large HTML snapshot or image data) exceeds internal limits, it is offloaded to the cloud and you'll receive an offloaded_data_url instead of inline JSON data in the response object.

Returns (Dictionary) - Success Example:

python
{
  "success": True,
  "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
  "status": "done",
  "created_at": "2026-05-01T12:04:58Z",
  "finished_at": "2026-05-01T12:05:15Z",
  "response": {
    "commands": [
        {
            "step": 0,
            "data": {
                "url": "about:blank"
            },
            "success": True,
            "command": "get_url"
        },
        {
            "step": 1,
            "data": {
                "url": "https://example.com"
            },
            "success": True,
            "command": "open_url"
        }
    ]
  }
}

Returns (Dictionary) - Failure Example:

python
{
  "success": True,
  "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
  "status": "failed",
  "error_name": "InvalidParams",
  "error_message": "run_js() missing 1 required positional argument: 'js_code'",
  "created_at": "2026-05-01T12:04:58Z",
  "finished_at": "2026-05-01T12:05:05Z",
  "response": {
    "commands": [
      {
        "step": 0,
        "success": False,
        "command": "run_js",
        "error_name": "InvalidParams",
        "error_message": "run_js() missing 1 required positional argument: 'js_code'"
      }
    ]
  }
}