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 startCopy Anchor Link

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 taskCopy Anchor Link

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 responseCopy Anchor Link

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 workCopy Anchor Link

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 MCPCopy Anchor Link

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 ownCopy Anchor Link

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.