Browser agent

The browser agent does web tasks your code can't do with a plain HTTP request: search a site, click through pages, fill and submit forms, log in, and read what the page shows. You describe the task in plain words. The agent works in a real Chromium browser, one action at a time, and returns a text answer and, if you ask for it, JSON in data.

It uses the same API key and prepaid balance as the rest of Lovely Router. You pay per step, from $0.006, and the models are included. There is no run fee.

Run your first task#

1. 1

   Get an API key

   Create a key in API keys and export it. A post about Lovely Router on X gets you $2 of free credit, enough for dozens of short runs (how).

   Shell

   export LOVELY_API_KEY="lr-..."

2. 2

   Start a run

   Send a goal and a start_url to POST /v1/browser/runs. The response comes back at once with status 202 and the run's id. The agent keeps working in the background.

   cURLPythonNode.js

   Shell

   curl https://lovelyrouter.com/v1/browser/runs \
     -H "Authorization: Bearer $LOVELY_API_KEY" \
     -H "content-type: application/json" \
     -d '{
       "goal": "Find the price of the book \"A Light in the Attic\" and whether it is in stock.",
       "start_url": "https://books.toscrape.com/"
     }'

3. 3

   Wait for the result

   Fetch the run with ?wait=30. The request holds for up to 30 seconds (50 at most) and returns as soon as the status changes, so a loop of these calls follows the run without busy polling.

   To watch the run instead, with each step and the browser's screen as they happen, add "stream": true when you start it. See Live events & screen.

   cURLPythonNode.js

   Shell

   curl "https://lovelyrouter.com/v1/browser/runs/brun_3f9a1c7e0b2d4e6f8a9b0c1d?wait=30" \
     -H "Authorization: Bearer $LOVELY_API_KEY"

4. 4

   Read the result

   A finished run has a status, the agent's answer, and what it cost in charge_usd (abridged):

   JSON

   {
     "id": "brun_3f9a1c7e0b2d4e6f8a9b0c1d",
     "object": "browser_run",
     "status": "succeeded",
     "mode": "fast",
     "steps": 2,
     "max_steps": 50,
     "current_url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
     "answer": "\"A Light in the Attic\" costs £51.77 and is in stock (22 available).",
     "data": null,
     "error": null,
     "charge_usd": 0.012,
     "reserved_usd": 0
   }

   The full list of fields is in the run object. Add &trace=1 to the request to get every step the agent took.

You can also start runs from the console: pick an example or write a task, watch the browser's screen and each step live, answer the agent when it asks, and copy the matching cURL, Python or JavaScript code.

How a run works#

A run starts as running and ends in one of four final statuses. In between, it can pause as waiting_for_human and continue after you reply.

Each step, the agent reads the current page, picks one action, and does it. It stops when the goal is met, when it needs a person, or when it reaches max_steps. Before it clicks a button that submits a form, it checks every field against your goal and fixes values that don't match.

succeeded means the agent finished, not that the website accepted what it did. For tasks that submit something, read the answer: if the page showed a validation error or no confirmation, the answer says so.

When the run ends, the unused part of the amount reserved at the start returns to your balance and charge_usd shows the final charge. charge_usd is null until then.

What counts as a step#

A step is one browser action:

• click a link, button, checkbox or list option
• type into a field, or type and press Enter
• choose an option in a dropdown
• fill a saved secret or upload a file
• go back to the previous page
• wait for a page that has not loaded yet, or load it again
• run read-only code to read data from the page (accurate mode only)
• write the final answer

Pauses for a person (a question, an approval, a handover) appear in the trace but are not billed. A step that fails, for example because the element moved, still counts. The run's steps field counts every recorded step, pauses included.

A simple lookup takes 1 to 3 steps. A login takes 4 to 8. A long multi-page form takes 15 to 25. Modes, models & pricing has cost examples.

Write goals that work#

The goal is the agent's only instruction. Write it the way you would brief a careful assistant who has never seen the site.

• Include every value the task needs. Names, emails, dates, quantities, the exact product. Don't leave the agent to guess: if a value is missing, it stops to ask you (unless you turned questions off).
• Say what to report. "Tell me the price and whether it is in stock" gets a better answer than "check the book".
• For actions, say what proves success. "Submit the form and tell me the confirmation number."
• Start close to the task. Use the search page or the form itself as start_url, not the home page, when you know it.
• Name the place to look when the site has several: "in the Reviews tab", "using the site's own search".
• One task per run. Split unrelated tasks into separate runs.
• Keep secrets out of the goal. Pass passwords as vault secrets, never in the goal text.

Limits#

When you reach the limit on runs at once, POST /v1/browser/runs returns 429. When your balance is below what the run reserves, it returns 402. Errors lists every error.

Use it from an AI agent#

The MCP server at https://lovelyrouter.com/mcp exposes the browser agent as four tools: browser_run, browser_status, browser_reply and browser_takeover. They use the same key, limits and prices as the REST API. The MCP tools take vault secret names, never secret values: store secrets in the vault first.

Next steps#