---
title: "Run an Agent"
method: POST
path: "/v1/agents/runs"
---

# Run an Agent

`POST /v1/agents/runs`

Run a browser agent to complete the `task` by using web search and browser tooling. Optionally pass `agentId` to run a [custom agent](/reference/api/create-an-agent) you've created.

## Request body

- object
  - `agentId` string — Optionally run a specific [custom agent](/reference/api/create-an-agent) you've created by ID. The run will use the agent's `systemPrompt` and `resultSchema` unless overridden.
  - `task` string, required — A natural language description of the task the agent should accomplish.
  - `resultSchema` object — An optional [JSON Schema](https://json-schema.org/specification) 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.
    - `context` object
      - `id` string, required — The Context ID.
      - `persist` boolean — Whether to persist the context after browsing. Defaults to false.
    - `proxies` boolean — Set true to route the agent's browser session through the default proxy.
    - `verified` boolean — Set true to enable Browserbase Verified for the session.
  - `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`

The agent run has been created in `pending` state.

- AgentRun — 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.
  - `agentId` string — The ID of the agent applied to this run, if any. Omitted for ad-hoc runs.
  - `task` string, 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
  - `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](https://json-schema.org/specification) 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](https://json-schema.org/specification) when one is set.
  - `cause` object
    - `code` string, required — Structured failure code (e.g., RUNNER_HEARTBEAT_LOST).
    - `message` string — Human-readable failure detail.
  - `startedAt` string, date-time
  - `endedAt` string, date-time
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

---

[API](https://skmtc.net/browserbase/apis/browserbase-api.md) · [All operations](https://skmtc.net/browserbase/apis/browserbase-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/browserbase/browserbase-api/versions/832b22144edf/schema)