# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mux Metrics API
  version: 1.0.0
extends: openapi/mux-com-metrics-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: 5
- target: $.paths['/data/v1/metrics/{METRIC_ID}/breakdown'].get
  update:
    x-apievangelist-phrasing:
      intent: Break a metric down by a dimension
      effect: read
      questions:
      - Which countries have the worst rebuffering on my videos?
      - Can I group a quality metric by browser or device over a timeframe?
      instructions:
      - text: Break down metric {metric_id} by {group_by}.
        slots:
          metric_id: path.METRIC_ID
          group_by: query.group_by
      - text: Show metric {metric_id} grouped by {group_by} over {timeframe}, sorted by {order_by}.
        slots:
          metric_id: path.METRIC_ID
          group_by: query.group_by
          timeframe: query.timeframe[]
          order_by: query.order_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data/v1/metrics/{METRIC_ID}/overall'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a metric's overall value
      effect: read
      questions:
      - What's my overall video startup time compared to the Mux global average?
      - How many total views and watch time went into a metric's overall score?
      instructions:
      - text: Get the overall value of metric {metric_id}.
        slots:
          metric_id: path.METRIC_ID
      - text: Show the overall {measurement} of metric {metric_id} over {timeframe}.
        slots:
          measurement: query.measurement
          metric_id: path.METRIC_ID
          timeframe: query.timeframe[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data/v1/metrics/{METRIC_ID}/insights'].get
  update:
    x-apievangelist-phrasing:
      intent: Find what hurts a metric most
      effect: read
      questions:
      - Which segments of my audience are dragging down playback quality the most?
      - What are the worst-performing values for a metric across all breakdowns?
      instructions:
      - text: List insights for metric {metric_id}.
        slots:
          metric_id: path.METRIC_ID
      - text: Show the worst-performing breakdowns for metric {metric_id} over {timeframe}.
        slots:
          metric_id: path.METRIC_ID
          timeframe: query.timeframe[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data/v1/metrics/{METRIC_ID}/timeseries'].get
  update:
    x-apievangelist-phrasing:
      intent: Chart a metric over time
      effect: read
      questions:
      - How has my rebuffer percentage trended over the past week?
      - Can I get a metric's values bucketed by hour or day?
      instructions:
      - text: Get timeseries data for metric {metric_id}.
        slots:
          metric_id: path.METRIC_ID
      - text: Chart metric {metric_id} over {timeframe} grouped by {group_by}.
        slots:
          metric_id: path.METRIC_ID
          timeframe: query.timeframe[]
          group_by: query.group_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/data/v1/metrics/comparison'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare all metrics for one dimension value
      effect: read
      questions:
      - For a single browser or country, what do all my quality metrics look like?
      - Can I compare every metric's value for one dimension value side by side?
      instructions:
      - text: List all metric values where {dimension} is {value}.
        slots:
          dimension: query.dimension
          value: query.value
      - text: Compare every metric for {dimension} {value} over {timeframe}.
        slots:
          dimension: query.dimension
          value: query.value
          timeframe: query.timeframe[]
      method: generated
      generated: '2026-09-26'