Guides — Browser Fleet

Guides

Understand the single scraper, flat text steps, variables, automation-owned output and storage contracts, and job lifecycle behind Browser Fleet automations.

Scraper

Each Browser Fleet job opens a fresh browser session and gives one scraper the Automation's complete task, flat steps, input variables, output contract, and storage contract.

Browser Scraper

DSOpenCode GoDeepSeek V4 Flash

Uses the visible portal UI for navigation, forms, full-list views, and browser-native downloads. It returns only the requested output fields and stored files; matching, identity resolution, and other downstream business logic remain with the caller.

Steps

The task states the outcome. Steps are a one-dimensional array of plain-text browser instructions consumed together by the single scraper.

string

Each array item is one plain-text browser instruction.

one dimension

Nested steps, step objects, agent assignments, and skip conditions are not supported.

browser UI

Name the visible portal controls and exact inputs the scraper should use.

no business logic

Do not ask the scraper to generate search variants, resolve identity, filter datasets, or interpret source records.

[
  "Open %portalUrl in the browser.",
  "Click the visible Export all control exactly once as the final browser action."
]

Execution and Order

Array order is binding. One scraper receives the complete array once and executes it in one browser session.

one run

There are no per-step jobs, worker handoffs, or parallel branches.

ordered instructions

Put navigation, interaction, and the final source action in the order they must occur.

exact controls

Prefer portal labels such as Download full list or Export all over general search instructions.

source artifact

Preserve the complete browser-produced file or full-list page without transforming it into downstream business decisions.

Variables

A variable key is the exact token written in an automation task or step. Keep the leading percent sign in both the automation and the job request.

%tokenName

The key must match the referenced token exactly, including capitalization and the leading percent sign.

string values

The public jobs API accepts a string value for every variable key.

references

Use tokens in task text and step strings that depend on job input.

{
  "automationId": "jh7d9...",
  "variables": {
    "%portalUrl": "https://example.com/registry"
  }
}

Output Schema

Automation output is a flat result-data contract. Use an empty object when no structured values are requested, or map each requested field name to its primitive JSON type. The Automation's storage array separately declares the named files every run should preserve.

{}

Dataset extracts return no structured fields, so their automation output is empty.

requested fields

Each property name declares one source-observed value that the completed job must return. Do not request fields that require downstream matching or interpretation.

type labels

Each requested field uses the literal type label boolean, number, or string.

exact keys

Completed data must contain every requested field and no unrequested fields.

Dataset extract:
{}

Requested output values:
{ "match": "boolean", "licenseNumber": "string", "status": "string" }

When Results Are Final

Treat a job as final when its public status is Done or Error. Polling responses remain nonterminal while Browser Fleet is executing and verifying the work.

Pending

The job is queued and normally returns a null result.

In Progress

Execution or result verification is still underway; do not consume the result yet.

Done

The result contains requested structured values under data and each requested file under storage.

Error

The result is null. The Job error contains a stable code and any available browser trace; requested storage is not required on Error.

site_unreachable

The official source could not be reached or read during the required browser navigation.

unable_to_complete_job

The source was reachable, but the requested browser flow, output, or stored artifact could not be completed and verified.

agent_keys_missing

The organization's agent keys were removed after the job was created, so no browser agent could be launched. Set both agent keys in Settings and create the job again.

runtime_error

The failure did not fit a more specific error category.

{
  "status": "Error",
  "result": null,
  "error": {
    "code": "site_unreachable",
    "trace": [
      {
        "timestamp": "2026-07-19T14:20:31.000Z",
        "command": "--session job-km2q8 state",
        "output": "The source portal did not return a usable page."
      }
    ]
  }
}

Error Trace

When browser command turns are available, the Job error includes them inline under trace.

available when captured

The trace array is empty when the failure happened before any browser command turn was available.

timestamp, command, output

Each array item records when one browser command ran, the command, and its output.

inline JSON

The trace is part of the Job error object; it is not uploaded to storage and does not require a second request.

[
  {
    "timestamp": "2026-07-19T14:20:31.000Z",
    "command": "--session job-km2q8 state",
    "output": "Page loaded but the expected export control was unavailable."
  }
]

Job Lifecycle

POST /api/jobs creates a new immutable execution record. A job belongs to one automation, carries that run's variables, and inherits the Automation's output and storage contracts.

Create

Start every execution with a new job, even when the automation and variables are unchanged.

jobId

Use the returned id to poll that specific execution.

priority

Set a non-negative integer when creating a job. Higher values run first, and equal values remain FIFO.

No rerun

Existing jobs are not reset or run again; create another job instead.

Pending -> In Progress -> Done | Error

Poll and Purge

Read the job until it reaches Done or Error. Purging is a separate destructive operation for records you no longer need.

Pending

Browser Fleet accepted the job and queued it for execution.

In Progress

Browser Fleet is executing or verifying the run.

Done | Error

These are the two public terminal statuses and should stop the polling loop.

Purge

Deleting a job also removes every current or legacy stored artifact linked to it.