Brightcove Analytics Report API
Full analytics reports with many options for filtering, date ranges, formats, and more.
OpenAPI Specification
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