Chat with us, powered by LiveChat Skip to main content
Echo360 Status: 

EchoVideo: Reporting API

Hannah Petty
  • Updated

The reporting API provides self-service, programmatic access to data that EchoVideo has recorded about activity on the platform. This includes data on video views, classroom interaction such as questions and polls, and user engagement. The data included in some reports can be customized, such as limiting the results over a specific time range. The output format can also be specified.

For details on routes and request / response formats see the Swagger UI under /reporting in your preferred region:

SwaggerDocs web interface with Reporting API endpoints and descriptions shown as described

See Using Swagger Docs UI for API Calls for information on using the public API in general, including generating access credentials.

API Endpoints Paths

The path for the reporting API is /public/api/v1/reporting/. All further references to paths assume this prefix. The base URL depends on the desired region. For example, the full URL in the US region for the /reports endpoint is https://echo360.org/public/api/v1/reporting/reports.

All dates should be supplied in UTC. All timestamps are in UTC, both in the API request tracking and in assets.

Reporting Workflow

  1. Make a call requesting a report.
  2. Take note of the report request ID returned.
  3. Periodically poll to check the status of your report request. Potential statuses are:
    • Pending - the report request is queued or currently running
    • Available - the report request is complete and available for download
    • Expired - the report results are no longer available, submit again
    • Failed - the report execution failed
    • Missing - the report was not executed for an extended period
  4. When you get back an Available status, retrieve the extended request info. which will include a signed S3 URL.
  5. Use signed S3 URL to download your requested report.

In some rare circumstances, the report execution can fail (indicated by the Failed and Missing statuses). Try again or contact support with the associated request ID.

Processing and Retention

Building a report takes time due to queueing delays, data extraction, and processing. A delay of up to several hours is expected. The API can be queried at any time for the status associated with a submitted report request.

Source data also has a delay—for some reports, complete data for a given day is not available until the following day, and additional delay may be present depending on when certain background processing happens in different regions. In general, data for a given day is complete 48 hours after the close of that day (in UTC).

Reports are available for 14 days from the report submission, after which they are permanently deleted. Only the report associated with a particular request is deleted; the source data from which it is produced is never deleted. Submissions, where reports have been deleted, show as status Expired. Reports can be re-requested if needed, though they will have to be processed again.

Output

By default, the reports are provided as gzipped CSV files. Once decompressed, they can be imported directly into Excel or processed using standard CSV libraries.

Compression can be disabled using the output.compression flag. The CSV delimiter can be specified using the output.delimiter option; tab \t (TSV) and pipe | (PSV) are also supported.

Endpoints

  • The /reports endpoint shows available reports by name and the parameters required when submitting.
  • The /requests endpoint shows the submitted requests for reports. Requests have a unique ID, a status, a creation timestamp, the report name and parameters of the request, and any assets produced by the completed request.

Limitations

A limited number of in-flight reports are allowed. If this limit is reached, you must wait until a previously submitted report finishes before submitting another.

For reports with time interval parameters (start and end), the requested interval is restricted. For longer intervals, separate requests must be submitted with smaller sub-intervals.

Current restrictions are:

  • 3 in-flight reports
  • 7-day range for start/end parameters

Date ranges specified via start and end include start but exclude end; that is, start <= interval of interest < end. This means that for adjacent contiguous time ranges, the end of the earlier range is equal to the start of the later range.

Report Definitions

Asset Report

Identifier: asset

Engagement for all video assets. These counts are for all time; no date parameters are supplied.

Output
video_name video name
create_date video creation timestamp (UTC)
section_number section number
owner_name owner first name, last name
mediaid system identifier of the media (UUID)
scheduled 1 if from a scheduled capture
0 otherwise (ad hoc captures)
course_identifier course identifier (UUID)
organization_name organization name
department_name department name
room_name room name
building_name building name
campus_name campus name
term_name term name
transcribed 1 if the video has been automatically transcribed
0 otherwise (no transcription)
device capture source / device type that created the asset, including Zoom or OneDrive where applicable
video_duration_in_minutes video duration in minutes
last_view timestamp (UTC) of the most recent video view
view_count total number of video views
downloads total number of downloads
view_duration_in_minutes cumulative view time for all users and views
public total number of views resulting from public links
private total number of views from sources other than public links
live total number of views from a live stream, if any
on_demand total number of video-on-demand (VOD) views
published_date the date this video was published to the identified section

