List Tasks

List your runs

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

import requests

url = "https://api.pre.dev/list-browser-agents"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.pre.dev/list-browser-agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pre.dev/list-browser-agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pre.dev/list-browser-agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.pre.dev/list-browser-agents")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pre.dev/list-browser-agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

import requests

url = "https://api.pre.dev/list-browser-agents"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.pre.dev/list-browser-agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pre.dev/list-browser-agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pre.dev/list-browser-agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.pre.dev/list-browser-agents")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pre.dev/list-browser-agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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/key (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.

Queue Status & Capacity Browser Agents SDKs

⌘I

Get Started

API Reference

SDKs

Migrations

Overview

Query Parameters

Response

Example

Status Codes

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

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