# Browser task

> Have a browser agent work through a page to reach a goal, as a long-running job.

`browser_task` has a browser agent open a page and work through it to reach a goal you describe in words: click through listings, fill a search form, collect what a page shows after interaction. It returns what the agent found, as text or as data in the shape of `output_schema`. Use [`web_scrape`](https://clonvo.com/docs/web-scrape.md) when reading the page as it loads is enough.

Call it with `POST /v1/tools/browser_task`, or as `browser_task` over [MCP](https://clonvo.com/docs/mcp.md). It runs as a [job](https://clonvo.com/docs/jobs.md).

> **Warning: Keep secrets out of the goal**
> 
> Don’t put passwords or personal data in the goal. The agent can submit forms, so MCP clients that auto-approve read-only tools ask before they call `browser_task`.

## Arguments

-   `url` string Required
    
    The page the agent starts on.
    
-   `goal` string Required
    
    What the agent should do and return, e.g. "List the first 10 products with name and price".
    
-   `output_schema` object
    
    A JSON Schema with "type": "object" for the shape of the result.
    
-   `max_steps` integer
    
    The most steps (page actions) the agent may take (1–150, default 30). The run is billed per step and stops at this limit.
    

## Example

```bash
curl https://api.clonvo.com/v1/tools/browser_task \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "url": "https://news.ycombinator.com",
      "goal": "Open the first story’s comments and return its title and the number of comments.",
      "output_schema": {
        "type": "object",
        "properties": { "title": { "type": "string" }, "comments": { "type": "integer" } }
      },
      "max_steps": 10
    }
  }'
```

The call answers `202` with a running job. Once you check it with `GET /v1/tools/jobs/{id}` and it has finished:

```json
{
  "id": "gen-01M6B6S0T2V4X6Z8B0D2F4H6K8",
  "object": "tool.job",
  "tool": "browser_task",
  "status": "completed",
  "provider": "clonvo",
  "created_at": "2026-11-09T12:00:00.000Z",
  "completed_at": "2026-11-09T12:00:47.000Z",
  "result": {
    "url": "https://news.ycombinator.com",
    "goal": "Open the first story’s comments and return its title and the number of comments.",
    "goal_reached": true,
    "output": { "title": "PostgreSQL 18 Released", "comments": 214 },
    "steps": 4
  },
  "usage": { "cost": 0.064, "charged": 0.06528, "is_byok": false }
}
```

## Result

Once the job is `completed`, its `result` has:

| Field | Description |
| --- | --- |
| `url` | The page the agent started on. |
| `goal` | The goal you gave. |
| `goal_reached` | `false` when the agent ran but reported that it couldn’t do the task. |
| `output` | What the agent returned: text, or data in the shape of `output_schema`. |
| `steps` | How many steps the agent took, when known. |
| `notes` | Present when the provider handled an argument differently. |

The job’s other fields are described in [Jobs](https://clonvo.com/docs/jobs.md#the-job-object).

## Notes

-   A browser task is billed for the steps the agent took. `max_steps` is a hard limit: if the agent reaches it without finishing, Clonvo stops the run, and the job fails with `step_limit_reached` and is charged for `max_steps`.
-   On Clonvo credits, Clonvo holds the cost of `max_steps` before the job starts. Lower `max_steps` to need less; see [Research and browser tasks on credits](https://clonvo.com/docs/tool-billing.md#research-and-browser-tasks-on-credits).
-   Clonvo removes email addresses and phone numbers from the output.
-   A goal can carry instructions about your own accounts, so it’s never stored as a [web tool query](https://clonvo.com/docs/privacy.md#web-tool-queries).