> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pre.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# List Tasks
> Paginate over every browser-agent task submission your API key has created. Filter by status, control page size with limit/skip.
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](/browser-agents/api/run-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
```typescript theme={null}
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`](/browser-agents/api/task-status) 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
```bash theme={null}
curl "https://api.pre.dev/list-browser-agents?limit=10&status=completed" \
-H "Authorization: Bearer $PREDEV_API_KEY"
```
```json theme={null}
{
"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
```python theme={null}
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
```javascript theme={null}
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
```typescript theme={null}
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`](/browser-agents/api/task-status).
## OpenAPI
````yaml GET /list-browser-agents
openapi: 3.1.0
info:
title: pre.dev Architect API
description: >-
Generate comprehensive software specifications for coding agents. The
Architect API helps you create detailed project specifications that AI
coding agents can understand and implement.
version: 1.1.0
contact:
name: pre.dev Support
url: https://pre.dev
email: support@pre.dev
license:
name: Proprietary
url: https://pre.dev/terms
servers:
- url: https://api.pre.dev
description: Production API Server
security:
- apiKeyAuth: []
tags:
- name: Spec Generation
description: Generate comprehensive software specifications for AI coding agents
- name: Status
description: Check status of asynchronous specification processing
- name: Spec Management
description: List and search existing specifications
- name: Account
description: Manage user account and credits
- name: Batches
description: Submit and retrieve browser-agent task batches
paths:
/list-browser-agents:
get:
tags:
- Batches
summary: List your runs
description: Paginated list of batches this API key has run.
operationId: listRuns
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: skip
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
- name: status
in: query
required: false
schema:
type: string
enum:
- processing
- completed
responses:
'200':
description: Paginated list of runs owned by this API key.
content:
application/json:
schema:
type: object
properties:
batches:
type: array
description: >-
Run summaries (field is named `batches` for backwards
compatibility).
items:
$ref: '#/components/schemas/BatchResult'
total:
type: integer
description: Total matching runs, ignoring limit/skip.
hasMore:
type: boolean
description: True when `skip + limit < total`.
'401':
description: Missing or invalid bearer token.
components:
schemas:
BatchResult:
type: object
description: >-
Run summary. The schema is named `BatchResult` for backwards
compatibility with older clients.
properties:
id:
type: string
description: Run id (24-char Mongo ObjectId).
total:
type: integer
description: Total tasks in the run.
completed:
type: integer
description: Number of tasks that have finished (any status).
results:
type: array
description: >-
Per-task results aligned by `taskIndex`. In-progress runs return
PENDING stubs for tasks that haven't started; the stub has only
`url`, `instruction`, `input`, and `status: "PENDING"`.
items:
$ref: '#/components/schemas/TaskResult'
totalCreditsUsed:
type: number
description: Sum of credits billed across all tasks in the run.
status:
type: string
enum:
- processing
- completed
- failed
createdAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
description: Populated once `status !== "processing"`.
liveEvents:
type: array
description: >-
Only present when `includeEvents=true` on `GET /:id`. Per-task
in-flight event streams for tasks that haven't yet finished. Aligned
by index with `results`; completed tasks get an empty array.
items:
type: array
items:
$ref: '#/components/schemas/RunnerEvent'
error:
type: string
description: Set only when `status === "failed"`.
TaskResult:
type: object
properties:
url:
type: string
instruction:
type: string
input:
type: object
additionalProperties:
type: string
status:
type: string
description: Only `SUCCESS` is billed; every failure mode is free.
enum:
- SUCCESS
- PENDING
- ERROR
- TIMEOUT
- BLOCKED
- CAPTCHA_FAILED
- LOOP
- NO_TARGET
data:
description: >-
Extracted data, validated against the task's `output` schema. `null`
when no `output` was specified or the task failed.
creditsUsed:
type: number
description: >-
Credits billed for this task. 1 credit = $0.10. Floor 0.1 for
SUCCESS, scales up with task complexity. Zero for non-SUCCESS
statuses.
durationMs:
type: integer
description: Wall-clock runtime of the task.
error:
type: string
description: Failure reason, populated when `status` is not `SUCCESS`.
events:
type: array
description: >-
Full per-step event timeline. Only present when the caller requested
`includeEvents=true`.
items:
$ref: '#/components/schemas/RunnerEvent'
RunnerEvent:
type: object
description: >-
One step in the agent's execution. Internal fields (sandbox provider,
LLM model, token counts) are stripped before the event is returned.
properties:
type:
type: string
enum:
- navigation
- plan
- action
- screenshot
- validation
- done
- error
data:
type: object
description: >-
Event-specific payload. See the Get a Run docs for per-type field
lists.
ts:
type: string
format: date-time
securitySchemes:
apiKeyAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
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
x-default: YOUR_API_KEY
````