Run a Task

curl -X POST 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 page heading." }
    ]
  }'

{
  "id": "65f8a9d2c1e4b5a6f7e8d9c0",
  "total": 1,
  "completed": 1,
  "results": [
    {
      "url": "https://example.com",
      "instruction": "Extract the page heading.",
      "status": "SUCCESS",
      "data": { "heading": "Example Domain" },
      "creditsUsed": 0.11,
      "durationMs": 4820
    }
  ],
  "totalCreditsUsed": 0.11,
  "status": "completed",
  "createdAt": "2026-04-16T18:22:10.224Z",
  "completedAt": "2026-04-16T18:22:15.044Z"
}

curl -X POST 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 heading." }],
    "async": true
  }'

{
  "id": "65f8a9d2c1e4b5a6f7e8d9c0",
  "total": 1,
  "completed": 0,
  "results": [],
  "totalCreditsUsed": 0,
  "status": "processing"
}

curl -N -X POST 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 heading." }],
    "stream": true
  }'

:ok

event: task_event
data: {"taskIndex":0,"type":"navigation","data":{"url":"https://example.com"}}

event: task_event
data: {"taskIndex":0,"type":"screenshot","data":{"url":"https://..."}}

event: task_result
data: {"taskIndex":0,"status":"SUCCESS","data":{"heading":"Example Domain"},"durationMs":4820}

event: done
data: {"id":"65f8...","total":1,"completed":1,"results":[...],"status":"completed"}

{
  "error": "Need ~0.5 credits, have 0.00. Buy more to continue.",
  "code": "INSUFFICIENT_CREDITS",
  "actionUrl": "https://pre.dev/projects/key?upgrade=credits"
}

curl -X POST https://api.pre.dev/browser-agent \
  -H "Authorization: Bearer $PREDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      { "url": "https://news.ycombinator.com", "instruction": "Extract the top 5 story titles." },
      { "url": "https://www.reddit.com/r/programming", "instruction": "Extract the top 5 post titles." }
    ],
    "concurrency": 2
  }'

curl -X POST https://api.pre.dev/browser-agent \
  -H "Authorization: Bearer $PREDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": [
      {
        "url": "https://news.ycombinator.com",
        "instruction": "Extract the top 5 stories.",
        "output": {
          "type": "object",
          "properties": {
            "stories": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "title": { "type": "string" },
                  "points": { "type": "number" }
                },
                "required": ["title", "points"]
              }
            }
          },
          "required": ["stories"]
        }
      }
    ]
  }'

import json
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.pre.dev/browser-agent"
HDR = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def run_sync(tasks, concurrency=5):
    r = requests.post(BASE, headers=HDR, json={"tasks": tasks, "concurrency": concurrency})
    r.raise_for_status()
    return r.json()


def run_async(tasks, concurrency=5, poll_every=5):
    r = requests.post(BASE, headers=HDR, json={"tasks": tasks, "concurrency": concurrency, "async": True})
    r.raise_for_status()
    batch_id = r.json()["id"]
    while True:
        poll = requests.get(f"{BASE}/{batch_id}", headers=HDR).json()
        if poll["status"] in ("completed", "failed"):
            return poll
        print(f"{poll['completed']}/{poll['total']} done")
        time.sleep(poll_every)


def run_stream(tasks):
    with requests.post(BASE, headers=HDR, json={"tasks": tasks, "stream": True}, stream=True) as r:
        r.raise_for_status()
        event = None
        for line in r.iter_lines(decode_unicode=True):
            if line is None or line.startswith(":"):
                continue
            if line.startswith("event: "):
                event = line[len("event: "):].strip()
            elif line.startswith("data: "):
                data = json.loads(line[len("data: "):])
                yield event, data


# sync
result = run_sync([{"url": "https://example.com", "instruction": "Extract the heading."}])
print(result["results"][0]["data"])

# stream
for event, data in run_stream([{"url": "https://example.com", "instruction": "Extract the heading."}]):
    if event == "task_event":
        print(f"[task {data['taskIndex']}] {data.get('type')}")
    elif event == "task_result":
        print(f"[task {data['taskIndex']}] {data['status']} → {data.get('data')}")
    elif event == "done":
        print("batch done:", data["id"])
        break

const API_KEY = process.env.PREDEV_API_KEY;
const BASE = "https://api.pre.dev/browser-agent";
const HDR = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

async function runSync(tasks, concurrency = 5) {
  const res = await fetch(BASE, {
    method: "POST",
    headers: HDR,
    body: JSON.stringify({ tasks, concurrency }),
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

async function* runStream(tasks) {
  const res = await fetch(BASE, {
    method: "POST",
    headers: HDR,
    body: JSON.stringify({ tasks, stream: true }),
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  let event = null;

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });

    let idx;
    while ((idx = buffer.indexOf("\n")) !== -1) {
      const line = buffer.slice(0, idx).trim();
      buffer = buffer.slice(idx + 1);
      if (!line || line.startsWith(":")) continue;
      if (line.startsWith("event: ")) event = line.slice(7).trim();
      else if (line.startsWith("data: ")) yield { event, data: JSON.parse(line.slice(6)) };
    }
  }
}

// sync
const result = await runSync([
  { url: "https://example.com", instruction: "Extract the heading." },
]);
console.log(result.results[0].data);

// stream
for await (const { event, data } of runStream([
  { url: "https://example.com", instruction: "Extract the heading." },
])) {
  if (event === "task_event") console.log(`[task ${data.taskIndex}]`, data.type);
  if (event === "task_result") console.log(`[task ${data.taskIndex}]`, data.status, data.data);
  if (event === "done") break;
}

type TaskStatus =
  | "SUCCESS" | "PENDING" | "ERROR" | "TIMEOUT"
  | "BLOCKED" | "CAPTCHA_FAILED" | "LOOP" | "NO_TARGET";

interface Task {
  url: string;
  instruction?: string;
  input?: Record<string, string>;
  output?: Record<string, unknown>;
  successCondition?: string;
  timeoutMs?: number;
}

interface TaskResult {
  url: string;
  instruction?: string;
  input?: Record<string, string>;
  status: TaskStatus;
  data?: unknown;
  creditsUsed: number;
  durationMs: number;
  error?: string;
}

interface BatchResult {
  id: string;
  total: number;
  completed: number;
  results: TaskResult[];
  totalCreditsUsed: number;
  status: "processing" | "completed" | "failed";
  createdAt?: string;
  completedAt?: string;
  error?: string;
}

interface BatchRequest {
  tasks: Task[];
  concurrency?: number;
  async?: boolean;
  stream?: boolean;
}

export class BrowserAgents {
  constructor(private apiKey: string, private base = "https://api.pre.dev/browser-agent") {}

  private headers() {
    return {
      "Authorization": `Bearer ${this.apiKey}`,
      "Content-Type": "application/json",
    };
  }

  async run(req: BatchRequest): Promise<BatchResult> {
    const res = await fetch(this.base, { method: "POST", headers: this.headers(), body: JSON.stringify(req) });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    return res.json();
  }
}