Tasks API reference
Start a hosted agent run inside a session and poll it to a terminal state: request options, TaskRun fields and the separate reviewer verdict.
Last updated:
A task hands the whole loop to Browserberg: you state a goal, the hosted agent plans steps inside your session, and a separate reviewer decides whether the goal was met. The task endpoints below expect the usual dashboard-created API key after Bearer in the authorization header.
/v1/sessions/:id/tasks
Starts a task run in the session and answers 202 immediately; poll the run to its end.
Task request
| Name | Type | Description |
|---|---|---|
task
required
|
string | The goal, up to 4000 characters. |
startUrl
|
string | The page the task starts on. The API OPENS it before the run begins (since 1.4) and anchors the destination guard to its site; a page that cannot be opened answers `422 navigation_failed` and no task is created. With `pinToStartSite` the agent cannot leave that site. |
variables
|
object | Values the task text may reference. |
maxSteps
|
integer |
Step budget, at most 100.
Default: 25
|
maxFailures
|
integer | How many failed steps the run tolerates before giving up. |
pinToStartSite
|
boolean | Removes navigation from the model's action schema entirely, so a page cannot steer the agent off the portal it started on. |
readOnly
|
boolean | Restricts the run to non-mutating actions. |
timeoutSeconds
|
integer | Wall-clock bound on the whole run. |
/v1/tasks/:id
Returns the TaskRun, live while running and final once terminal.
TaskRun fields
| Name | Type | Description |
|---|---|---|
status
|
string | `running` while in flight; terminal values are `completed`, `terminated`, `failed` and `canceled`. |
endedBy
|
string | Why the run ended, finer than `status`: `verified` (completed), `gave_up` (the agent said it cannot) or `not_offered` (the reviewer agrees the site has no such thing) for terminated, and `budget`, `timeout`, `canceled`, `error` for failed. Open enum; absent while running and from servers before 1.4. |
answer
|
string | The agent's answer to the goal, when there is one. |
data
|
array | Everything extract returned along the way. |
steps
|
array | The reasoning trail: `{step, evaluation, memory, nextGoal, actions}` per step. |
verification
|
object | `{isComplete, isTerminate, thoughts}` from a separate reviewer call against a re-scraped page — the agent never certifies its own success. |
notes
|
array | Free-form remarks the run left behind. |
/v1/tasks
Lists your task runs.
/v1/tasks/:id
Cancels a running task; the run finishes with status `canceled`.
Three ways to end
completed means the reviewer confirmed the goal against the re-scraped page. terminated is a conclusion: the agent or the reviewer decided the task should stop — a portal that refuses, a precondition that turns out false. failed is an inability: the run could not proceed within its budgets. Keeping the two apart matters, because a terminated run often carries a useful answer while a failed one usually does not. An organisation runs at most 5 tasks concurrently by default.