openapi: 3.1.0
info:
  title: Mux Animated Images Dimensions 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: Dimensions
  description: Dimensions are the types of metadata that can be collected for a video view. Some dimensions are collected automatically based on the playback or device, such as the viewer's Country or the device information. Other dimensions are specified by the developer when configuring a Mux Data video view such as the video title. The Dimensions APIs allow you to get a list of the supported dimensions and their values.
  x-displayName: Dimensions
paths:
  /data/v1/dimensions:
    get:
      tags:
      - Dimensions
      summary: List Dimensions
      description: 'List all available dimensions.


        Note: This API replaces the list-filters API call.

        '
      operationId: list-dimensions
      servers:
      - url: https://api.mux.com
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDimensionsResponse'
              example:
                data:
                  advanced:
                  - asn
                  - audio_codec
                  - audio_codec_initial
                  - browser_version
                  - client_application_name
                  - client_application_version
                  - country
                  - custom_1
                  - custom_2
                  - custom_3
                  - custom_4
                  - custom_5
                  - custom_6
                  - custom_7
                  - custom_8
                  - custom_9
                  - custom_10
                  - custom_11
                  - custom_12
                  - custom_13
                  - custom_14
                  - custom_15
                  - custom_16
                  - custom_17
                  - custom_18
                  - custom_19
                  - custom_20
                  - experiment_name
                  - environment_id
                  - operating_system_version
                  - page_type
                  - page_url
                  - playback_failure
                  - playback_business_exception
                  - player_autoplay
                  - player_error_code
                  - player_language
                  - player_mux_plugin_name
                  - player_mux_plugin_version
                  - player_poster
                  - player_preload
                  - player_remote_played
                  - player_software_version
                  - player_version
                  - region
                  - source_hostname
                  - time_shift_enabled
                  - used_captions
                  - used_pip
                  - video_affiliate
                  - video_brand
                  - video_cdn_trace
                  - video_codec
                  - video_codec_initial
                  - video_creator_id
                  - video_dynamic_range_type
                  - video_dynamic_range_type_initial
                  - video_encoding_variant
                  - video_language
                  - video_producer
                  - video_source_bitrate
                  - video_source_bitrate_initial
                  - video_source_fps
                  - video_source_fps_initial
                  - video_source_height
                  - video_source_height_initial
                  - video_source_width
                  - video_source_width_initial
                  - video_startup_business_exception
                  - video_variant_id
                  - video_variant_name
                  - view_cdn_edge_pop
                  - view_cdn_origin
                  - view_drm_type
                  - view_dropped
                  - view_dropped_frame_count
                  - view_session_id
                  - viewer_connection_type
                  - viewer_device_model
                  - viewer_user_id
                  - viewer_plan
                  - viewer_plan_status
                  - viewer_plan_category
                  - view_drm_level
                  basic:
                  - asset_id
                  - browser
                  - cdn
                  - continent_code
                  - exit_before_video_start
                  - live_stream_id
                  - operating_system
                  - playback_id
                  - player_name
                  - player_software
                  - source_type
                  - stream_type
                  - sub_property_id
                  - video_content_type
                  - video_id
                  - video_series
                  - video_startup_failure
                  - video_title
                  - view_has_ad
                  - viewer_device_category
                  - viewer_device_manufacturer
                  - viewer_device_name
                timeframe:
                - 1610033879
                - 1610120279
                total_row_count: 1
      security:
      - accessToken: []
      - authorizationToken: []
  /data/v1/dimensions/{DIMENSION_ID}:
    get:
      tags:
      - Dimensions
      summary: Lists the Values for a Specific Dimension
      description: 'Lists the values for a dimension along with a total count of related views.


        Note: This API replaces the list-filter-values API call.

        '
      operationId: list-dimension-values
      servers:
      - url: https://api.mux.com
      parameters:
      - $ref: '#/components/parameters/dimension_id'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/filters'
      - $ref: '#/components/parameters/metric_filters'
      - $ref: '#/components/parameters/timeframe'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDimensionValuesResponse'
              example:
                data:
                - total_count: 10000
                  value: FR
                - total_count: 5000
                  value: ES
                - total_count: 2000
                  value: PT
                - total_count: 100
                  value: DE
                - total_count: 1
                  value: BE
                timeframe:
                - 1610033976
                - 1610120376
                total_row_count: 5
      security:
      - accessToken: []
      - authorizationToken: []
  /data/v1/dimensions/{DIMENSION_ID}/elements:
    get:
      tags:
      - Dimensions
      summary: Lists Elements for a Trace Dimension
      description: 'Lists the elements (values) for a trace dimension along with their total counts.

        This endpoint is specifically designed for trace dimensions like video_cdn_trace

        that contain arrays of values.

        '
      operationId: list-dimension-elements
      servers:
      - url: https://api.mux.com
      parameters:
      - $ref: '#/components/parameters/dimension_id'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/filters'
      - $ref: '#/components/parameters/metric_filters'
      - $ref: '#/components/parameters/timeframe'
      - $ref: '#/components/parameters/order_by'
      - $ref: '#/components/parameters/order_direction'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDimensionValuesResponse'
              example:
                total_row_count: 25
                timeframe:
                - 1755069000
                - 1755155999
                data:
                - value: cdn_a
                  total_count: 2640882
                - value: cdn_b
                  total_count: 1368812
                - value: cdn_c
                  total_count: 154541
      security:
      - accessToken: []
      - authorizationToken: []