Asset By Date Report

Identifier: assetbydate

Engagement for all video assets within the identified date range. Start and End date parameters are required. The range can be up to 7 days in length and up to one year prior to the date the report is requested (current date).

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
video_name video name
create_date video creation timestamp (UTC)
section_number section number
owner_name owner first name, last name
mediaid system identifier of the media (UUID)
scheduled 1 if from a scheduled capture
0 otherwise (ad hoc captures)
course_identifier course identifier (UUID)
organization_name organization name
department_name department name
room_name room name
building_name building name
campus_name campus name
term_name term name
transcribed 1 if the video has been automatically transcribed
0 otherwise (no transcription)
device capture source / device type that created the asset, including Zoom or OneDrive where applicable
video_duration_in_minutes video duration in minutes
last_view timestamp (UTC) of the most recent video view
view_count total number of video views
downloads total number of downloads
view_duration_in_minutes cumulative view time for all users and views
public total number of views resulting from public links
private total number of views from sources other than public links
live total number of views from a live stream, if any
on_demand total number of video-on-demand (VOD) views
published_date the date this video was published to the identified section

Presentation Report

Identifier: presentation

Engagement for presentations (slide decks). Each row represents a user view of a presentation.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
presentationID presentation identifier (UUID)
presentationName presentation name
sectionId section identifier (UUID)
sectionNumber section number
courseId course identifier (UUID)
courseIdentifier course identifier as displayed in the UI
courseName course name
event_timestamp timestamp in UTC
userid user identifier (UUID)
firstname user first name
lastname user last name
email user email
role institution level user role
slide_count total slide count for presentation

Video Views by User Report

Identifier: videoview

These are non-aggregated video view events with user associations. Each event indicates 30 seconds of watched video. This report returns data for views that occurred in a classroom, through a Group, or through the media details page for video or audio media.

Classroom, Group, and Media Details page views before 2024 are tracked in the videoview report.

For view data of interactive media, or from the public or embedded player, see the Media View Sessions Report below.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
videoId video identifier (UUID)
videoName video name
sectionId section identifier (UUID)
sectionNumber section number
courseId course identifier (UUID)
courseIdentifier course identifier as displayed in the UI
courseName course name
event_timestamp timestamp in UTC
duration_Minute total video duration in minutes
userid user identifier (UUID)
firstname user first name
lastname user last name
email user email
role institution level user role

Confusion by User Report

Identifier: confused

Non-aggregated events indicating that a user marked a presentation slide as confusing.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
PresentationID presentation identifier (UUID)
PresentationName presentation name
sectionId section identifier (UUID)
sectionNumber section number
courseId course identifier (UUID)
courseIdentifier course identifier as displayed in the UI
courseName course name
event_timestamp timestamp in UTC
userid user identifier (UUID)
firstname user first name
lastname user last name
email user email
role institution level user role

Polling by User Report - presentations

Identifier: polling

Student responses given for poll questions located in Presentation media.

NOTE: The data from this report is also available in the Polling by User Report - V2, which contains additional information and is described immediately below. This V1 version of the Polling by User Report is scheduled to be deprecated on June 30, 2022. Please transition to using the newer version prior to that date.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
presentation_id presentation identifier (UUID)
presentation_name presentation name
sectionId section identifier (UUID)
sectionNumber section number
courseId course identifier (UUID)
courseidentifier course identifier as displayed in the UI
courseName course name
activity_id activity identifier (UUID)
activity_prompt question text
activity_content JSON record of available poll responses
solution correct answer
event_timestamp timestamp in UTC
answer_id answer identifier (UUID)
answer answer text
isCorrect DEPRECATED, do not use
userid user identifier (UUID)
firstname user first name
lastname user last name
email user email
role institution level user role

Polling by User Report - Version 2 - all media types

Identifier: pollingv2

All student responses to polling questions in both presentation and interactive media.

