# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Browser Use Public API v4 Runs API
  version: 1.0.0
extends: openapi/browser-use-runs-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List agent runs
      effect: read
      questions:
      - What agent runs have I started recently?
      - Can I see only the runs that belong to one session?
      instructions:
      - text: List the agent runs in session {session_id}.
        slots:
          session_id: query.sessionId
      - text: Show the next {limit} runs after cursor {cursor}.
        slots:
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an agent run on a task
      effect: write
      questions:
      - How do I start an agent run that works through a browser task for me?
      - Can I cap how much a single run is allowed to spend?
      - Is it possible to attach uploaded files or a workspace to a new run?
      instructions:
      - text: Start a run to {task} using model {model}.
        slots:
          task: requestBody.task
          model: requestBody.model
      - text: Launch a run to {task} with a spending cap of {max_cost} dollars.
        slots:
          task: requestBody.task
          max_cost: requestBody.maxCostUsd
      - text: Run {task} in session {session_id} with workspace {workspace_id}.
        slots:
          task: requestBody.task
          session_id: requestBody.sessionId
          workspace_id: requestBody.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/runs/{run_id}/attachments'].get
  update:
    x-apievangelist-phrasing:
      intent: List files attached to a run
      effect: read
      questions:
      - Which uploaded files were attached to an agent run?
      - Can I see a run's attachments in the order they were attached?
      instructions:
      - text: List the attachments on run {run_id}.
        slots:
          run_id: path.run_id
      - text: Show which files I attached when I started run {run_id}.
        slots:
          run_id: path.run_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/runs/{run_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a run's full summary and result
      effect: read
      questions:
      - How do I get the full result and task text of a finished run?
      - Where can I read the complete summary of an agent run once it's done?
      instructions:
      - text: Get the full summary and result of run {run_id}.
        slots:
          run_id: path.run_id
      - text: Show everything about run {run_id}, including what it returned.
        slots:
          run_id: path.run_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/runs/{run_id}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Poll a run's status
      effect: read
      questions:
      - What's the lightest way to poll whether a run has finished?
      - Has my agent run reached a terminal state yet?
      instructions:
      - text: Poll the status of run {run_id} until it completes, fails or is cancelled.
        slots:
          run_id: path.run_id
      - text: Check just the status of run {run_id}.
        slots:
          run_id: path.run_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/runs/{run_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an in-flight run
      effect: destructive
      questions:
      - How do I cancel an agent run so it stops billing my project?
      - What happens if I cancel a run that has already completed?
      instructions:
      - text: Cancel run {run_id} now.
        slots:
          run_id: path.run_id
      - text: Stop the in-progress run {run_id} before it spends any more.
        slots:
          run_id: path.run_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/runs/{run_id}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a run's event stream
      effect: read
      questions:
      - How can I follow the step-by-step events of an agent run?
      - Can I fetch only the run events newer than the last one I saw?
      instructions:
      - text: Get the events for run {run_id} after event {after}.
        slots:
          run_id: path.run_id
          after: query.after
      - text: 'Show up to {limit} events from run {run_id} with output included: {include_output}.'
        slots:
          limit: query.limit
          run_id: path.run_id
          include_output: query.include_output
      method: generated
      generated: '2026-09-26'