Mux Video Views API

openapi: 3.1.0
info:
  title: Mux Animated Images Video Views API
  description: Mux is how developers build online video. This API encompasses both Mux Video and Mux Data functionality to help you build your video-related projects better and faster than ever before.
  version: v1
  contact:
    name: Mux DevEx
    url: https://docs.mux.com
    email: devex@mux.com
servers:
- url: https://api.mux.com
  description: Mux Production API
- url: https://image.mux.com
- url: https://stream.mux.com
- url: https://stats.mux.com
tags:
- name: Video Views
  description: An individual video view tracked by Mux Data. For the full list of properties for each view please refer to the table of data fields in the [Export raw video view data guide](https://docs.mux.com/guides/export-raw-video-view-data).
  x-displayName: Video Views
paths:
  /data/v1/video-views:
    get:
      tags:
      - Video Views
      summary: List Video Views
      description: Returns a list of video views which match the filters and have a `view_end` within the specified timeframe.
      operationId: list-video-views
      servers:
      - url: https://api.mux.com
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/viewer_id'
      - $ref: '#/components/parameters/error_id'
      - $ref: '#/components/parameters/order_direction'
      - $ref: '#/components/parameters/filters'
      - $ref: '#/components/parameters/metric_filters'
      - $ref: '#/components/parameters/timeframe'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVideoViewsResponse'
              example:
                total_row_count: 4
                timeframe:
                - 1610025789
                - 1610112189
                data:
                - viewer_os_family: OS X
                  viewer_application_name: Chrome
                  view_start: '2021-01-07T20:34:06Z'
                  view_end: '2021-01-07T20:46:04Z'
                  video_title: my-title
                  total_row_count: 4
                  player_error_message: null
                  player_error_code: null
                  id: JpA81zBfGaGZ85C6aGF3bptyD4CKwpdNgamr
                  error_type_id: 1
                  country_code: US
                  viewer_experience_score: 0.8
                  watch_time: 1000
                  playback_failure: false
                - viewer_os_family: OS X
                  viewer_application_name: Chrome
                  view_start: '2021-01-07T20:21:53Z'
                  view_end: '2021-01-07T20:34:03Z'
                  video_title: ''
                  total_row_count: 4
                  player_error_message: null
                  player_error_code: null
                  id: jPVLR5giYMrLYbHM88Tkn3cM3qCRDk0jL114
                  error_type_id: 1
                  country_code: US
                  viewer_experience_score: 0.8
                  watch_time: 1000
                  playback_failure: false
                - viewer_os_family: OS X
                  viewer_application_name: Chrome
                  view_start: '2021-01-07T15:16:06Z'
                  view_end: '2021-01-07T15:17:06Z'
                  video_title: Video Test Title 12.14.20
                  total_row_count: 4
                  player_error_message: this is an error message from the player
                  player_error_code: '1001'
                  id: pdLDVKBuPZJJ9YsPVmtmB9FG9gsWBWMmYar4
                  error_type_id: 1
                  country_code: US
                  viewer_experience_score: 0.8
                  watch_time: 1000
                  playback_failure: true
                - viewer_os_family: OS X
                  viewer_application_name: Chrome
                  view_start: '2021-01-07T15:15:09Z'
                  view_end: '2021-01-07T15:15:17Z'
                  video_title: Video Test Title 12.14.20
                  total_row_count: 4
                  player_error_message: null
                  player_error_code: null
                  id: zbZPowWtD3z54jcGMLCJJpF79zCjB03bV7o8
                  error_type_id: 1
                  country_code: US
                  viewer_experience_score: 0.8
                  watch_time: 1000
                  playback_failure: false
      security:
      - accessToken: []
      - authorizationToken: []
  /data/v1/video-views/{VIDEO_VIEW_ID}:
    get:
      tags:
      - Video Views
      summary: Get a Video View
      description: Returns the details of a video view.
      operationId: get-video-view
      servers:
      - url: https://api.mux.com
      parameters:
      - $ref: '#/components/parameters/video_view_id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoViewResponse'
              example:
                total_row_count: null
                timeframe:
                - 1643133378
                - 1643219778
                data:
                  id: LOpk9M00bMWgOJ3hcTcCHmz1JjxMFRRI
                  ad_attempt_count: null
                  ad_break_count: null
                  ad_break_error_count: null
                  ad_break_error_percentage: null
                  ad_error_count: null
                  ad_error_percentage: null
                  ad_exit_before_start_count: null
                  ad_exit_before_start_percentage: null
                  ad_impression_count: null
                  ad_playback_failure_error_type_id: null
                  ad_preroll_startup_time: null
                  ad_startup_error_count: null
                  ad_startup_error_percentage: null
                  asn: 11427
                  asn_name: null
                  asset_id: rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy
                  audio_codec: null
                  audio_codec_initial: null
                  buffering_count: null
                  buffering_duration: null
                  buffering_rate: null
                  cdn: null
                  city: Austin
                  client_application_name: null
                  client_application_version: null
                  continent_code: null
                  country_code: US
                  country_name: United States
                  custom_1: null
                  custom_2: null
                  custom_3: null
                  custom_4: null
                  custom_5: null
                  custom_6: null
                  custom_7: null
                  custom_8: null
                  custom_9: null
                  custom_10: null
                  environment_id: envid123
                  error_type_id: null
                  events:
                  - viewer_time: 1643216891851
                    playback_time: 0
                    name: playerready
                    event_time: 1643216898061
                    details: {}
                  - viewer_time: 1643216891853
                    playback_time: 0
                    name: viewstart
                    event_time: 1643216898101
                    details: {}
                  exit_before_video_start: false
                  experiment_name: null
                  inserted_at: '2022-01-26T17:08:18Z'
                  isp: null
                  latitude: null
                  live_stream_id: null
                  live_stream_latency: null
                  long_rebuffering: false
                  long_resume: false
                  longitude: null
                  metro: null
                  mux_api_version: v1
                  mux_embed: null
                  mux_embed_version: null
                  mux_viewer_id: abc123viewerid
                  page_load_time: null
                  page_type: null
                  page_url: null
                  platform_description: null
                  platform_summary: null
                  playback_business_exception_error_type_id: null
                  playback_failure: false
                  playback_failure_error_type_id: null
                  playback_id: null
                  playback_score: null
                  player_autoplay: false
                  player_error_code: '1001'
                  player_error_context: error context
                  player_error_message: error from player
                  player_height: null
                  player_instance_id: null
                  player_language: null
                  player_load_time: null
                  player_mux_plugin_name: apple-mux
                  player_mux_plugin_version: null
                  player_name: null
                  player_poster: null
                  player_preload: false
                  player_remote_played: null
                  player_software: null
                  player_software_version: null
                  player_source_domain: null
                  player_source_duration: null
                  player_source_height: null
                  player_source_host_name: stream.mux.com
                  player_source_stream_type: null
                  player_source_type: null
                  player_source_url: https://stream.mux.com/ax9qwyTIaUDLdmhesYDKir5kfE4Ve215.m3u8
                  player_source_width: null
                  player_startup_time: null
                  player_version: null
                  player_view_count: null
                  player_width: null
                  preroll_ad_asset_hostname: null
                  preroll_ad_tag_hostname: null
                  preroll_played: null
                  preroll_requested: null
                  property_id: 1234
                  quality_score: null
                  rebuffer_percentage: null
                  rebuffering_score: null
                  region: null
                  rendition_change_count: null
                  rendition_downshift_count: null
                  rendition_upshift_count: null
                  requests_for_first_preroll: null
                  session_id: b97d7b4a-8de7-4b18-8984-1f9ec3d3b5bc
                  short_time: '2022-01-26T17:08:18Z'
                  startup_score: null
                  sub_property_id: null
                  time_shift_enabled: false
                  time_to_first_frame: null
                  updated_at: '2022-01-26T17:56:12Z'
                  used_captions: false
                  used_fullscreen: false
                  used_pip: false
                  video_affiliate: null
                  video_brand: null
                  video_cdn_trace: []
                  video_codec: null
                  video_codec_initial: null
                  video_content_type: null
                  video_creator_id: null
                  video_duration: null
                  video_dynamic_range_type: null
                  video_dynamic_range_type_initial: null
                  video_encoding_variant: null
                  video_id: rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy
                  video_language: null
                  video_producer: null
                  video_series: null
                  video_source_bitrate: null
                  video_source_bitrate_initial: null
                  video_source_fps: null
                  video_source_fps_initial: null
                  video_source_height: null
                  video_source_height_initial: null
                  video_source_width: null
                  video_source_width_initial: null
                  video_startup_business_exception_error_type_id: null
                  video_startup_failure: false
                  video_startup_preroll_load_time: null
                  video_startup_preroll_request_time: null
                  video_stream_type: null
                  video_title: null
                  video_variant_id: null
                  video_variant_name: null
                  view_average_request_latency: null
                  view_average_request_throughput: null
                  view_cdn_edge_pop: null
                  view_cdn_origin: null
                  view_content_startup_time: null
                  view_drm_level: null
                  view_drm_type: null
                  view_dropped: false
                  view_dropped_frame_count: null
                  view_end: '2022-01-26T17:56:12Z'
                  view_error_id: null
                  view_has_ad: false
                  view_id: 8d00a0ca-8456-4e55-9ff8-dc501814a6b1
                  view_max_downscale_percentage: '0.32222223'
                  view_max_playhead_position: '41126'
                  view_max_request_latency: null
                  view_max_upscale_percentage: '0'
                  view_playing_time: '58134'
                  view_seek_count: null
                  view_seek_duration: null
                  view_session_id: null
                  view_start: '2022-01-26T17:08:18Z'
                  view_total_content_playback_time: 37521
                  view_total_downscaling: null
                  view_total_upscaling: null
                  viewer_application_engine: null
                  viewer_application_name: null
                  viewer_application_version: null
                  viewer_connection_type: null
                  viewer_device_category: null
                  viewer_device_manufacturer: null
                  viewer_device_model: iPhone10,4
                  viewer_device_name: null
                  viewer_experience_score: null
                  viewer_os_architecture: null
                  viewer_os_family: null
                  viewer_os_version: '15.1'
                  viewer_plan: null
                  viewer_plan_category: null
                  viewer_plan_status: null
                  viewer_user_agent: null
                  viewer_user_id: null
                  watch_time: null
                  watched: true
                  weighted_average_bitrate: 697078
      security:
      - accessToken: []
      - authorizationToken: []
components:
  schemas:
    VideoViewResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/VideoView'
        timeframe:
          type: array
          items:
            type: integer
            format: int64
        total_row_count:
          type: integer
          format: int64
          nullable: true
      required:
      - data
      - timeframe
      - total_row_count
    ListVideoViewsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AbridgedVideoView'
        total_row_count:
          type: integer
          format: int64
          nullable: true
        timeframe:
          type: array
          items:
            type: integer
            format: int64
      required:
      - data
      - total_row_count
      - timeframe
    VideoViewEvent:
      type: object
      properties:
        viewer_time:
          type: integer
          format: int64
        playback_time:
          type: integer
          format: int64
        name:
          type: string
        event_time:
          type: integer
          format: int64
        details:
          type: object
          additionalProperties: true
      required:
      - viewer_time
      - playback_time
      - name
      - event_time
      - details
    AbridgedVideoView:
      type: object
      properties:
        id:
          type: string
        viewer_os_family:
          type: string
          nullable: true
        viewer_application_name:
          type: string
          nullable: true
        video_title:
          type: string
          nullable: true
        total_row_count:
          type: integer
          format: int64
        player_error_message:
          type: string
          nullable: true
        player_error_code:
          type: string
          nullable: true
        error_type_id:
          type: integer
          format: int32
          nullable: true
        country_code:
          type: string
          nullable: true
        view_start:
          type: string
        view_end:
          type: string
        viewer_experience_score:
          type: number
          format: float
          nullable: true
        watch_time:
          type: integer
          format: int32
          nullable: true
        playback_failure:
          type: boolean
      required:
      - id
      - viewer_os_family
      - viewer_application_name
      - video_title
      - total_row_count
      - player_error_message
      - player_error_code
      - error_type_id
      - country_code
      - view_start
      - view_end
      - viewer_experience_score
      - watch_time
      - playback_failure
    VideoView:
      type: object
      properties:
        view_total_upscaling:
          type: string
          nullable: true
        preroll_ad_asset_hostname:
          type: string
          nullable: true
        player_source_domain:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        viewer_user_agent:
          type: string
          nullable: true
        preroll_requested:
          type: boolean
          nullable: true
        page_type:
          type: string
          nullable: true
        startup_score:
          type: string
          nullable: true
        view_seek_duration:
          type: integer
          format: int64
          nullable: true
        country_name:
          type: string
          nullable: true
        player_source_height:
          type: integer
          format: int32
          nullable: true
        longitude:
          type: string
          nullable: true
        buffering_count:
          type: integer
          format: int64
          nullable: true
        video_duration:
          type: integer
          format: int64
          nullable: true
        player_source_type:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        view_id:
          type: string
        platform_description:
          type: string
          nullable: true
        video_startup_preroll_request_time:
          type: integer
          format: int64
          nullable: true
        viewer_device_name:
          type: string
          nullable: true
        video_series:
          type: string
          nullable: true
        viewer_application_name:
          type: string
          nullable: true
        updated_at:
          type: string
        view_total_content_playback_time:
          type: integer
          format: int64
          nullable: true
        cdn:
          type: string
          nullable: true
        player_instance_id:
          type: string
          nullable: true
        video_language:
          type: string
          nullable: true
        player_source_width:
          type: integer
          format: int32
          nullable: true
        player_error_message:
          type: string
          nullable: true
        player_mux_plugin_version:
          type: string
          nullable: true
        watched:
          type: boolean
        playback_score:
          type: string
          nullable: true
        page_url:
          type: string
          nullable: true
        metro:
          type: string
          nullable: true
        view_max_request_latency:
          type: integer
          format: int64
          nullable: true
        requests_for_first_preroll:
          type: integer
          format: int64
          nullable: true
        view_total_downscaling:
          type: string
          nullable: true
        latitude:
          type: string
          nullable: true
        player_source_host_name:
          type: string
          nullable: true
        inserted_at:
          type: string
        view_end:
          type: string
        mux_embed_version:
          type: string
          nullable: true
        player_language:
          type: string
          nullable: true
        page_load_time:
          type: integer
          format: int64
          nullable: true
        viewer_device_category:
          type: string
          nullable: true
        video_startup_preroll_load_time:
          type: integer
          format: int64
          nullable: true
        player_version:
          type: string
          nullable: true
        watch_time:
          type: integer
          format: int64
          nullable: true
        player_source_stream_type:
          type: string
          nullable: true
        preroll_ad_tag_hostname:
          type: string
          nullable: true
        viewer_device_manufacturer:
          type: string
          nullable: true
        rebuffering_score:
          type: string
          nullable: true
        experiment_name:
          type: string
          nullable: true
        viewer_os_version:
          type: string
          nullable: true
        player_preload:
          type: boolean
        buffering_duration:
          type: integer
          format: int64
          nullable: true
        player_view_count:
          type: integer
          format: int64
          nullable: true
        player_software:
          type: string
          nullable: true
        player_load_time:
          type: integer
          format: int64
          nullable: true
        platform_summary:
          type: string
          nullable: true
        video_encoding_variant:
          type: string
          nullable: true
        player_width:
          type: integer
          format: int32
          nullable: true
        view_seek_count:
          type: integer
          format: int64
          nullable: true
        viewer_experience_score:
          type: string
          nullable: true
        view_error_id:
          type: integer
          format: int32
          nullable: true
        video_variant_name:
          type: string
          nullable: true
        preroll_played:
          type: boolean
          nullable: true
        viewer_application_engine:
          type: string
          nullable: true
        viewer_os_architecture:
          type: string
          nullable: true
        player_error_code:
          type: string
          nullable: true
        buffering_rate:
          type: string
          nullable: true
        events:
          type: array
          items:
            $ref: '#/components/schemas/VideoViewEvent'
        player_name:
          type: string
          nullable: true
        view_start:
          type: string
        view_average_request_throughput:
          type: integer
          format: int64
          nullable: true
        video_producer:
          type: string
          nullable: true
        error_type_id:
          type: integer
          format: int32
          nullable: true
        mux_viewer_id:
          type: string
        video_id:
          type: string
          nullable: true
        continent_code:
          type: string
          nullable: true
        session_id:
          type: string
        exit_before_video_start:
          type: boolean
        video_content_type:
          type: string
          nullable: true
        viewer_os_family:
          type: string
          nullable: true
        player_poster:
          type: string
          nullable: true
        view_average_request_latency:
          type: integer
          format: int64
          nullable: true
        video_variant_id:
          type: string
          nullable: true
        player_source_duration:
          type: integer
          format: int64
          nullable: true
        player_source_url:
          type: string
          nullable: true
        mux_api_version:
          type: string
        video_title:
          type: string
          nullable: true
        id:
          type: string
        short_time:
          type: string
        rebuffer_percentage:
          type: string
          nullable: true
        time_to_first_frame:
          type: integer
          format: int64
          nullable: true
        viewer_user_id:
          type: string
          nullable: true
        video_stream_type:
          type: string
          nullable: true
        player_startup_time:
          type: integer
          format: int64
          nullable: true
        viewer_application_version:
          type: string
          nullable: true
        view_max_downscale_percentage:
          type: string
          nullable: true
        view_max_upscale_percentage:
          type: string
          nullable: true
        country_code:
          type: string
          nullable: true
        used_fullscreen:
          type: boolean
        isp:
          type: string
          nullable: true
        property_id:
          type: integer
          format: int64
        player_autoplay:
          type: boolean
        player_height:
          type: integer
          format: int32
          nullable: true
        asn:
          type: integer
          format: int64
          nullable: true
        asn_name:
          type: string
          nullable: true
        quality_score:
          type: string
          nullable: true
        player_software_version:
          type: string
          nullable: true
        player_mux_plugin_name:
          type: string
          nullable: true
        sub_property_id:
          type: string
          nullable: true
        player_remote_played:
          type: boolean
          nullable: true
        view_max_playhead_position:
          type: string
          nullable: true
        view_playing_time:
          type: string
          nullable: true
        view_session_id:
          type: string
          nullable: true
        viewer_connection_type:
          type: string
          nullable: true
        viewer_device_model:
          type: string
          nullable: true
        weighted_average_bitrate:
          type: number
          format: double
          nullable: true
        custom_1:
          type: string
          nullable: true
        custom_2:
          type: string
          nullable: true
        custom_3:
          type: string
          nullable: true
        custom_4:
          type: string
          nullable: true
        custom_5:
          type: string
          nullable: true
        custom_6:
          type: string
          nullable: true
        custom_7:
          type: string
          nullable: true
        custom_8:
          type: string
          nullable: true
        custom_9:
          type: string
          nullable: true
        custom_10:
          type: string
          nullable: true
        live_stream_latency:
          type: integer
          format: int64
          nullable: true
        asset_id:
          type: string
          nullable: true
        environment_id:
          type: string
        live_stream_id:
          type: string
          nullable: true
        mux_embed:
          type: string
          nullable: true
        playback_id:
          type: string
          nullable: true
        player_error_context:
          type: string
          nullable: true
        view_drm_type:
          type: string
          nullable: true
        view_dropped_frame_count:
          type: integer
          format: int64
          nullable: true
        view_has_ad:
          type: boolean
        video_startup_failure:
          type: boolean
        ad_attempt_count:
          type: integer
          format: int32
          nullable: true
        ad_break_count:
          type: integer
          format: int32
          nullable: true
        ad_break_error_count:
          type: integer
          format: int32
          nullable: true
        ad_break_error_percentage:
          type: string
          nullable: true
        ad_error_count:
          type: integer
          format: int32
          nullable: true
        ad_error_percentage:
          type: string
          nullable: true
        ad_impression_count:
          type: integer
          format: int32
          nullable: true
        ad_startup_error_count:
          type: integer
          format: int32
          nullable: true
        ad_startup_error_percentage:
          type: string
          nullable: true
        ad_exit_before_start_count:
          type: integer
          format: int32
          nullable: true
        ad_exit_before_start_percentage:
          type: string
          nullable: true
        rendition_change_count:
          type: integer
          format: int32
          nullable: true
        rendition_upshift_count:
          type: integer
          format: int32
          nullable: true
        rendition_downshift_count:
          type: integer
          format: int32
          nullable: true
        long_resume:
          type: boolean
        long_rebuffering:
          type: boolean
        playback_failure_error_type_id:
          type: integer
          format: int32
          nullable: true
        playback_business_exception_error_type_id:
          type: integer
          format: int32
          nullable: true
        video_startup_business_exception_error_type_id:
          type: integer
          format: int32
          nullable: true
        playback_failure:
          type: boolean
        ad_playback_failure_error_type_id:
          type: integer
          format: int32
          nullable: true
        view_content_startup_time:
          type: integer
          format: int32
          nullable: true
        ad_preroll_startup_time:
          type: integer
          format: int32
          nullable: true
        view_dropped:
          type: boolean
        client_application_name:
          type: string
          nullable: true
        client_application_version:
          type: string
          nullable: true
        video_affiliate:
          type: string
          nullable: true
        viewer_plan:
          type: string
          nullable: true
        viewer_plan_status:
          type: string
          nullable: true
        viewer_plan_category:
          type: string
          nullable: true
        view_drm_level:
          type: string
          nullable: true
        video_brand:
          type: string
          nullable: true
        used_pip:
          type: boolean
        time_shift_enabled:
          type: boolean
        used_captions:
          type: boolean
        video_codec:
          type: string
          nullable: true
        audio_codec:
          type: string
          nullable: true
        video_dynamic_range_type:
          type: string
          nullable: true
        video_source_height_initial:
          type: integer
          format: int32
          nullable: true
        video_source_width_initial:
          type: integer
          format: int32
          nullable: true
        video_source_bitrate_initial:
          type: integer
          format: int64
          nullable: true
        video_codec_initial:
          type: string
          nullable: true
        audio_codec_initial:
          type: string
          nullable: true
        video_source_fps_initial:
          type: number
          format: double
          nullable: true
        video_dynamic_range_type_initial:
          type: string
          nullable: true
        video_source_fps:
          type: number
          format: double
          nullable: true
        video_source_bitrate:
          type: integer
          format: int64
          nullable: true
        video_source_height:
          type: integer
          format: int32
          nullable: true
        video_source_width:
          type: integer
          format: int32
          nullable: true
        view_cdn_edge_pop:
          type: string
          nullable: true
        view_cdn_origin:
          type: string
          nullable: true
        video_creator_id:
          type: string
          nullable: true
        video_cdn_trace:
          type: array
          items:
            type: string
      required:
      - ad_attempt_count
      - ad_break_count
      - ad_break_error_count
      - ad_break_error_percentage
      - ad_error_count
      - ad_error_percentage
      - ad_exit_before_start_count
      - ad_exit_before_start_percentage
      - ad_impression_count
      - ad_startup_error_count
      - ad_startup_error_percentage
      - rendition_change_count
      - rendition_upshift_count
      - rendition

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mux-com/refs/heads/main/openapi/mux-com-video-views-api-openapi.yml