This version of the Polling by User Report is replacing the Polling by User Report - presentations (described immediately above). The previous version will be deprecated on June 30, 2022. If you have not yet, please transition to using this version of the report as soon as is feasible for your institution.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
mediaId system identifier of the media (UUID)
mediaName name of the media
sectionId section identifier (UUID)
sectionNumber section number
courseId course identifier (UUID)
lmsCourseId LMS system ID for the LMS Course where the response occurred (if applicable)
courseIdentifier course identifier as displayed in the UI
lmsCourseIdentifier LMS course code or unique identifier as displayed in the UI for the LMS course where the response occurred (if applicable)
courseName course name
lmsCourseName Name of the LMS course where the response occurred (if applicable).
pollId System ID (UUID) of the poll 
pollPrompt Question text of the poll
pollContent JSON record of available poll responses
solution correct answer
action

Action performed on the response given by the student. Can be Created, Updated, or Deleted.

If multiple actions apply, they will occupy multiple rows in the report.

Updated actions only apply to polling slides where students can edit their responses.

Deleted actions only occur if the poll is deleted after students responded.
eventTimestamp timestamp in UTC
answerId answer identifier (UUID)
answer answer text
userId user identifier (UUID)
firstName user first name
lastName user last name
email user email
role institution level user role

Question and Answer Report

Identifier: qanda

Discussion posts / questions and, where applicable, corresponding responses / answers for course Q&A / Discussions. 

NOTE: The data from this report is also available in the Question and Answer Report- Version 2, which contains additional information and is described immediately below. This V1 version of the Question and Answer Report is scheduled to be deprecated on June 30, 2022. Please transition to using the newer version prior to that date.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
questionid question identifier (UUID)
question question text
sectionId section identifier (UUID)
sectionNumber section number
courseId course identifier (UUID)
courseIdentifier course identifier as displayed in the UI
courseName course name
question_userid question creator user identifier (UUID)
question_firstname question creator user first name
question_lastname question creator user last name
question_email question creator user email
question_role question creator institution level user role
answerid answer identifier (UUID)
answer answer text
event_timestamp timestamp in UTC
answer_userid answer creator user identifier (UUID)
answer_firstname answer creator user first name
answer_lastname answer creator user last name
answer_email answer creator user email
answer_role answer creator institution level user role

Question and Answer Report - Version 2

Identifier: qandav2

Discussion posts / questions and where applicable, corresponding responses / answers for course Q&A / Discussions.

This version of the Question and Answer report is replacing the V1 version of the report (described immediately above). The previous version will be deprecated on June 30, 2022. Please transition to using this version of the report as soon as is feasible for your institution.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
entity The item whose data occupies this row: Question or Response
action

Action performed on the response given by the student. Can be Created, Updated, or Deleted.

If multiple actions apply, they will occupy multiple rows in the report.
questionid question identifier (UUID)
question question text
sectionId section identifier (UUID)
sectionNumber section number
courseId course identifier (UUID)
courseIdentifier course identifier as displayed in the UI
courseName course name
questionUserId question creator user identifier (UUID)
questionFirstName question creator user first name
questionLastName question creator user last name
questionEmail question creator user email
questionRole question creator institution level user role
answerid answer identifier (UUID)
answer answer text
eventTimestamp timestamp in UTC
answerUserId answer creator user identifier (UUID)
answerFirstName answer creator user first name
answerLastName answer creator user last name
answerEmail answer creator user email
answerRole answer creator institution level user role

Notes by User Report

Identifier: notes

Metadata for created or updated notes.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
PresentationID presentation identifier (UUID)
PresentationName presentation name
sectionId section identifier (UUID)
sectionNumber section number
courseId course identifier (UUID)
courseIdentifier course identifier as displayed in the UI
courseName course name
content JSON blob describing noted content
note_count number of words in note
event_timestamp timestamp in UTC
userid user identifier (UUID)
firstname user first name
lastname user last name
email user email
role institution level user role

Media View Sessions Report

Identifier: viewsessions

Non-aggregated media view sessions with user associations and player detail. Each event is a view session of the corresponding noted status (SESSION_BEGIN, SESSION_END, SESSION_STALE).

This report returns data for views that occurred through any public link for media, for the embedded media player, including embedded interactive media, and for the media details page for interactive media only.

For view data of classroom views, Groups media views, and media details player views of video and audio media, see the Video Views by User report above.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
eventTimestamp timestamp in UTC
sessionId

system ID of the session generated by this viewing event

