> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pre.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agents: start with https://docs.pre.dev/agents.md, which has complete recipes, plan access, polling rules, errors and limits.
> Authenticate with the workspace API key (pdk_…) from Integrations → Built-in, sent as Authorization: Bearer <key>.
> REST API: https://api.pre.dev (OpenAPI: https://docs.pre.dev/api-reference/openapi.json). AI Gateway: https://api.pre.dev/v1, OpenAI-compatible (OpenAPI: https://docs.pre.dev/api-reference/ai-gateway.openapi.json).
> pre.dev MCP server: https://api.pre.dev/mcp. Search these docs over MCP at https://docs.pre.dev/mcp.

# Browser Agents quickstart

> Extract a page heading, inspect the result, and choose a response mode.

Extract the main heading from a page and read it as structured data. This example uses `https://example.com` and an output schema with one required field: `heading`.

Want your coding agent to work in your own Chrome, with your logins? See [Browser Agents Local](/browser-agents/local).

## Before you start

Copy your pre.dev API key from **Integrations → Built-in** in the dashboard: [pre.dev/projects/integrations](https://pre.dev/projects/integrations?tab=built-in) for your personal workspace, or the Integrations page of a team workspace. Workspace keys start with `pdk_`.

Store it as `PREDEV_API_KEY`. You need available credits to submit a task; see [authentication and account access](/api-reference/authentication).

## Run the task

Choose curl, Node.js, or Python. The default request waits for the result.

<CodeGroup>
  ```bash curl theme={null}
  curl --fail-with-body https://api.pre.dev/browser-agent \
    -H "Authorization: Bearer $PREDEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "tasks": [{
        "url": "https://example.com",
        "instruction": "Extract the main page heading.",
        "output": {
          "type": "object",
          "properties": { "heading": { "type": "string" } },
          "required": ["heading"]
        }
      }]
    }'
  ```

  ```typescript Node.js theme={null}
  // npm install predev-api
  import { PredevAPI } from 'predev-api';

  const client = new PredevAPI({ apiKey: process.env.PREDEV_API_KEY! });
  const run = await client.browserAgent([{
    url: 'https://example.com',
    instruction: 'Extract the main page heading.',
    output: {
      type: 'object',
      properties: { heading: { type: 'string' } },
      required: ['heading'],
    },
  }]);
  const task = run.results[0];
  if (!task || task.status !== 'SUCCESS') {
    throw new Error(task?.error ?? 'The task did not succeed');
  }
  console.log(task.data);
  ```

  ```python Python theme={null}
  # pip install predev-api
  import os
  from predev_api import PredevAPI

  client = PredevAPI(api_key=os.environ["PREDEV_API_KEY"])
  run = client.browser_agent([{
      "url": "https://example.com",
      "instruction": "Extract the main page heading.",
      "output": {
          "type": "object",
          "properties": {"heading": {"type": "string"}},
          "required": ["heading"],
      },
  }])
  task = run["results"][0]
  if not task or task["status"] != "SUCCESS":
      raise RuntimeError((task or {}).get("error", "The task did not succeed"))
  print(task["data"])
  ```
</CodeGroup>

## Read the response

A successful task has `status: "SUCCESS"` and, for this example, data shaped like `{ "heading": "Example Domain" }`. The run also has an `id`, lowercase batch `status`, `results`, and `totalCreditsUsed`.

An illustrative response excerpt:

```json theme={null}
{
  "id": "507f1f77bcf86cd799439011",
  "status": "completed",
  "results": [
    {
      "status": "SUCCESS",
      "data": { "heading": "Example Domain" }
    }
  ]
}
```

A batch marked `completed` can contain failed tasks. Check `results[0].status` before reading `results[0].data`; the SDK examples above include this check. Explore the [run and task states](/browser-agents/api/task-status#batch-and-task-states) for failure cases.

## Use async for longer work

Add `"async": true` to the REST request body, `{ async: true }` to Node options, or `run_async=True` to the Python call. Set `BATCH_ID` to the actual `id` returned by your request, then poll:

```bash theme={null}
curl --fail-with-body "https://api.pre.dev/browser-agent/$BATCH_ID" \
  -H "Authorization: Bearer $PREDEV_API_KEY"
```

Stop when batch `status` becomes `completed` or `failed`. You can also [watch an existing run with SSE](/browser-agents/api/stream-task) or submit with `stream: true` for a [submission stream](/browser-agents/api/run-task#streaming).

## Use MCP

Follow [MCP setup](/architect-agent/mcp-setup), then ask your assistant:

```text theme={null}
Use pre.dev browser_agent to extract the main heading from
https://example.com into an object with a heading string.
Retrieve the full result using browser_agent_get.
```

## Make it your own

Replace the URL and instruction, then describe the data your application needs in `output`. For a workflow with several actions, make the desired end state explicit.

Continue with [task modes and limits](/browser-agents/api/run-task), [streaming results](/browser-agents/api/stream-task), or [safe retries](/api-reference/errors#retry-submissions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.