Skip to main content
GET
/
api
/
v1
/
browser-agents
List your runs
curl --request GET \
  --url https://api.pre.dev/api/v1/browser-agents \
  --header 'Authorization: Bearer <token>'
{
  "batches": [
    {
      "id": "<string>",
      "total": 123,
      "completed": 123,
      "results": [
        {
          "url": "<string>",
          "instruction": "<string>",
          "input": {},
          "status": "SUCCESS",
          "data": "<unknown>",
          "creditsUsed": 123,
          "durationMs": 123,
          "error": "<string>",
          "events": [
            {
              "type": "navigation",
              "data": {},
              "ts": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ],
      "totalCreditsUsed": 123,
      "status": "processing",
      "createdAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "liveEvents": [
        [
          {
            "type": "navigation",
            "data": {},
            "ts": "2023-11-07T05:31:56Z"
          }
        ]
      ],
      "error": "<string>"
    }
  ],
  "total": 123,
  "hasMore": true
}
Paginate over every run this API key has created, newest first. Useful for building a history UI, reconciling your own records, or spot-checking processing runs.

​
Overview

  • Method: GET
  • Path: /api/v1/browser-agents
  • Auth: same Authorization: Bearer YOUR_API_KEY as Run a Task
  • Sort order: newest first (createdAt descending).
  • Scope: only runs owned by this API key are returned.

​
Query Parameters

NameTypeDefaultDescription
limitinteger20Page size. 1 ≤ limit ≤ 100. Values outside the range are clamped.
skipinteger0Number of runs to skip (offset-based pagination).
status"processing" | "completed"—Filter by run state. Omit to return all states.

​
Response

interface ListRunsResponse {
  batches: BatchResult[]; // historical field name — each entry is a run summary
  total: number;          // total matching runs (ignores limit/skip)
  hasMore: boolean;       // true when skip + limit < total
}
Each entry in batches is a summary row:
FieldTypeDescription
idstringRun id. Pass to GET /:id for full results.
totalintegerNumber of tasks in the run.
completedintegerHow many tasks have finished.
resultsTaskResult[]Array sized to total. Index 0 is pre-populated with a stub { url, instruction } for the first task so you can render a list row even before it completes; other indices are null until the run finishes.
totalCreditsUsednumberRunning credits total across completed tasks.
status"processing" | "completed" | "failed"Current state.
createdAtISO-8601Run creation time.
completedAtISO-8601Only set once status !== "processing".
The envelope field is historically named batches, not runs, to stay backward-compatible with older clients. Each entry is the same run-summary shape described above.

​
Example

curl "https://api.pre.dev/api/v1/browser-agents?limit=10&status=completed" \
  -H "Authorization: Bearer $PREDEV_API_KEY"

{
  "batches": [
    {
      "id": "65f8a9d2c1e4b5a6f7e8d9c0",
      "total": 3,
      "completed": 3,
      "results": [
        {
          "url": "https://example.com",
          "instruction": "Extract the heading.",
          "status": "SUCCESS",
          "data": { "heading": "Example Domain" },
          "creditsUsed": 0.11,
          "durationMs": 4820
        },
        { "...": "..." },
        { "...": "..." }
      ],
      "totalCreditsUsed": 0.41,
      "status": "completed",
      "createdAt": "2026-04-16T18:22:10.224Z",
      "completedAt": "2026-04-16T18:23:07.918Z"
    }
  ],
  "total": 87,
  "hasMore": true
}

​
Status Codes

CodeMeaning
200OK. Body is the list envelope above.
401Missing or invalid bearer token.

​
Pagination Patterns

​
Python — iterate every run

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.pre.dev/api/v1/browser-agents"
HDR = {"Authorization": f"Bearer {API_KEY}"}


def iter_runs(status: str | None = None, page_size: int = 100):
    skip = 0
    while True:
        params = {"limit": page_size, "skip": skip}
        if status:
            params["status"] = status
        r = requests.get(BASE, headers=HDR, params=params)
        r.raise_for_status()
        page = r.json()
        for run in page["batches"]:
            yield run
        if not page.get("hasMore"):
            return
        skip += page_size


# Tally credits used across every completed run.
total_credits = sum(run["totalCreditsUsed"] for run in iter_runs(status="completed"))
print(f"Lifetime spend: {total_credits} credits")

​
Node.js — fetch a single page

const API_KEY = process.env.PREDEV_API_KEY;
const BASE = "https://api.pre.dev/api/v1/browser-agents";

async function listRuns({ limit = 20, skip = 0, status } = {}) {
  const params = new URLSearchParams({ limit: String(limit), skip: String(skip) });
  if (status) params.set("status", status);

  const res = await fetch(`${BASE}?${params}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

const { batches, total, hasMore } = await listRuns({ limit: 25, status: "processing" });
console.log(`${batches.length}/${total} in-flight runs`);

​
TypeScript — pull all pages

async function fetchAllRuns(opts: { status?: "processing" | "completed" } = {}) {
  const all: any[] = [];
  let skip = 0;
  const limit = 100;

  while (true) {
    const page = await listRuns({ limit, skip, ...opts });
    all.push(...page.batches);
    if (!page.hasMore) break;
    skip += limit;
  }
  return all;
}
List responses echo only the first task’s URL/instruction into results[0] as a stub. To inspect every task in a run, fetch it by id with GET /:id.

Authorizations

​
Authorization
string
header
default:YOUR_API_KEY
required

API key for authentication. Get your API key from https://pre.dev/projects/playground (Solo) or https://pre.dev/enterprise/dashboard?page=api (Enterprise). Use format: Bearer YOUR_API_KEY

Query Parameters

​
limit
integer
default:50
Required range: 1 <= x <= 100
​
skip
integer
default:0
Required range: x >= 0
​
status
enum<string>
Available options:
processing,
completed

Response

Paginated list of runs owned by this API key.

​
batches
object[]

Run summaries (field is named batches for backwards compatibility).

​
total
integer

Total matching runs, ignoring limit/skip.

​
hasMore
boolean

True when skip + limit < total.