This ID can target or filter the Media View Session Details Report data, which provides specific viewing data for intervals (beacons) within sessions.
sessionStatus

The status of this viewing event entry. Can be any of three statuses as follows:

SESSION_BEGIN: A session is started when the media is loaded on the page (not necessarily when the user begins viewing).

SESSION_END: The viewing event ended either by the user actively closing the player or leaving the page, or closing the browser, or other action that ends viewing of the media.

Sometimes the browser gives us enough time to send the event and sometimes it doesn't.

SESSION_STALE: The viewing session timed out. This session time-out will occur automatically after 48 hours of inactivity.

Technically speaking, the player tries to fire a beacon but has not encountered any event within the past 48 hours. It refreshes the session, entering a SESSION_STALE event, followed often by a SESSION_BEGIN event (and a new session) on refresh.

mediaId

system identifier of the media (UUID)

mediaName

name of the media

mediaDuration

The total length of this media in minutes

lmsCourseName

The name of the LMS / VLE course where the viewing event occurred (if applicable)

courseId

course identifier (UUID)
courseCode

The number or unique identifier for the EchoVideo course where the viewing event occurred (if applicable)

courseName

course name

sectionId 

section identifier (UUID)

sectionNumber

section number

lessonId

The system ID of the EchoVideo class / lesson where the viewing event occurred (if applicable).

lessonName

The name of the EchoVideo class / lesson where the viewing event occurred (if applicable).

userId

user identifier (UUID)

firstName

user first name

lastName 

user last name

userEmail 

email address of the user performing the event

userRole 

current role of the user performing the event

intervalsPlayed

Array of intervals, in milliseconds, that were logged as viewed at the moment this session status was recorded.

For example, an entry of [[0,80000],[120000,160000]] means the user watched the video from the beginning of the media (0th second) to the 80th second, then skipped forward to view from the 120th second to the 160th second.

This field will always be blank for SESSION_BEGIN status.

playbackSpeed

The speed of playback set in the player at the time of this session beacon.

This will typically be 1x for SESSION_BEGIN as that is the default and state changes do not persist to subsequent view sessions.

Note that speed is shown in whole numbers corresponding to percentages. 1x speed is 100, 0.5x speed is 50, 2x speed is 200, etc.

playbackVolume

The volume of the playback set in the player at the time of this session beacon

This will typically be 100 for SESSION_BEGIN as that is the default and state changes do not persist to subsequent view sessions.

Note that volume is shown as a whole number corresponding to percentage. Full volume is 100, half volume is 50, etc.

playbackPosition

The location of the playhead in the player (in milliseconds) at the time of this session beacon.

For SESSION_BEGIN this will typically show 0, indicating the viewing session began at the beginning of the media.

This may show a value other than 0 for SESSION_BEGIN if the user stopped viewing in one session then resumed viewing in a subsequent session. In this instance, this value corresponds to the location of the playback at the time they reloaded the media for viewing, launching a new session. 

transcriptActive

Identifies whether the transcript panel was open (visible) at the time this session status was recorded – TRUE / FALSE

For SESSION_BEGIN this will typically be FALSE, as the transcript panel is closed by default and state changes do not persist to subsequent view sessions.

ccActive

Identifies whether the closed captions were turned on (visible) at the time this session status was recorded – TRUE / FALSE

For SESSION_BEGIN this will typically be FALSE, as closed captions are off by default and state changes do not persist to subsequent view sessions.

Media View Session Details Report

Identifier: viewsessiondetails

Non-aggregated video view events that include both the session Id and the beacon events that occurred within each session. Beacon events are sent approximately every 30 seconds and / or when a change in the player status warrants one.

This report applies to view sessions performed through any public link for media, for the embedded media player, including embedded interactive media, and for the media details page for interactive media only.

For view data of classroom views, Groups media views, and media details player views of video and audio media, see the Video Views by User report above.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
eventTimestamp

timestamp in UTC

sessionId

system ID of the session generated by this viewing event

mediaId 

system identifier of the media (UUID)

mediaName 

name of the media

userId

user identifier (UUID)

intervalsPlayed

Array of intervals that were watched for the duration of this session beacon, in milliseconds.

For example, an entry of [[0,10000],[120000,146000]] means the user watched the video from the beginning of the media (0th second) to the 10th second, then skipped forward to view from the 120th second to the 136th second.

