List Tasks - pre.dev

List your runs

curl --request GET \
  --url https://api.pre.dev/list-browser-agents \
  --header 'Authorization: Bearer <token>'

{
  "batches": [
    {
      "id": "<string>",
      "total": 123,
      "completed": 123,
      "results": [
        {
          "url": "<string>",
          "instruction": "<string>",
          "input": {},
          "data": "<unknown>",
          "creditsUsed": 123,
          "durationMs": 123,
          "error": "<string>",
          "events": [
            {
              "data": {},
              "ts": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ],
      "totalCreditsUsed": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "liveEvents": [
        [
          {
            "data": {},
            "ts": "2023-11-07T05:31:56Z"
          }
        ]
      ],
      "error": "<string>"
    }
  ],
  "total": 123,
  "hasMore": true
}

GET

list-browser-agents

List your runs

curl --request GET \
  --url https://api.pre.dev/list-browser-agents \
  --header 'Authorization: Bearer <token>'

{
  "batches": [
    {
      "id": "<string>",
      "total": 123,
      "completed": 123,
      "results": [
        {
          "url": "<string>",
          "instruction": "<string>",
          "input": {},
          "data": "<unknown>",
          "creditsUsed": 123,
          "durationMs": 123,
          "error": "<string>",
          "events": [
            {
              "data": {},
              "ts": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ],
      "totalCreditsUsed": 123,
      "createdAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "liveEvents": [
        [
          {
            "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: /list-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

Name	Type	Default	Description
`limit`	`integer`	`20`	Page size. `1` ≤ `limit` ≤ `100`. Values outside the range are clamped.
`skip`	`integer`	`0`	Number 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:

Field	Type	Description
`id`	`string`	Run id. Pass to `GET /browser-agent/:id` for full results.
`total`	`integer`	Number of tasks in the run.
`completed`	`integer`	How many tasks have finished.
`results`	`TaskResult[]`	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.
`totalCreditsUsed`	`number`	Running credits total across completed tasks.
`status`	`"processing" \| "completed" \| "failed"`	Current state.
`createdAt`	ISO-8601	Run creation time.
`completedAt`	ISO-8601	Only 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/list-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

Code	Meaning
`200`	OK. Body is the list envelope above.
`401`	Missing or invalid bearer token.

Pagination Patterns

Python — iterate every run

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.pre.dev/list-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/list-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 /browser-agent/: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).

Show child attributes

total

integer

Total matching runs, ignoring limit/skip.

hasMore

boolean

True when skip + limit < total.

Task Status Overview

⌘I

Documentation Index

​Overview

​Query Parameters

​Response

​Example

​Status Codes

​Pagination Patterns

​Python — iterate every run

​Node.js — fetch a single page

​TypeScript — pull all pages

Authorizations

Query Parameters

Response

Overview

Query Parameters

Response

Example

Status Codes

Pagination Patterns

Python — iterate every run

Node.js — fetch a single page

TypeScript — pull all pages