> ## Documentation Index
> Fetch the complete documentation index at: https://predev.mintlify.site/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: npx -y @predotdev/mcp setup adds it to every local coding agent with every pre.dev tool plus the user's own Chrome; the hosted server is 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](https://predev.mintlify.site/browser-agents/local.md).

## 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](https://predev.mintlify.site/api-reference/authentication.md).

## Run the task

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

```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"])
```

## 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](https://predev.mintlify.site/browser-agents/api/task-status.md#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](https://predev.mintlify.site/browser-agents/api/stream-task.md) or submit with `stream: true` for a [submission stream](https://predev.mintlify.site/browser-agents/api/run-task.md#streaming).

## Use MCP

Follow [MCP setup](https://predev.mintlify.site/architect-agent/mcp-setup.md), 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](https://predev.mintlify.site/browser-agents/api/run-task.md), [streaming results](https://predev.mintlify.site/browser-agents/api/stream-task.md), or [safe retries](https://predev.mintlify.site/api-reference/errors.md#retry-submissions).


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