Skip to main content
pre.dev
Changelogpre.devStart building
Start with pre.devBuild with pre.devAPI & SDKsLabs

Browser Agents

Get run status and results

Retrieve a browser run, individual task outcomes, retry counts, and optional execution timelines.

gethttps://api.pre.dev/browser-agent/{id}Try it

Use the id returned by task submission. A run is also called a batch in the API and SDK types.

curl --fail-with-body "https://api.pre.dev/browser-agent/$BATCH_ID" \
  -H "Authorization: Bearer $PREDEV_API_KEY"

Batch and task states

Batch status is processing, completed, or failed. Stop polling on either terminal state. A completed batch may contain unsuccessful tasks.

Browser task states and charges: submission charges the per-task floor, PENDING and RUNNING add nothing, SUCCESS, BLOCKED, CAPTCHA_FAILED, TIMEOUT, LOOP, and NO_TARGET are metered at the floor or more, and ERROR and EXHAUSTED keep the floor and nothing more.
Task statusMeaningCharge
PENDINGWaiting to runThe floor, charged at submission
RUNNINGExecution has startedNothing more; a retried attempt adds no charge
SUCCESSThe task succeededThe floor, plus any usage above it
BLOCKEDThe site blocked the taskThe floor, plus any usage above it
CAPTCHA_FAILEDA challenge could not be completedThe floor, plus any usage above it
TIMEOUTThe execution budget expiredThe floor, plus any usage above it
LOOPRepeated actions prevented progressThe floor, plus any usage above it
NO_TARGETThe requested target or usable result was not foundThe floor, plus any usage above it
ERRORAnother execution failure; read errorThe floor and nothing more
EXHAUSTEDThe run stopped responding before it finished, and no retry could finish it in timeThe floor and nothing more

Every browser task is charged a 0.1-credit floor when you submit it, so you need available credits to start. When the task finishes, it is charged any usage above the floor, whether it succeeded or not. Only an ERROR or EXHAUSTED task keeps the floor and nothing more.

In-progress results

results is aligned to task order. An entry can be a terminal result, a PENDING/RUNNING stub, or null when task details are unavailable. Pending entries need not include data, durationMs, or creditsUsed.

The detail response counts result slots in completed, including synthesized entries. Use status, not completed === total or array length, to decide whether the run is finished.

Additional fields can include:

FieldMeaning
name / taskNamesGenerated display names, when available
results[i].attemptsExecution attempts; greater than one indicates a retry
results[i].queuePositionAdvisory position for pending work; zero for running work, or null if unavailable
results[i].instruction, input, outputOriginal task inputs when available
totalCreditsUsedSum of reported task credit usage

Inspect task status before using data. Treat display names, queue position, and timestamps as optional.

Event timeline

Set includeEvents=true when you need execution evidence:

curl --fail-with-body "https://api.pre.dev/browser-agent/$BATCH_ID?includeEvents=true" \
  -H "Authorization: Bearer $PREDEV_API_KEY"

results[i].events contains available task events. liveEvents[i] can contain events for unfinished tasks; completed slots can be empty arrays. These fields can remain present after batch completion.

An event uses { type, timestamp, iteration?, data }, where timestamp is Unix time in milliseconds. Types include navigation, plan, action, screenshot, validation, done, error, and lifecycle events. Accept unfamiliar event types and inspect their payloads instead of assuming a closed list.

Screenshot payloads can contain inline image data rather than a URL. Events vary by execution path and are not guaranteed for every step. Timelines can be large, so omit them from routine status checks. The existing-run stream provides a snapshot followed by live updates.

Errors

StatusWhen
400id is not a valid run ID
401Missing or invalid key
404No run with this ID in your account

Each status has an example body in the response examples. See errors and retries.

curl -X GET "https://api.pre.dev/browser-agent/string"
fetch("https://api.pre.dev/browser-agent/string", {  method: "GET"})
package mainimport (  "fmt"  "net/http"  "io/ioutil")func main() {  url := "https://api.pre.dev/browser-agent/string"  req, _ := http.NewRequest("GET", url, nil)  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}
import requestsurl = "https://api.pre.dev/browser-agent/string"response = requests.request("GET", url)print(response.text)
import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://api.pre.dev/browser-agent/string"))  .GET()  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}
using System;using System.Net.Http;using System.Text;var client = new HttpClient();var response = await client.GetAsync("https://api.pre.dev/browser-agent/string");var responseBody = await response.Content.ReadAsStringAsync();
use reqwest::{Result, Client};async fn main() -> Result<()> {  let client = Client::new();  let url = "https://api.pre.dev/browser-agent/string";  let res = client    .get(url)    .send()    .await?    .text()    .await?;  println!("{}", res);  Ok(())}

{  "id": "507f1f77bcf86cd799439011",  "total": 1,  "completed": 1,  "results": [    {      "url": "https://example.com",      "status": "RUNNING",      "queuePosition": 0,      "attempts": 1    }  ],  "totalCreditsUsed": 0,  "status": "processing"}

GET
/browser-agent/{id}

Authorization

AuthorizationBearer <token>

Your pre.dev workspace API key (pdk_...) from Integrations, Built-in tab: https://pre.dev/projects/integrations?tab=built-in

In: header

Path Parameters

id*string

24-character record ID.

Match^[a-fA-F0-9]{24}$

Query Parameters

includeEvents?boolean
Defaultfalse

Response Body

application/json

Batch with available results and optional events.

TypeScript Definitions

Use the response body type in TypeScript.

application/json

application/json

application/json

application/json

Was this page helpful?

postRun browser tasks

Previous Page

getStream an existing run

Next Page