openapi: 3.0.3
info:
  title: Brightcove Analytics API Reference Access Tokens Engagement 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: Engagement Report
  description: Detailed engagement reports by account, video or player. Detailed engagement is available only for the most recent 32 days.
paths:
  /v1/engagement/accounts/{{account_id}}:
    get:
      tags:
      - Engagement Report
      summary: Get Account Engagement
      description: 'Get a summary report of engagement for the account. Note:  Engagement reports are only available for periods within the past 32 days. Requests outside that range will return an error The only parameters supported for Engagement reports are from and to Engagement reports are available for single accounts only - reports on multiple accounts will not work'
      operationId: GetAccountEngagement
      security:
      - BC_OAuth2:
        - video-cloud/analytics/read
      parameters:
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept-Encoding'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
        '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/engagement/accounts/{{account_id}}/players/{{player_id}}:
    get:
      tags:
      - Engagement Report
      summary: Get Player Engagement
      description: 'Get a summary report of engagement for a player. Note:  Engagement reports are only available for periods within the past 32 days. Requests outside that range will return an error The only parameters supported for Engagement reports are from and to Engagement reports are available for single accounts only - reports on multiple accounts will not work'
      operationId: GetPlayerEngagement
      security:
      - BC_OAuth2:
        - video-cloud/analytics/read
      parameters:
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept-Encoding'
      - $ref: '#/components/parameters/player_id'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
        '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/engagement/accounts/{{account_id}}/videos/{{video_id}}:
    get:
      tags:
      - Engagement Report
      summary: Get Video Engagement
      description: 'Get a summary report of engagement for a video. Note:  Engagement reports are only available for periods within the past 32 days. Requests outside that range will return an error The only parameters supported for Engagement reports are from and to Engagement reports are available for single accounts only - reports on multiple accounts will not work'
      operationId: GetVideoEngagement
      security:
      - BC_OAuth2:
        - video-cloud/analytics/read
      parameters:
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Accept-Encoding'
      - $ref: '#/components/parameters/video_id'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get_Video_Engagement_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:
  parameters:
    account_id:
      name: account_id
      in: path
      description: a Video Cloud account ID
      required: true
      style: simple
      explode: false
      schema:
        type: string
    Authorization:
      name: Authorization
      in: header
      description: 'Authorization: Bearer access_token (see Getting Access Tokens)'
      required: true
      style: simple
      explode: false
      schema:
        type: string
    player_id:
      name: player_id
      in: path
      description: a Video Cloud player ID
      required: true
      style: simple
      explode: false
      schema:
        type: string
    Content-Type:
      name: Content-Type
      in: header
      description: 'Content-Type: application/json'
      required: true
      style: simple
      explode: false
      schema:
        type: string
    video_id:
      name: video_id
      in: path
      description: a Video Cloud video ID
      required: true
      style: simple
      explode: false
      schema:
        type: string
    Accept-Encoding:
      name: Accept-Encoding
      in: header
      description: 'Accept-Encoding: gzip (optional)'
      required: true
      style: simple
      explode: false
      schema:
        type: string
  schemas:
    Timeline:
      title: Timeline
      required:
      - type
      - values
      type: object
      properties:
        type:
          type: string
          description: The type of the timeline array
        values:
          type: array
          items:
            type: number
          description: Array of views in each 100th part of video duration
      example:
        timeline:
          type: percentile
          values:
          - 17507.16
          - 17446.47
          - 17381.53
          - 18864.7
          - 20034.09
          - 19964.33
          - 19869.78
          - 19667.05
          - 19566.13
          - 19475.24
          - 72462.89
          - 72388.19
          - 72380.55
          - 72340.39
          - 72230.89
          - 72181.51
          - 72118.65
          - 72009.98
          - 71959.46
          - 71928.65
          - 72301.65
          - 72248.72
          - 72214.78
          - 72172.31
          - 72075.03
          - 71953.25
          - 71933.07
          - 71890.68
          - 71828.13
          - 71769.25
          - 71713.09
          - 71599.56
          - 71581.92
          - 71542.35
          - 71416.43
          - 71305.33
          - 71274.92
          - 71248.6
          - 71321.91
          - 71290.81
          - 71214.11
          - 71191.02
          - 71167.63
          - 71141.25
          - 71125.24
          - 71087.18
          - 71065.24
          - 71038.08
          - 71012.63
          - 71004.61
          - 74524.95
          - 74517.69
          - 74489.42
          - 74384.57
          - 74359.08
          - 74336.24
          - 74311.31
          - 74291.99
          - 74266.64
          - 74243.25
          - 74201.68
          - 74179.67
          - 74076.49
          - 74055.94
          - 74045.4
          - 73999.57
          - 73946.48
          - 73933.69
          - 73924.56
          - 73588.54
          - 73537.41
          - 73524.52
          - 71981.69
          - 70901.7
          - 70903.16
          - 70853.67
          - 70816.72
          - 70737.02
          - 70723.89
          - 70723.22
          - 70736.19
          - 70721.05
          - 70668.38
          - 70610.77
          - 70589
          - 70587.97
          - 70580.99
          - 70581.93
          - 70574.65
          - 70558.48
          - 21197.2
          - 21192.85
          - 21202.43
          - 21205.57
          - 21200.8
          - 21200.34
          - 21199.76
          - 21201.2
          - 21202.08
          - 21203
    Get_Video_Engagement_Response:
      title: Get Video Engagement Response
      required:
      - video_duration
      type: object
      properties:
        video_duration:
          type: string
          description: the video duration in seconds
      example:
        timeline:
          type: percentile
          values:
          - 1063
          - 1063
          - 1063
          - 1063
          - 1063
          - 1063
          - 1063
          - 1063
          - 1034.94
          - 1021
          - 1021
          - 1021
          - 1021
          - 1021
          - 1021
          - 1021
          - 1010.08
          - 988
          - 988
          - 988
          - 988
          - 988
          - 988
          - 988
          - 988
          - 962
          - 962
          - 962
          - 962
          - 962
          - 962
          - 962
          - 962
          - 953.97
          - 950
          - 950
          - 950
          - 950
          - 950
          - 950
          - 950
          - 944.38
          - 933
          - 933
          - 933
          - 933
          - 933
          - 933
          - 933
          - 933
          - 922
          - 922
          - 922
          - 922
          - 922
          - 922
          - 922
          - 922
          - 913.3
          - 909
          - 909
          - 909
          - 909
          - 909
          - 909
          - 909
          - 906.03
          - 900
          - 900
          - 900
          - 900
          - 900
          - 900
          - 900
          - 900
          - 875
          - 875
          - 875
          - 875
          - 875
          - 875
          - 875
          - 875
          - 837.6
          - 819
          - 819
          - 819
          - 819
          - 819
          - 819
          - 819
          - 818.67
          - 818
          - 818.67
          - 819
          - 819
          - 819
          - 819
          - 819
          - 819
        video_duration: '12'
  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