API Reference

Jobs

Jobs execute saved automations. Use these endpoints to start a run, poll its public status and result payload, or permanently purge it.

Endpoints

Jobs are immutable execution records for an automation. Create a separate job every time you want to execute an automation, then poll it for status and result fields.

POSThttps://api.browserfleet.dev/api/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.

Example Request

curl -X POST "https://api.browserfleet.dev/api/jobs" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "automationId": "jh7d9...",
    "priority": 10,
    "variables": { "%portalUrl": "https://example.com/registry" }
  }'

201 Created

{
  "automationId": "jh7d9...",
  "jobId": "km2q8...",
  "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 request body", "issues": { ... } }	The request body is malformed or cannot be validated.
400	{ "error": "Invalid request body", "issues": { ... } }	The JSON body does not include a valid automationId string.
401	{ "error": "Unauthorized" } or { "error": "Invalid API key" }	The request is not authenticated.
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": "Agent keys are not configured. Set the OpenCode Go and Cursor keys in Settings." }	The organization has not stored both agent keys. Add the OpenCode Go and Cursor keys on the dashboard Settings page, then start the job again.
422	{ "error": "Automation must use flat text steps, a flat typed output, and unique safe storage filenames" }	The saved automation uses a legacy contract. Create a replacement automation, then delete the legacy definition when it is no longer needed.

GEThttps://api.browserfleet.dev/api/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 "https://api.browserfleet.dev/api/jobs?jobId=km2q8..." \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK

{
  "automationId": "jh7d9...",
  "createdAt": "2026-06-17T10:01:00.000Z",
  "error": null,
  "jobId": "km2q8...",
  "priority": 10,
  "result": {
    "data": {},
    "storage": [
      {
        "name": "dataset.csv",
        "id": "st7p9..."
      }
    ]
  },
  "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.
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 resolves every requested name to its storage id. When multiple files share one archive, each name carries the same archive 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 }[]	Browser command history stored inline. The array is empty when no browser turn was available.
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": "Unauthorized" } or { "error": "Invalid API key" }	The request is not authenticated.
404	{ "error": "Job not found" }	The job id could not be found.

DELETEhttps://api.browserfleet.dev/api/jobs?jobId={jobId}

Purge Job

Deletes every current or legacy stored artifact linked to a job, then deletes the job.

Purge Job request fields
Field	Location	Type	Required	Description
jobId	Query String	string	Yes	Job id to purge.

Example Request

curl -X DELETE "https://api.browserfleet.dev/api/jobs?jobId=km2q8..." \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK

{
  "deleted": true,
  "jobId": "km2q8...",
  "purgedFileCount": 1
}

Purge Job response fields
Field	Type	Description
deleted	boolean	Always true when the purge succeeds.
jobId	string	Deleted job id.
purgedFileCount	number	Number of stored job artifacts deleted before the job.

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