openapi: 3.0.3
info:
  title: Brightcove Analytics API Reference Access Tokens Live Analytics 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: Live Analytics
  description: Analytics for Live streams
paths:
  /v1/timeseries/accounts/{{account_id}}:
    get:
      tags:
      - Live Analytics
      summary: Get Live Analytics time-series
      description: A time-series is defined as a an list of timestamp-value pairs representing samples of a variable (metric). The time-series API intends to allow the user to return a time-series for the set of metrics requested in the query.
      operationId: GetLiveTimeSeries
      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/account_id'
      - $ref: '#/components/parameters/live_dimensions'
      - $ref: '#/components/parameters/bucket_limit'
      - $ref: '#/components/parameters/bucket_duration'
      - $ref: '#/components/parameters/metrics'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/live_from'
      - $ref: '#/components/parameters/to'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get_Time_Series_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

            INVALID_PARAM: The message fields of the response contains information about what invalid params were specified or required params were missing'
        '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/events/accounts/{account_id}:
    get:
      tags:
      - Live Analytics
      summary: Get Live Analytics event
      description: Provides a summary of analytics data collected for a live stream.
      operationId: GetLiveEvents
      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/account_id'
      - $ref: '#/components/parameters/live_dimensions'
      - $ref: '#/components/parameters/metrics'
      - $ref: '#/components/parameters/live_where'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get_Events_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

            INVALID_PARAM: The message fields of the response contains information about what invalid params were specified or required params were missing'
        '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:
    live_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 now
        example: 2018-01-01
    live_where:
      name: where
      in: query
      description: "One or more filters to limit responses for Live Analytics requests\nAvailable filters:\n  - video\n  - country\n  - device_type"
      required: true
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/live_where'
    metrics:
      name: metrics
      in: query
      description: "Data metrics to return for live analytics requests:\n\n  - `video_impression` - the number of video impressions\n  - `video_view` - the number of video views\n  - `video_seconds_viewed` - seconds of video viewed\n  - `alive_ss_ad_start` - SSAI ad starts\n  - `fingerprint_count` - \"fingerprint\" (user) count\n  - `ccu` - concurrent viewers"
      required: true
      style: form
      explode: true
      schema:
        type: string
        enum:
        - video_impression
        - video_view
        - video_seconds_viewed
        - alive_ss_ad_start
        - fingerprint_count
        - ccu
        example: video_view,alive_ss_ad_start,ccu
    account_id:
      name: account_id
      in: path
      description: a Video Cloud account ID
      required: true
      style: simple
      explode: false
      schema:
        type: string
    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'
    Authorization:
      name: Authorization
      in: header
      description: 'Authorization: Bearer access_token (see Getting Access Tokens)'
      required: true
      style: simple
      explode: false
      schema:
        type: string
    live_dimensions:
      name: dimensions
      in: query
      description: "One or more dimensions to report on for Live Analytics requests\nDimensions:\n  - video\n  - video, country\n  - video, device_type"
      required: true
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/LiveDimensions'
    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'
    bucket_limit:
      name: bucket_limit
      in: query
      description: '''Max number of points to be returned for a time-series'''
      required: false
      example: 10
      style: form
      explode: true
      schema:
        type: integer
    bucket_duration:
      name: bucket_duration
      in: query
      description: '''Intervals duration in the form of an integer plus `m` (minutes), `h` (hours), or `d` (days)'''
      example: 5m
      required: false
      style: form
      explode: true
      schema:
        type: string
    Content-Type:
      name: Content-Type
      in: header
      description: 'Content-Type: application/json'
      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:
    LiveDimensions:
      enum:
      - video
      - video,country
      - video, device_type
    Get_Events_Response:
      title: Get Events Response
      type: object
      description: Get live events success response
      example:
        data:
        - dimensions:
            country: US
          totals:
            live_unique_viewers: 1267
            video_seconds_viewed: 126755
            alive_ss_ad_start: 1274
        - dimensions:
            country: GB
          totals:
            live_unique_viewers: 2267
            video_seconds_viewed: 136005
            alive_ss_ad_start: 1024
      properties:
        data:
          type: array
          description: array containing metrics per dimension(s)
          items:
            type: object
            description: object containing `dimensions` and `totals` objects
            properties:
              dimensions:
                type: object
                description: Object containing dimension/value that the associated metrics are for
              totals:
                type: object
                description: Object containing metric/value pairs for the associated dimensions
    Get_Time_Series_Response:
      title: Get Time-Series Response
      type: object
      description: Get Live time-series success response
      example:
        video_impression:
          data:
          - dimensions:
              video: '6063969160001'
              account: '57838016001'
            points:
            - timestamp: 1564075800000
              value: 11.0
            - timestamp: 1564077600000
              value: 3.0
        video_view:
          data:
          - dimensions:
              video: '6063969160001'
              account: '57838016001'
            points:
            - timestamp: 1564075800000
              value: 11.0
            - timestamp: 1564077600000
              value: 1.0
        video_seconds_viewed:
          data:
          - dimensions:
              video: '6063969160001'
              account: '57838016001'
            points:
            - timestamp: 1564075800000
              value: 3185.0
            - timestamp: 1564077600000
              value: 514.0
        alive_ss_ad_start: {}
        fingerprint_count:
          data:
          - dimensions:
              video: '6063969160001'
              account: '57838016001'
            points:
            - timestamp: 1564075800000
              value: 9.0
            - timestamp: 1564077600000
              value: 6.0
            - timestamp: 1564079400000
              value: 1.0
        ccu:
          data:
          - dimensions:
              video: '6063969160001'
              account: '57838016001'
            points:
            - timestamp: 1564075800000
              value: 9.0
            - timestamp: 1564077600000
              value: 6.0
            - timestamp: 1564079400000
              value: 1.0
      properties:
        interval:
          type: array
          description: array containing the start and end points for the interval in the units specified by the `bucket_duration` parameter
          items:
            type: integer
        dimensions:
          type: object
          description: A set of dimension/value pairs corresponding to the dimensions specified in the `dimensions` parameter
        points:
          type: array
          description: An array of objects containing metrics for the points in the time-series
          items:
            type: object
            description: An object containing the `timestamp` value (in the units specified in the `bucket_duration` parameter) and values of the metrics (specified in the `metrics` parameter) at the timestamp
    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: ''
  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