openapi: 3.0.3
info:
  title: Brightcove Analytics API Reference Access Tokens Analytics Report API
  description: "Reference for the Brightcove Analytics API, used to retrieve analytics data for your accounts. To test API requests, you can use our <a href=\"/getting-started/concepts-testing-tools-brightcove-apis.html\" target=\"_blank\">API Testing Tools</a>.\n\nFor additional in-depth guides to features of the API, see the **[general documentation](/analytics/index.html)**.\n\n **Base URL**: https://analytics.api.brightcove.com"
  x-bc-access: public
  version: 1.0.0
servers:
- url: https://analytics.api.brightcove.com
  variables: {}
tags:
- name: Analytics Report
  description: Full analytics reports with many options for filtering, date ranges, formats, and more.
paths:
  /v1/data:
    get:
      tags:
      - Analytics Report
      summary: Get Analytics Report
      description: Get an analytics report on one or more dimensions. Note that the fields returned in the response will vary according to the dimension(s) requested and the fields specified in the fields parameter. See [the API Overview](/analytics/getting-started/analytics-api-overview-dimensions-fields-and-parameters.html) and the dimension guides for details.
      operationId: GetAnalyticsReport
      security:
      - BC_OAuth2:
        - video-cloud/analytics/read
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept-Encoding'
      - $ref: '#/components/parameters/accounts'
      - $ref: '#/components/parameters/dimensions'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/reconciled'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get_Analytics_Report_Response'
        '400':
          description: 'BAD_REQUEST: The message fields of the response contains information about what caused the error such as invalid value for sort parameter

            UNSUPPORTED_FIELD_COMBINATION_ERROR: The message fields of the response contains information about what invalid fields were specified'
        '401':
          description: 'UNAUTHORIZED: Authentication failed; check to make sure your client credentials are correct'
        '404':
          description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
        '405':
          description: 'METHOD_NOT_ALLOWED: This error occurs when the api request is made with an HTTP method other than GET'
        '500':
          description: 'SERVER_ERROR: Issue in Brightcove system; try again later

            PROCESSING: The analytics API may send back this message if it encounters a long running query. Once the query has finished it will be stored in the server’s cache for up to 5 minutes. Therefore we suggest querying the API 4 minutes after receiving this error'
      deprecated: false
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
  /v1/data/status:
    get:
      tags:
      - Analytics Report
      summary: Get Available Date Range
      description: Get the date range for which reconciled data is available for any Analytics API report. All parameters are allowed, but only account, dimensions, and where affect the result - all others are ignored. Note that date range for this request must fall within the available date range for the dimensions requested.
      operationId: GetAvailableDateRange
      security:
      - BC_OAuth2:
        - video-cloud/analytics/read
      parameters:
      - $ref: '#/components/parameters/accounts'
      - $ref: '#/components/parameters/dimensions'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept-Encoding'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/reconciled'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get_Available_Date_Range_Response'
        '400':
          description: 'BAD_REQUEST: The message fields of the response contains information about what caused the error such as invalid value for sort parameter

            UNSUPPORTED_FIELD_COMBINATION_ERROR: The message fields of the response contains information about what invalid fields were specified'
        '401':
          description: 'UNAUTHORIZED: Authentication failed; check to make sure your client credentials are correct'
        '404':
          description: 'RESOURCE_NOT_FOUND: The api could not find the resource you requested'
        '405':
          description: 'METHOD_NOT_ALLOWED: This error occurs when the api request is made with an HTTP method other than GET'
        '500':
          description: 'SERVER_ERROR: Issue in Brightcove system; try again later

            PROCESSING: The analytics API may send back this message if it encounters a long running query. Once the query has finished it will be stored in the server’s cache for up to 5 minutes. Therefore we suggest querying the API 4 minutes after receiving this error'
      deprecated: false
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
components:
  schemas:
    Items:
      title: items
      type: object
      properties:
        ad_mode_begin:
          type: integer
          description: number of times a player entered ad mode
          format: int32
        ad_mode_complete:
          type: integer
          description: number of times a player completed ad mode
          format: int32
        bytes_delivered:
          type: number
          description: the total bytes of data delivered, including the videos, other assets such as images and captions, and (for player reports) the player code - some of the date is obtained from CDNs and may not be available for up to 3 days
        engagement_score:
          type: number
          description: the calculated engagement score for the video
        play_rate:
          type: number
          description: video views divided by video impressions
        play_request:
          type: integer
          description: number of play requests received for a video
          format: int32
        video:
          type: string
          description: the video id
        duration:
          type: string
          description: '''the duration of the video in seconds (note that the duration is available only if there is at least one `video_view`)'''
        video_engagement_1:
          type: number
          description: number of views at the 1% point of the video duration
        video_engagement_25:
          type: number
          description: number of views at the 25% point of the video duration
        video_engagement_50:
          type: number
          description: number of views at the 50% point of the video duration
        video_engagement_75:
          type: number
          description: number of views at the 75% point of the video duration
        video_engagement_100:
          type: number
          description: number of views at the 100% point of the video duration
        video_impression:
          type: integer
          description: number of times the video was loaded in a player
          format: int32
        name:
          type: string
          description: name of the video
        video_percent_viewed:
          type: number
          description: average percentage of the video played when viewed
        video_seconds_viewed:
          type: number
          description: total seconds of the video viewed
        video_view:
          type: integer
          description: number of times some portion of the video was viewed
          format: int32
    Format:
      title: format
      enum:
      - csv
      - json
      - xlxs
      type: string
      example: csv
      x-enum-elements:
      - name: csv
        description: ''
      - name: json
        description: ''
      - name: xlxs
        description: ''
    Dimensions:
      title: dimensions
      enum:
      - account
      - audio_track_language
      - caption_track_language
      - city
      - country
      - region
      - date
      - date-time
      - device_os
      - device_type
      - player
      - referrer_domain
      - destination_domain
      - search_terms
      - social_platform
      - source_type
      - video
      - stream_type
      type: string
      example: account
      x-enum-elements:
      - name: account
        description: Analytics data for account as a whole
      - name: audio_track_language
        description: Analytics by audio track language selected by viewers
      - name: caption_track_language
        description: Analytics by caption/subtitle track language enabled by viewers
      - name: city
        description: Geo analytics for cities
      - name: country
        description: Geo analytics for countries
      - name: region
        description: Geo analytics for regions of countries
      - name: date
        description: Daily analytics for a range of days
      - name: datetime
        description: Hourly analytics for a range of hours - available for the previous 32 days
      - name: device_os
        description: Analytics by device operating systems
      - name: device_type
        description: Analytics by device type
      - name: player
        description: Analytics by player
      - name: referrer_domain
        description: Analytics by referring domain
      - name: destination_domain
        description: Analytics by the destination domain
      - name: search_terms
        description: Search terms that brought the user to the page
      - name: source_type
        description: Source such as search or direct link
      - name: video
        description: Analytics by video
      - name: stream_type
        description: Identifies whether content is video-on-demand (VOD) or live
    Summary:
      title: Summary
      type: object
      properties:
        ad_mode_begin:
          type: integer
          description: Total ad mode begin events received for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        ad_mode_complete:
          type: integer
          description: Total ad mode complete events received for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        active_media:
          type: integer
          description: Total active videos in account(s) - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        bytes_delivered:
          type: integer
          description: Total bytes of data delivered for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        daily_unique_viewers:
          type: integer
          description: Total daily unique viewers for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        drm_bytes_packaged:
          type: number
          description: Total DRM bytes packaged for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        engagement_score:
          type: number
          description: Average engagement score for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        licenses_served:
          type: integer
          description: Total DRM licenses serverd for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        live_seconds_streamed:
          type: number
          description: Total second of live video streamed for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        play_rate:
          type: number
          description: Average play rate for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        play_request:
          type: integer
          description: Total play requests for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        player_load:
          type: integer
          description: Total player loads for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        video_engagement_1:
          type: number
          description: Average views at 1% point for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        video_engagement_25:
          type: number
          description: Average views at 25% point for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        video_engagement_50:
          type: number
          description: Average views at 50% point for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        video_engagement_75:
          type: number
          description: Average views at 75% point for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        video_engagement_100:
          type: number
          description: Average views at 100% point for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
        video_impression:
          type: integer
          description: Total video impressions for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
        video_view:
          type: integer
          description: Total video views for all items - note that properties included in the summary vary depending on the dimension(s) and fields requested
          format: int32
    live_where:
      title: Live where
      enum:
      - country
      - device_type
      - video
      type: string
      example: video==6049313942001,6049313942002
      x-enum-elements:
      - name: country
        description: ''
      - name: device_type
        description: ''
      - name: video
        description: ''
    Get_Analytics_Report_Response:
      title: Get Analytics Report Response
      required:
      - account
      - item_count
      - items
      - summary
      - video_engagement_1
      - video_engagement_25
      - video_engagement_50
      - video_engagement_75
      - video_engagement_100
      type: object
      properties:
        account:
          type: string
          description: the Video Cloud account id
        item_count:
          type: integer
          description: the total number of items matching the request
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Items'
          description: array of analytics objects for the videos returned
        summary:
          $ref: '#/components/schemas/Summary'
        video_engagement_1:
          type: number
          description: number of views at the 1% point of the video duration for all videos
        video_engagement_25:
          type: number
          description: number of views at the 25% point of the video duration for all videos
        video_engagement_50:
          type: number
          description: number of views at the 50% point of the video duration for all videos
        video_engagement_75:
          type: number
          description: number of views at the 75% point of the video duration for all videos
        video_engagement_100:
          type: number
          description: number of views at the 100% point of the video duration for all videos
      example:
        item_count: 378
        items:
        - video_duration: null
          video_name: School of Fish
          video_seconds_viewed: 0
          video_impression: 1
          ad_mode_complete: 0
          video: '5068505928001'
          engagement_score: null
          video_percent_viewed: 0
          play_request: 0
          video_view: 0
          player_name: Popular Videos Playlist Player v6
          ad_mode_begin: 0
          play_rate: 0
          player: players.brightcove.com/1752604059001/Hyuo8j4pM_default
        - video_duration: null
          video_name: null
          video_seconds_viewed: 0
          video_impression: 2
          ad_mode_complete: 0
          video: null
          engagement_score: null
          video_percent_viewed: 0
          play_request: 0
          video_view: 0
          player_name: CarouselPlayerPlugin
          ad_mode_begin: 0
          play_rate: 0
          player: players.brightcove.com/1752604059001/18ba409a-3d7d-424e-9d10-849a5864f09e_default
        summary:
          engagement_score: 404.21
          video_seconds_viewed: 722394
          video_percent_viewed: 6203852.1
          video_impression: 45116
          play_request: 22035
          ad_mode_complete: 757
          video_view: 15348
          ad_mode_begin: 923
          play_rate: 0.34
    Get_Available_Date_Range_Response:
      title: Get Available Date Range Response
      required:
      - reconciled_from
      - reconciled_to
      type: object
      properties:
        reconciled_from:
          type: string
          description: the earliest date that you can use for from and get reconciled data
        reconciled_to:
          type: string
          description: '''the latest date that you can use for to and get reconciled data (realtime data may be available for later dates)'''
      example:
        reconciled_from: '2011-01-01'
        reconciled_to: '2018-08-31'
  parameters:
    sort:
      name: sort
      in: query
      description: Field to sort results by (prefix with `-` for descending order); you can sort on **any field** that you specifying the `fields` parameter.
      style: form
      explode: true
      schema:
        type: string
        default: video_view
        example: video_view
    Accept-Encoding:
      name: Accept-Encoding
      in: header
      description: 'Accept-Encoding: gzip (optional)'
      required: true
      style: simple
      explode: false
      schema:
        type: string
    fields:
      name: fields
      in: query
      description: 'Fields to return - available fields varies according to the dimensions - see the [Overview: Analytics API](/analytics/getting-started/analytics-api-overview-dimensions-fields-and-parameters.html) for more details'
      style: form
      explode: true
      schema:
        type: string
        default: '`video_view` + others (varies by dimension)'
        example: video_view, video_impression, video.name
    accounts:
      name: accounts
      in: query
      description: One or more account ids, separated by commas
      required: true
      style: form
      explode: true
      schema:
        type: string
    reconciled:
      name: reconciled
      in: query
      description: if true, only reconciled data is returned; if false, only realtime data is returned; if not present, both reconciled and realtime data are returned
      style: form
      explode: true
      schema:
        type: boolean
        default: true
        example: true
    from:
      name: from
      in: query
      description: '''Start time for the period covered by the report — epoch time in milliseconds (`1535654206775`) or a date in the format `yyyy-mm-dd` (such as `2013-09-26`)'''
      style: form
      explode: true
      schema:
        oneOf:
        - type: string
        - type: integer
        default: 32 days before `to` value
        example: 2018-01-01
    to:
      name: to
      in: query
      description: End time for the period covered by the report — `now` or epoch time in milliseconds (`1535654206775`) or a date in the format `yyyy-mm-dd` (such as `2013-09-26`)
      style: form
      explode: true
      schema:
        oneOf:
        - type: string
        - type: integer
        default: now
        example: '2018-09-01'
    where:
      name: where
      in: query
      description: one or more 'dimension==value' pairs to filter the results; for live, the only available filters are `country`, `device-type`, and `video`. This is a filter in which the options areL where in the world, in which device or which part of the video. In this case, the property is called where as if to use some DSL that mimics the SQL syntax, and that is why it is called where
      required: true
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/live_where'
    Content-Type:
      name: Content-Type
      in: header
      description: 'Content-Type: application/json'
      required: true
      style: simple
      explode: false
      schema:
        type: string
    dimensions:
      name: dimensions
      in: query
      description: "One or more dimensions to report on; see [Multiple Dimensions](/analytics/getting-started/analytics-api-overview-dimensions-fields-and-parameters.html) or which combined dimensions are supported\n\nDimensions:\n  - account\n  - audio_track_language\n  - browser_type\n  - caption_track_language\n  - city\n  - country\n  - date\n  - date_hour\n  - destination_domain\n  - destination_path\n  - device_os\n  - device_manufacturer\n  - device_type\n  - live_stream\n  - player\n  - referrer_domain\n  - region\n  - search_terms\n  - social_platform\n  - source_type\n  - video\n  - stream_type"
      required: true
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/Dimensions'
    Authorization:
      name: Authorization
      in: header
      description: 'Authorization: Bearer access_token (see Getting Access Tokens)'
      required: true
      style: simple
      explode: false
      schema:
        type: string
    format:
      name: format
      in: query
      description: format to return the results in
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/Format'
    offset:
      name: offset
      in: query
      description: Number of items to skip
      style: form
      explode: true
      schema:
        type: integer
        format: int32
        default: 0
        example: 10
    limit:
      name: limit
      in: query
      description: Number of items to return
      style: form
      explode: true
      schema:
        type: integer
        format: int32
        default: 10
        example: 10
  securitySchemes:
    BC_OAuth2:
      type: oauth2
      description: Brightcove OAuth API. See the [support documentation](/oauth/index.html) or [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html) to learn more
      flows:
        clientCredentials:
          tokenUrl: https://oauth.brightcove.com/v4/access_token
          scopes:
            video-cloud/analytics/read: Read analytics data
            video-cloud/video/read: Read video data
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: https://backend_server