API Reference

Jobs

A job runs a saved automation. Start a job, then retrieve its status and results.

Job Lifecycle

POST /rest/public/jobs creates a job for one automation. The job carries its own variables and uses 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 retrieve this job's status and results.

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

Retrieve the job until its status is Done or Error.

Pending

Browser Fleet accepted the job and queued it for execution.

In Progress

Browser Fleet is executing or verifying the run.

Done | Error

Stop polling when the job is Done or Error.

When Results Are Final

A job is finished when its status is Done or Error. Keep polling while its status is Pending or In Progress.

Pending

The job is queued, or a failed run is waiting to run again. Its result is null.

In Progress

The job is running or its result is being verified. Its result is still null. A run that has not finished two hours after it starts fails with runtime_error.

Retries

A failed run returns the job to Pending, and Browser Fleet runs it again, up to three runs in total; a run that Cursor itself fails is not counted. Each run gets its own two hours, runStartAt shows the newest run's start, and only the first run is billed.

Done

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

Error

All three runs failed. The result is null, and error holds the stable code and diagnostic trace of the last run.

site_unreachable

The website could not be reached, or it did not load during the job.

unable_to_complete_job

The website loaded, but the steps, the requested values, or a requested file could not be completed.

agent_keys_missing

Your organization's configuration changed after the job was created and now has some parts but not all, or no cursor key or llm, so none of its runs could start. Set every part, or send an empty configuration to run on Browser Fleet, with PUT /configuration, then start a new job.

runtime_error

The last run's failure did not fit a more specific error category, including a run that passed the two-hour limit.

{
  "status": "Error",
  "result": null,
  "error": {
    "code": "site_unreachable",
    "trace": [
      {
        "timestamp": "2026-07-19T14:20:31.000Z",
        "command": "scraper result",
        "output": "The page at https://example.com/registry did not load."
      }
    ]
  }
}

Error Trace

A failed job's error object includes a trace that explains why the job stopped. The wording of trace entries can change.

can be empty

The trace array is empty when the job failed before it started, for example when agent keys are missing.

timestamp, command, output

Each entry records when it was written, the stage that wrote it, and its message.

inline JSON

The trace is part of the job's error object; it is not a stored file and needs no second request.

[
  {
    "timestamp": "2026-07-19T14:20:31.000Z",
    "command": "scraper result",
    "output": "The Export CSV button was not shown on the page."
  }
]

Endpoints

A job is one run of an automation. Start a job and poll it for its status and results.

POSThttps://api.browserfleet.dev/rest/public/jobs

Start Job

Creates a pending job for an automation.

Start Job request fields
Field	Location	Type	Required	Description
automationId	JSON Body	string	Yes	Automation id to execute.
priority	JSON Body	integer	No	Non-negative queue priority. Higher values run first; omitted priorities default to 0.
variables	JSON Body	object	No	Optional string replacements keyed by the literal tokens used in task and step text, for example %portalUrl.
metadata	JSON Body	object	No	Your own JSON object, stored unchanged and returned by retrieve job and the job.finished webhook, for example the record the job belongs to. The scraper never sees it. Omitted metadata is stored as {}.

Example Request (cURL)

curl -X POST "https://api.browserfleet.dev/rest/public/jobs" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
    "priority": 10,
    "variables": { "%portalUrl": "https://example.com/registry" }
  }'

201 Created Response (JSON)

{
  "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
  "jobId": "7b2e4d9a-1c3f-4e8b-a6d5-0f9c2b8e3a71",
  "priority": 10,
  "status": "Pending"
}

Start Job response fields
Field	Type	Description
automationId	string	Automation id attached to the job.
jobId	string	Public job id used for status polling.
priority	integer	Accepted queue priority.
status	string	Initial job status. New jobs return Pending.

Start Job error responses
Status	Body	Meaning
400	{ "error": "Invalid or missing JSON body" }	The request body is missing or is not valid JSON.
400	{ "error": "Invalid request body", "issues": { ... } }	The JSON body lacks an automationId string, has an invalid priority, variables, or metadata field, or has a field that start job does not accept.
401	{ "error": "Invalid API key" }	The API key is missing or invalid.
402	{ "error": "No active subscription" } or { "error": "Could not verify subscription" }	Billing must be active before jobs can be started.
404	{ "error": "Automation not found" }	The automation id could not be found.
422	{ "error": "Configuration is incomplete. Set every part (browsers, cloud_infrastructure, llm, stealth, network) with PUT /rest/public/configuration, or remove them all to run on Browser Fleet." }	The organization's configuration has some parts but not all. Set every part, or send an empty configuration to run on Browser Fleet, then start the job again.
422	{ "error": "Automation must use flat text steps, a flat typed output, and unique safe storage filenames" }	The automation's stored steps, output, or storage do not meet the current contract. Update the automation, then start the job again.

GEThttps://api.browserfleet.dev/rest/public/jobs?jobId={jobId}

Retrieve Job

Returns a job, including result data when available.

Retrieve Job request fields
Field	Location	Type	Required	Description
jobId	Query String	string	Yes	Job id returned by start job.

Example Request (cURL)

curl "https://api.browserfleet.dev/rest/public/jobs?jobId=7b2e4d9a-1c3f-4e8b-a6d5-0f9c2b8e3a71" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK Response (JSON)

{
  "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
  "createdAt": "2026-06-17T10:01:00.000Z",
  "error": null,
  "jobId": "7b2e4d9a-1c3f-4e8b-a6d5-0f9c2b8e3a71",
  "metadata": {},
  "priority": 10,
  "result": {
    "data": {},
    "storage": [
      {
        "name": "dataset.csv",
        "id": "4f9a2c7e1b3d4a5f8e6c0b9d2a7f1e3c"
      }
    ]
  },
  "status": "Done",
  "updatedAt": "2026-06-17T10:04:00.000Z"
}

Retrieve Job response fields
Field	Type	Description
automationId	string	Automation id attached to the job.
createdAt	string	Creation timestamp as an ISO string.
jobId	string	Job id.
metadata	object	The metadata object sent with start job, or {} when none was sent.
priority	integer	Queue priority assigned when the job was created.
result	{ data: object, storage: array } or null	Done result envelope. Nonterminal and Error jobs return null.
result.data	object	Done contains exactly the output fields requested by the automation, which may be empty.
result.storage	{ name: string, id: string }[]	Done lists each stored file's name with its own storage id.
error	{ code: string, trace: array } or null	Error details for a failed job. Pending, In Progress, and Done jobs return null.
error.code	string	Stable failure category: site_unreachable, unable_to_complete_job, agent_keys_missing, or runtime_error.
error.trace	{ timestamp: string, command: string, output: string }[]	Diagnostic entries that explain why the job stopped. The array is empty when the job failed before it started.
status	string	Public status: Pending, In Progress, Done, or Error. Poll until Done or Error.
updatedAt	string	Last update timestamp as an ISO string.

Retrieve Job error responses
Status	Body	Meaning
400	{ "error": "Missing jobId" }	The jobId query parameter is empty or absent.
401	{ "error": "Invalid API key" }	The API key is missing or invalid.
404	{ "error": "Job not found" }	The job id could not be found.