Guides

Creating runs

A run is the unit of work in BrowserPilot. This guide covers how to describe a task, shape its output, observe it, and handle failure.

Describe the task

Write the task as an outcome, not a script. "List every open role with title and team" is a good task; "click the third nav link, then scroll" is a brittle one. The agent plans the steps and adapts when a page changes.

POST /v1/runs
{
  "task": "Open the pricing page and capture each plan name and monthly price"
}

Shape the output

Pass an output object to define the JSON shape you want back. The agent is responsible for satisfying the contract; if it cannot, the run fails clearly instead of returning partial data.

{
  "task": "Open the pricing page and capture each plan",
  "output": { "plans": [{ "name": "", "price": "" }] }
}

Observe the run

You have two options. Poll the run by id, or — preferred — register a webhook and receive a signed event the moment the run reaches a terminal state. Either way, every run also streams live in the dashboard.

GET /v1/runs/run_9fA2c1
→ { "status": "running", "steps": 8, "cost_usd": 0.11 }

Cancel a run

A run can be cancelled while it is running. Cancellation is propagated to the browser session immediately and emits a run.cancelled event.

DELETE /v1/runs/run_9fA2c1

Failure and recovery

When a step fails, BrowserPilot retries from the last checkpoint rather than restarting the run. If the task still cannot be completed, the run ends as failed with the error and the full step history intact — so you can replay exactly where it went wrong.