Browser Agents quickstart

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.

Before you start

Copy your pre.dev API key from Integrations → Built-in in the dashboard: pre.dev/projects/integrations 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.

Run the task

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

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"]
      }
    }]
  }'

// 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);

# 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:

{
  "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 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:

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 or submit with stream: true for a submission stream.

Use MCP

Follow MCP setup, then ask your assistant:

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, streaming results, or safe retries.

Get started

Quickstarts

Essentials

Resources

Browser Agents quickstart

Before you start

Run the task

Read the response

Use async for longer work

Use MCP

Make it your own

​Before you start

​Run the task

​Read the response

​Use async for longer work

​Use MCP

​Make it your own

Before you start

Run the task

Read the response

Use async for longer work

Use MCP

Make it your own