playbackSpeed

The speed of playback set in the player at the time of this session beacon

Note that volume is shown as a whole number corresponding to percentage. Full volume is 100, half volume is 50, etc.

playbackVolume

The volume of the playback set in the player at the time of this session beacon

Note that speed is shown in whole numbers corresponding to percentages. 1x speed is 100, 0.5x speed is 50, 2x speed is 200, etc.

playbackPosition

The location of the playhead in the player (in milliseconds) at the time of this session beacon

transcriptActive

Identifies whether the transcript panel was open (visible) at the time this session status was recorded – TRUE / FALSE

ccActive

Whether or not the closed captions were enabled / visible at the time of this session beacon – TRUE / FALSE

Live Views Report

Identifier: liveviews

Non-aggregated live stream and live classroom view events with user associations.

The report includes scope entries that identify if the event was for the classroom where the live stream was playing or for showing / hiding the live stream itself (they are two separate user actions). Each event indicates either a Join or a Leave event for the scope indicated.

Note that LEAVE events are automatically generated (after anywhere from 32 to 62 seconds) for users who are in the classroom and (may be) viewing the Live stream but who close the window or browser without hiding the stream / exiting the classroom via normal exit selections.

Input parameters:

  • start: start date (UTC, inclusive)
  • end: end date (UTC, exclusive)
Output
mediaId system identifier of the media (UUID)
mediaName name of the media 
userId user identifier (UUID)
firstName user first name
lastName user last name
userEmail email address of the user performing the event
userRole current role of the user performing the event
scope

The type of event. Includes:

CLASSROOM (enter or exit the classroom) or

LIVE_STREAM (show or hide the live stream in the classroom)
event JOIN or LEAVE event for the scope of this entry
eventTimestamp timestamp in UTC

Media Copyright Report for a Year Report

Identifier: mediacopyrightyearly

Media copyright report for a year.

Output
mediaName name of the media 
mediaCreatedDate media creation timestamp (UTC)
currentDurationSec total duration of media in seconds
firstName user first name
lastName user last name
emailAddress user email
copyrightUpdatedDate media creation timestamp (UTC)
restrictDownload TRUE downloads are restricted
FALSE downloads are not restricted
restrictUnauthenticatedViewing TRUE Unauthenticated Viewing is restricted
FALSE Unauthenticated Viewing is not restricted
organizationName organization name
departmentName department name
courseidentifier course identifier as displayed in the UI
courseName course name
sectionNumber section number
lessonName name of the EchoVideo class / lesson where the viewing event occurred (if applicable).
captureName capture name
IsScheduledCapture TRUE if from a scheduled capture
FALSE otherwise (ad hoc captures)

Transcript Aggregate Report for a Year Report

Identifier: asryearly

Transcript aggregate report for a year filtered by institutionId.

Output
organizationName organization name
departmentName

department name
transcriptprovider

company that provided the transcript
transcriptionCount

how many transcripts were ordered
durationMs

total duration of transcripts in minutes
asrHours

total Automatic Speech Recognition used in hours
year

year the transcript is from
month

month the transcript is from

Caption Usage Yearly

Identifier: captionusage

Caption usage yearly report filtered by institutionId.

Output
institutionId institution ID
organization organization name
department department name
sectionNumber section number
caption_provider The name given to each caption profile created per institution.
provider The third-party provider used to create the caption, e.g., RevAI, 3playMedia, Verbit, etc.
captionsCount total number of captions created per provider
durationHours total duration of captions in hours
status The caption status is Initiating, Processing, Failed, or Processed.
CaptionType

Auto - captions are automatically created based on institution settings

Manual - the corresponding caption is either uploaded or is ordered manually from the Media Details page
createdAt shows the date and time of the last caption created using a caption profile.

Media Once Only Viewer Report

Identifier: media-once-only-viewers

Know how many users watched a video x% through and never came back.

Input parameters:

  • mediaId: media identifier (UUID)
Output
userId user identifier (UUID)
firstName user first name
lastName user last name
email user email
mediaId system identifier of the media (UUID)
mediaName name of the media
totalViewCount total number of media views (will always be 1)
totalWatchedDuration total video watch duration
view_perc percentage of media that was viewed

Media Recurring Viewers Report

