> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/reference/api/create-an-agent) you've created.



## OpenAPI

````yaml post /v1/agents/runs
openapi: 3.0.0
info:
  title: Browserbase API
  description: Browserbase API for 3rd party developers
  version: v1
servers:
  - url: https://api.browserbase.com
    description: Public endpoint
    variables: {}
security:
  - BrowserbaseAuth: []
tags: []
paths:
  /v1/agents/runs:
    post:
      summary: Run an Agent
      description: >-
        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.
      operationId: AgentRuns_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  description: >-
                    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.
                  type: string
                task:
                  description: >-
                    A natural language description of the task the agent should
                    accomplish.
                  type: string
                  minLength: 1
                resultSchema:
                  description: >-
                    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.
                  type: object
                  additionalProperties: true
                  properties: {}
                browserSettings:
                  description: >-
                    Browser configuration for the agent's session. When omitted,
                    runner defaults apply.
                  type: object
                  additionalProperties: false
                  properties:
                    context:
                      type: object
                      additionalProperties: false
                      properties:
                        id:
                          description: The Context ID.
                          type: string
                        persist:
                          description: >-
                            Whether to persist the context after browsing.
                            Defaults to false.
                          type: boolean
                      required:
                        - id
                    proxies:
                      description: >-
                        Set true to route the agent's browser session through
                        the default proxy.
                      type: boolean
                    verified:
                      description: Set true to enable Browserbase Verified for the session.
                      type: boolean
                variables:
                  description: >-
                    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.
                  type: object
                  additionalProperties:
                    additionalProperties: false
                    type: object
                    properties:
                      value:
                        description: >-
                          The value the placeholder resolves to when the agent
                          uses it.
                        type: string
                      description:
                        description: >-
                          Optional hint to the agent describing what this
                          variable represents and when to use it.
                        type: string
                    required:
                      - value
              additionalProperties: false
              required:
                - task
      responses:
        '201':
          description: The agent run has been created in `pending` state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRun'
components:
  schemas:
    AgentRun:
      description: >-
        One execution of an agent against a task. Created in `pending` and
        transitioned through `running` → `completed`/`failed` by the runner.
      type: object
      properties:
        runId:
          description: Unique identifier for the run.
          type: string
        agentId:
          description: >-
            The ID of the agent applied to this run, if any. Omitted for ad-hoc
            runs.
          type: string
        task:
          description: The original task description.
          type: string
        status:
          description: |-
            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
          type: string
          enum:
            - PENDING
            - RUNNING
            - COMPLETED
            - FAILED
            - STOPPED
            - TIMED_OUT
        sessionId:
          description: The Browserbase session ID powering this run.
          type: string
        sandboxId:
          description: External sandbox identifier assigned by the runner. Optional.
          type: string
        resultSchema:
          description: >-
            Per-run [JSON Schema](https://json-schema.org/specification)
            override for the result shape. When unset, the agent's default
            `resultSchema` applies.
          type: object
          additionalProperties: true
          properties: {}
        result:
          description: >-
            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.
          type: object
          additionalProperties: true
          properties: {}
        cause:
          type: object
          properties:
            code:
              description: Structured failure code (e.g., RUNNER_HEARTBEAT_LOST).
              type: string
              maxLength: 64
            message:
              description: Human-readable failure detail.
              type: string
              maxLength: 500
          required:
            - code
        startedAt:
          type: string
          format: date-time
        endedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - runId
        - task
        - status
        - createdAt
        - updatedAt
  securitySchemes:
    BrowserbaseAuth:
      type: apiKey
      in: header
      name: X-BB-API-Key
      description: Your [Browserbase API Key](https://www.browserbase.com/settings).

````