# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Matomo Reporting API for plugin Media Analytics API
  version: 1.0.0
extends: openapi/matomo-mediaanalytics-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/index.php?module=API&method=MediaAnalytics.get'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the media analytics overview
      effect: read
      questions:
      - How many video and audio plays did my site get last week?
      - What are the headline media engagement numbers for a period?
      instructions:
      - text: Get the media analytics overview for site {idSite} for {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show only the columns {columns} of the media overview for site {idSite}, {date} by {period}.
        slots:
          columns: query.columns
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getCurrentNumPlays'].get
  update:
    x-apievangelist-phrasing:
      intent: Count media plays in the last few minutes
      effect: read
      questions:
      - How many videos or audio files are being played on my site right now?
      - What's the real-time play count for the last half hour?
      instructions:
      - text: Count media plays on site {idSite} in the last {lastMinutes} minutes.
        slots:
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      - text: Tell me the live number of plays for site {idSite} over the past {lastMinutes} minutes in segment {segment}.
        slots:
          idSite: query.idSite
          lastMinutes: query.lastMinutes
          segment: query.segment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getCurrentSumTimeSpent'].get
  update:
    x-apievangelist-phrasing:
      intent: Get total watch time in the last few minutes
      effect: read
      questions:
      - How much total time have visitors spent watching media in the last hour?
      - What is the real-time sum of seconds watched on my site?
      instructions:
      - text: Get total seconds of media watched on site {idSite} in the last {lastMinutes} minutes.
        slots:
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      - text: Sum the live watch time for site {idSite} across the past {lastMinutes} minutes.
        slots:
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getCurrentMostPlays'].get
  update:
    x-apievangelist-phrasing:
      intent: List the most played media right now
      effect: read
      questions:
      - Which videos are trending on my site in the last few minutes?
      - What are the top played media items in real time?
      instructions:
      - text: List the most played media on site {idSite} in the last {lastMinutes} minutes.
        slots:
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      - text: Show the top {filter_limit} trending media items on site {idSite} from the past {lastMinutes} minutes.
        slots:
          filter_limit: query.filter_limit
          idSite: query.idSite
          lastMinutes: query.lastMinutes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getVideoResources'].get
  update:
    x-apievangelist-phrasing:
      intent: Report on video resource URLs
      effect: read
      questions:
      - Which video file URLs were played most on my site?
      - Can I see video plays broken down by the media resource URL?
      instructions:
      - text: Report video plays by resource URL for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show a flat list of video resource URLs for site {idSite} in {date} ({period}) with flat={flat}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          flat: query.flat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getAudioResources'].get
  update:
    x-apievangelist-phrasing:
      intent: Report on audio resource URLs
      effect: read
      questions:
      - Which audio file URLs were played most on my site?
      - Can I see podcast or audio plays broken down by resource URL?
      instructions:
      - text: Report audio plays by resource URL for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show a flat list of audio resource URLs for site {idSite} in {date} ({period}) with flat={flat}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          flat: query.flat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getVideoTitles'].get
  update:
    x-apievangelist-phrasing:
      intent: Report video performance by title
      effect: read
      questions:
      - Which video titles got the most plays and engagement?
      - What are the metrics for each video by its title?
      instructions:
      - text: Show video titles with their metrics for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Rank videos by title on site {idSite} for {date} ({period}) with secondary dimension {secondaryDimension}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          secondaryDimension: query.secondaryDimension
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getAudioTitles'].get
  update:
    x-apievangelist-phrasing:
      intent: Report audio performance by title
      effect: read
      questions:
      - Which audio titles or podcast episodes got the most listens?
      - What are the metrics for each audio track by its title?
      instructions:
      - text: Show audio titles with their metrics for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Rank audio tracks by title on site {idSite} for {date} ({period}) with secondary dimension {secondaryDimension}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          secondaryDimension: query.secondaryDimension
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getGroupedVideoResources'].get
  update:
    x-apievangelist-phrasing:
      intent: Report video plays by grouped resource URL
      effect: read
      questions:
      - Can I see video resource URLs grouped together instead of one row per file?
      - What are the aggregated metrics for grouped video resources?
      instructions:
      - text: Show grouped video resource URLs with metrics for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Aggregate video plays by grouped resource on site {idSite} in {date} ({period}) for segment {segment}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          segment: query.segment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getGroupedAudioResources'].get
  update:
    x-apievangelist-phrasing:
      intent: Report audio plays by grouped resource URL
      effect: read
      questions:
      - Is there a rolled-up view of audio file URLs rather than a row for each one?
      - What are the aggregated metrics for grouped audio resources?
      instructions:
      - text: Show grouped audio resource URLs with metrics for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Aggregate audio plays by grouped resource on site {idSite} in {date} ({period}) for segment {segment}.
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
          segment: query.segment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getVideoHours'].get
  update:
    x-apievangelist-phrasing:
      intent: Show video plays by hour of day
      effect: read
      questions:
      - At what time of day do visitors watch the most videos?
      - Which hours see the highest video plays?
      instructions:
      - text: Break down video plays by hour for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show hourly video viewing on site {idSite} for {date} ({period}).
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getAudioHours'].get
  update:
    x-apievangelist-phrasing:
      intent: Show audio plays by hour of day
      effect: read
      questions:
      - At what time of day do visitors listen to the most audio?
      - Which hours see the highest audio plays?
      instructions:
      - text: Break down audio plays by hour for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Show hourly audio listening on site {idSite} for {date} ({period}).
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getVideoResolutions'].get
  update:
    x-apievangelist-phrasing:
      intent: Show video plays by player resolution
      effect: read
      questions:
      - What player sizes are my videos watched at?
      - Do people watch my videos in full HD or smaller embeds?
      instructions:
      - text: Show video plays grouped by player resolution for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: Break down video viewing on site {idSite} by player dimensions for {date} ({period}).
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'
- target: $.paths['/index.php?module=API&method=MediaAnalytics.getPlayers'].get
  update:
    x-apievangelist-phrasing:
      intent: Show media plays by player name
      effect: read
      questions:
      - Which media players are used to play content on my site?
      - How are plays split between embedded players versus HTML5?
      instructions:
      - text: Show media plays grouped by player name for site {idSite}, {period} {date}.
        slots:
          idSite: query.idSite
          period: query.period
          date: query.date
      - text: List which players served media on site {idSite} in {date} ({period}).
        slots:
          idSite: query.idSite
          date: query.date
          period: query.period
      method: generated
      generated: '2026-10-01'