Sign in

v34

latestOpenAPI 3.0.0raw.githubusercontent.com2026-07-215423105.7 KB

Run an Agent

Run a browser agent to complete the task by using web search and browser tooling. Optionally pass agentId to run a custom agent you've created.

post/v1/agents/runs

Request body

agentIdstring

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

taskstring required

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

resultSchemaobject

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.

variablesobject

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

The agent run has been created in pending state.

runIdstring required

Unique identifier for the run.

agentIdstring

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

taskstring required

The original task description.

status'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'STOPPED' | 'TIMED_OUT' 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
sessionIdstring

The Browserbase session ID powering this run.

sandboxIdstring

External sandbox identifier assigned by the runner. Optional.

resultSchemaobject

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

resultobject

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.

startedAtstring date-time
endedAtstring date-time
createdAtstring date-time required
updatedAtstring date-time required