components:
  parameters:
    filters:
      name: filters[]
      in: query
      description: 'Filter results using key:value pairs. Must be provided as an array query string parameter.


        **Basic filtering:**

        * `filters[]=dimension:value` - Include rows where dimension equals value

        * `filters[]=!dimension:value` - Exclude rows where dimension equals value


        **For trace dimensions (like video_cdn_trace):**

        * `filters[]=+dimension:value` - Include rows where trace contains value

        * `filters[]=-dimension:value` - Exclude rows where trace contains value

        * `filters[]=dimension:[value1,value2]` - Exact trace match


        **Examples:**

        * `filters[]=country:US` - US views only

        * `filters[]=+video_cdn_trace:fastly` - Views using Fastly CDN

        '
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
    order_direction:
      name: order_direction
      in: query
      description: Sort order.
      required: false
      schema:
        type: string
        enum:
        - asc
        - desc
    dimension_id:
      name: DIMENSION_ID
      in: path
      description: ID of the Dimension
      required: true
      example: abcd1234
      schema:
        type: string
    page:
      name: page
      in: query
      description: Offset by this many pages, of the size of `limit`
      required: false
      schema:
        type: integer
        format: int32
        default: 1
    timeframe:
      name: timeframe[]
      in: query
      description: "Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).\n\nAccepted formats are...\n\n  * array of epoch timestamps e.g. `timeframe[]=1498867200&timeframe[]=1498953600`\n  * duration string e.g. `timeframe[]=24:hours or timeframe[]=7:days`\n"
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
    order_by:
      name: order_by
      in: query
      description: Value to order the results by
      required: false
      schema:
        type: string
        enum:
        - negative_impact
        - value
        - views
        - field
    metric_filters:
      name: metric_filters[]
      in: query
      description: "Limit the results to rows that match inequality conditions from provided metric comparison clauses. Must be provided as an array query string parameter.\n\nPossible filterable metrics are the same as the set of metric ids, with the exceptions of `exits_before_video_start`, `unique_viewers`, `video_startup_failure_percentage`, `view_dropped_percentage`, and `views`.\n\nExample:\n\n  * `metric_filters[]=aggregate_startup_time>=1000`\n"
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
    limit:
      name: limit
      in: query
      description: Number of items to include in the response
      required: false
      schema:
        type: integer
        format: int32
        default: 25
  schemas:
    ListDimensionsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            basic:
              type: array
              items:
                type: string
            advanced:
              type: array
              items:
                type: string
          required:
          - basic
          - advanced
        total_row_count:
          type: integer
          format: int64
          nullable: true
        timeframe:
          type: array
          items:
            type: integer
            format: int64
      required:
      - data
      - total_row_count
      - timeframe
    ListDimensionValuesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DimensionValue'
        total_row_count:
          type: integer
          format: int64
        timeframe:
          type: array
          items:
            type: integer
            format: int64
      required:
      - data
      - total_row_count
      - timeframe
    DimensionValue:
      type: object
      properties:
        value:
          type: string
          nullable: true
        total_count:
          type: integer
          format: int64
      required:
      - value
      - total_count
  securitySchemes:
    accessToken:
      description: 'The Mux Video API uses an Access Token and Secret Key for authentication. If you haven''t already, [generate a new Access Token](https://dashboard.mux.com/settings/access-tokens) in the Access Token settings of your Mux account dashboard.


        Once you have an Access Token ID and Secret, you can then simply include those as the username (id) and password (secret) in the same way you use traditional basic auth.

        '
      scheme: basic
      type: http
    authorizationToken:
      description: 'OAuth authorization token, used as a Bearer Auth header

        '
      scheme: bearer
      type: http
x-tagGroups:
- name: Video
  tags:
  - Assets
  - Live Streams
  - Playback ID
  - URL Signing Keys
  - Direct Uploads
  - Delivery Usage
  - Playback Restrictions
  - DRM Configurations
  - Transcription Vocabularies
- name: Data
  tags:
  - Video Views
  - Errors
  - Filters
  - Exports
  - Metrics
  - Monitoring
  - Real-Time
  - Dimensions
  - Incidents
  - Annotations
  - View and Viewer Counts
- name: System
  tags:
  - Signing Keys
  - Utilities
- name: Robots
  tags:
  - Jobs
  - Ask Questions
  - Edit Captions
  - Find Key Moments
  - Generate Chapters
  - Moderate
  - Summarize
  - Translate Captions
- name: Playback
  tags:
  - Thumbnails
  - Animated Images
  - Storyboards
  - Streaming
  - Captions and Transcripts