Identifier: media-recurring-viewers

Know how many users watched a video x% through and came back.

Input parameters:

  • mediaId: media identifier (UUID)
Output
userId user identifier (UUID)
firstName user first name
lastName user last name
email user email
mediaId system identifier of the media (UUID)
mediaName name of the media 
totalViewCount total number of media views
totalWatchedDuration Total video duration, which includes the sum of durations if media is played multiple times.
view_perc percentage of media that was viewed

Top Viewed Media by Date Report

Identifier: media-top-view-count

Top viewed media by date.

Input parameters:

  • start: start date (UTC, inclusive)
Output
mediaid system identifier of the media (UUID)
view_count total number of video views

medis_name

 name of the media

Timestamp of When Students Watched a Media Report

Identifier: media-view-timestamp

Timestamp of when students watched a media.

Input parameters:

  • mediaId: media identifier (UUID)
Output
firstName user first name
lastName user last name
email user email
media_name media name
mediaid system identifier of the media (UUID)
view_timestamp at what time the media was viewed (UTC)
duration_seconds total viewed duration of media in seconds

Report on devices, OS, browsers, and versions used for video viewing

Identifier: media-access-metrics

Report on devices, OS, browsers, and versions used for video viewing.

Input parameters:

  • mediaId: media identifier (UUID)
Output
institutionid institution ID

userid

 user identifier (UUID)
firstName user first name
lastName user last name
email user email
mediaid  system identifier of the media (UUID)
mediaName name of the media
sessionid system ID of the session generated by this viewing event
url URL from which the media was played, i.e., Media Details page, class, collection, public link, etc.
referrer The URL from which the user clicked through to access the media. It usually contains the URL of the previous page that the user visited before requesting the current one.
browser browser that the user used to play the media
browser_version browser version
device The device used to access the media. Possible values are Tablet, Mobile, or Desktop.
operating_system The OS from which the media was played, i.e., Windows, Linux, Ubuntu, macOs, Android, etc.
accessed_on date and time user accessed the media

Report on playback like volume and speed at which user watched

Identifier: media-playback-metrics

Report on playback like volume and speed at which user watched.

Input parameters:

  • mediaId: media identifier (UUID)
Output
institutionid institution ID
userid user identifier (UUID)
firstName user first name
lastName user last name
email user email
mediaid  system identifier of the media (UUID)
mediaName name of the media
sessionid system ID of the session generated by this viewing event
playback_rate The playback speed set in the player - 100 means 1x, 150 means 1.5x, 50 means .5x speed.
volume The volume of the playback set in the player at the time of this session beacon

Report to see how many students watched a certain part of the video x amount of times

Identifier: media-user-engagement

Report to see how many students watched a certain part of the video x amount of times. Set endsec to 0 if we need to consider the entire media duration.

