Skip to main content
POST
/
v1
/
agents
/
runs
Run an Agent
curl --request POST \
  --url https://api.browserbase.com/v1/agents/runs \
  --header 'Content-Type: application/json' \
  --header 'X-BB-API-Key: <api-key>' \
  --data '
{
  "task": "<string>",
  "agentId": "<string>",
  "resultSchema": {},
  "browserSettings": {
    "proxies": true,
    "verified": true
  },
  "variables": {}
}
'
{
  "runId": "<string>",
  "task": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "agentId": "<string>",
  "sessionId": "<string>",
  "sandboxId": "<string>",
  "resultSchema": {},
  "result": {},
  "cause": {
    "code": "<string>",
    "message": "<string>"
  },
  "startedAt": "2023-11-07T05:31:56Z",
  "endedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
X-BB-API-Key
string
header
required

Your Browserbase API Key.

Body

application/json
​
task
string
required

A natural language description of the task the agent should accomplish.

Minimum string length: 1
​
agentId
string

Optionally run a specific custom agent you've created by ID. The run will use the agent's systemPrompt and resultSchema unless overridden.

​
resultSchema
object

An optional JSON Schema object. If provided, the agent will aim to return a result that conforms to this schema when the run completes. Overrides the referenced agent's default resultSchema for this run only.

​
browserSettings
object

Browser configuration for the agent's session. When omitted, runner defaults apply.

​
variables
object

Optional named variables the agent can reference as placeholders, i.e. %variable%. Each entry pairs a value the placeholder resolves to with an optional description that hints to the agent when it should be used. Values are not persisted.

Response

201 - application/json

The agent run has been created in pending state.

One execution of an agent against a task. Created in pending and transitioned through running → completed/failed by the runner.

​
runId
string
required

Unique identifier for the run.

​
task
string
required

The original task description.

​
status
enum<string>
required

Current status of the run.

  • PENDING - agent will run soon
  • RUNNING - agent is currently running
  • COMPLETED - agent has finished running
  • FAILED - agent has failed the run
  • STOPPED - run was stopped by the user
  • TIMED_OUT - run exceeded maximum time
Available options:
PENDING,
RUNNING,
COMPLETED,
FAILED,
STOPPED,
TIMED_OUT
​
createdAt
string<date-time>
required
​
updatedAt
string<date-time>
required
​
agentId
string

The ID of the agent applied to this run, if any. Omitted for ad-hoc runs.

​
sessionId
string

The Browserbase session ID powering this run.

​
sandboxId
string

External sandbox identifier assigned by the runner. Optional.

​
resultSchema
object

Per-run JSON Schema override for the result shape. When unset, the agent's default resultSchema applies.

​
result
object

The agent's structured result for the run. Only present when the run has finished and output is available. The result conforms to the provided JSON Schema when one is set.

​
cause
object
​
startedAt
string<date-time>
​
endedAt
string<date-time>