> ## 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.

# List Runs

> List runs across your account. Supports filtering by status, by the agent they reference, and by creation time.



## OpenAPI

````yaml get /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:
    get:
      summary: List Runs
      description: >-
        List runs across your account. Supports filtering by status, by the
        agent they reference, and by creation time.
      operationId: AgentRuns_list
      parameters:
        - name: status
          in: query
          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
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - RUNNING
              - COMPLETED
              - FAILED
              - STOPPED
              - TIMED_OUT
        - name: agentId
          in: query
          description: Only return runs that reference this agent ID.
          required: false
          schema:
            type: string
        - name: startAt
          in: query
          description: >-
            Only return runs created on or after this timestamp (inclusive). ISO
            8601 / RFC 3339, e.g. 2026-01-19T00:00:00Z.
          required: false
          schema:
            type: string
            format: date-time
        - name: endAt
          in: query
          description: >-
            Only return runs created on or before this timestamp (inclusive).
            ISO 8601 / RFC 3339, e.g. 2026-01-20T00:00:00Z.
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
            default: 20
            maximum: 1000
            minimum: 1
        - name: cursor
          in: query
          description: >-
            Pagination cursor. Pass the nextCursor from the previous response to
            fetch the next page. Omit to start from the first page.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: The page of matching agent runs.
          content:
            application/json:
              schema:
                description: A page of agent runs.
                type: object
                properties:
                  data:
                    description: The page of matching agent runs.
                    type: array
                    items:
                      $ref: '#/components/schemas/AgentRun'
                  limit:
                    description: The maximum number of results returned in this page.
                    type: integer
                  nextCursor:
                    description: >-
                      Cursor for the next page. Pass it back as `cursor` on the
                      next request to continue paging. null when there are no
                      more results.
                    anyOf:
                      - type: string
                    nullable: true
                required:
                  - data
                  - limit
                  - nextCursor
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).

````