Input parameters:

  • mediaId: media identifier (UUID)
  • startsec: the time on the seekbar of the media when the user starts watching the media
    (numeric value of seconds
  • endsec: the time on the seekbar of the media when the user stops watching the media
    (numeric value of seconds)
Output
timelineinseconds This works like a heat map. We divide the media into 30-second chunks and track how many users watched each chunk. The term 'timelineInSeconds' refers to each 30-second segment of the media.
viewcount total number of media views

Report on the top medias by share count

Identifier: media-top-shares

Report on the top medias by share count. The parameter days is used to limit to the past x number of days.

Input parameters:

  • days: the past number of X days
Output
mediaId system identifier of the media (UUID)
mediaName name of the media
shareType The different types of ways media can be shared - Public Link, Secure Link, Course, and Shared with Users.
shareSubType Applies to secure links only. The two available types are VideoSecureLinkInfo and PlaylistSecureLink.
shareCount total media shares per share type

The average amount of time consuming the media

Identifier: media-view-percentage

The average amount of time spent consuming the media. If the content is 20 minutes long and students watch 10 minutes on average, the engagement is 50%. The start and end dates are inputs with just a date and no time. For the end date, we calculate based on midnight.

Input parameters:

  • mediaId: media identifier (UUID)
  • startdate: start date (UTC, inclusive)
  • enddate: start date (UTC, inclusive)
Output
mediaid  system identifier of the media (UUID)
total_view_count total number of media views
duration_seconds total duration of the media watched
average_view_duration_seconds SUM(Watch_duration) / SUM(view_count)
user_engagement_percentage (Total Content Duration / Average Watch Time) * 100
video_duration_seconds media duration in seconds
video_name media name
created creation date of media

Examples

Report Example

For the sake of this example, a fictional report visit is used. Actual reports contain too many columns for a short example. Assume the visit report defines the columns user, page, visit_count, and date. It has parameters start and end defining a date range. If a request were submitted for this report for February 2nd, 2020, the parameters would be start=2020-02-02 and end=2020-02-03 (end date is exclusive), and the output might be:

"user","page","visit_count","date"
"Alice","home",2,"2020-02-02"
"Alice","profile",1,"2020-02-02"
"Bob","home",4,"2020-02-02"

Since the request restricted the data to February 2nd, all records are from that date. If the same report were requested for February 2nd and 3rd, the parameters would be start=2020-02-02 and end=2020-02-04 and the output might be:

"user","page","visit_count","date"
"Alice","home",2,"2020-02-02"
"Alice","profile",1,"2020-02-02"
"Bob","home",4,"2020-02-02"
"Alice","home",2,"2020-02-03"

This contains all the same data as the previous report, but with one additional row for the activity from February 3rd, 2020. If a report were requested for only February 3rd, 2020, it would contain only that row.

Reports Endpoint Examples

Asset report Example

The asset report contains video engagement data. Since it contains aggregated data for all assets for their entire history, there are no date parameters.

Example listing:

{
  "name": "asset",
  "description": "Asset report",
  "note": "Engagement for all video assets",
  "parameters": []
}

User related report Example

The reports related to user activity consist of presentation, videoview, confused, polling, qanda, and notes. They all require a date range as parameters.

Example listing:

{
  "name": "presentation",
  "description": "Presentation slide views",
  "note": "Engagement for presentation slide views",
  "parameters": [
    {
      "name": "start",
      "datatype": "date",
      "required": true
    },
    {
      "name": "end",
      "datatype": "date",
      "required": true
    }
  ]
}

Requests Endpoint Example

Example listing:

{
  "requests": [
    {
      "requestId": "00000000-0000-0000-0000-000000000123",
      "status": "Available",
      "assets": [
        "00000000-0000-0000-0000-000000000456.csv.gz"
      ],
      "reportName": "asset",
      "parameters": {},
      "created": "2020-04-01T20:36:12.000Z"
    },
    {
      "requestId": "00000000-0000-0000-0000-000000000abc",
      "status": "Pending",
      "reportName": "notes",
      "parameters": {
        "start": "2020-02-08",
        "end": "2020-02-15"
      },
      "created": "2020-03-03T17:40:00.000Z"
    }
  ]
}

Data for a specific request is obtained through /request/<requestId>. This is also the only way to obtain a signed asset link. The signed link contains a lengthy signature parameter and must be used exactly as given. The link only works for a limited time (currently 7 days), or until the underlying asset expires (14 days from submission).

{
  "requestId": "00000000-0000-0000-0000-000000000123",
  "status": "Available",
  "signedAssets": [
    "http://some.url/00000000-0000-0000-0000-000000000456.csv.gz?Signature=xxx"
  ],
  "reportName": "asset",
  "parameters": {},
  "created": "2020-04-01T20:36:12.000Z"
}

Submitting a Request Example

To submit a request to generate an asset for a given report, use the endpoint POST /requests/<reportName>. Supply the required parameters as defined in the report listing. Also define output options to adjust the asset format.

For example, a POST to /requests/presentation might be:

{
  "parameters": {"start":"2020-01-01", "end":"2020-01-02"},
  "output": {
    "compression": true,
    "delimiter": "|"
    }
}

This would produce one day of data, and use a pipe (|) delimited output. It would also be gzipped as compression is enabled by default. The response repeats the supplied parameters as well as the generated request ID:

{
  "requestId": "00000000-0000-0000-0000-000000001234",
  "status": "Pending",
  "reportName": "presentation",
  "parameters": {
    "start": "2020-01-01",
    "end": "2020-01-02"
  },
  "created": "2020-04-01T00:00:00.000Z"
}

Here, the request ID 00000000-0000-0000-0000-000000001234 can be used to fetch the result, when available.

Related to