The reporting API provides self-service, programmatic access to data that Echo360 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 that 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

Make a call requesting a report
Take note of the report request ID returned
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
When you get back an Available status, retrieve the extended request info. which will include a signed S3 URL
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

It takes time to build a report 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 status associated with a submitted report request.

There is also delay associated with source data - 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 further 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, as well as 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	media identifier (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 device type
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 for a period of UP TO 7 days in length, for a period 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	media identifier (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 device type
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 section identified

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

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.

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

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	The date/time this viewing event occurred (in UTC)
sessionId	The system ID of the session generated by this viewing event. This ID can be used to 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 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	The system ID of the media being viewed in this event
mediaName	The name of the media being viewed in this event
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	The system ID of the Echo360 course where the viewing event occurred (if applicable)
courseCode	The number or unique identifier for the Echo360 course where the viewing event occurred (if applicable)
courseName	The name of the Echo360 course where the viewing event occurred (if applicable)
sectionId	The system ID of the Echo360 section where the viewing event occurred (if applicable)
sectionNumber	The number or other identifier of the Echo360 section where the viewing event occurred (if applicable).
lessonId	The system ID of the Echo360 class/lesson where the viewing event occurred (if applicable).
lessonName	The name of the Echo360 class/lesson where the viewing event occurred (if applicable).
userId	The system ID of the user who performed the viewing event.
firstName	The first name of the user who performed the viewing event.
lastName	The last name of the user who performed the viewing event.
userEmail	The email address of the user who performed the viewing event.
userRole	The role the user is logged in as when performing this viewing 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 (0^th 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 playback speed that was set at the time this session status was recorded. 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 that was set at the time this session status was recorded 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 at the time this session status was recorded (in milliseconds). 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	The date/time, in UTC, this viewing event (the session or beacon entry) occurred
sessionId	The system ID of the viewing session that applies to this beacon
mediaId	The system ID of the media being viewed in this session
mediaName	The name of the media being viewed in this session
userId	The system ID of the user performing the view session
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 (0^th 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	Whether or not the transcript panel was open/visible at the time of this session beacon – TRUE/FALSE
ccActive	Whether or not the closed captions were enabled/visible at the time of this session beacon – TRUE/FALSE

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

Identifier: polling

New responses and updates to existing responses for poll questions.

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 supplied by user
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

Question and Answer by User Report

Identifier: qanda

New responses or updates to existing responses for Q&A. Does not include questions that have no responses.

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

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

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.

API

API Endpoints Paths

Reporting Workflow

Processing and Retention

Output

Endpoints

Limitations

Report Definitions

Asset Report

Asset By Date Report

Presentation Report

Video Views by User Report

Media View Sessions Report

Media View Session Details Report

Confusion by User Report

Polling by User Report

Question and Answer by User Report

Notes by User Report

Examples

Report Example

Reports Endpoint Examples

Asset report Example

User related report Example

Requests Endpoint Example

Submitting a Request Example

Article Sections

Related articles