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:
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
/reportsendpoint shows available reports by name, as well as the parameters required when submitting. - The
/requestsendpoint 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/endparameters
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 capture0 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 transcribed0 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 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 capture0 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 transcribed0 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 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 |
| 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 |
| user email | |
| role | institution level user role |
Live Views Report
Identifier: liveviews
Non-aggregated live stream and live classroom view events with user associations.
The report includes "scope" entries that identifies 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 | system identifier of the user performing the event (UUID) |
| firstName | first name (given name) of the user performing the event |
| lastName | last name (surname) of the user performing the event |
| 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 of the event in UTC |
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 (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 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 (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 |
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 |
| user email | |
| role | institution level user role |
Polling by User Report (presentations)
Identifier: polling
New responses and updates to existing responses for poll questions located in Presentation media.
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 |
| user email | |
| role | institution level user role |
Polling by User Report - Version 2 (all media types)
Identifier: pollingv2
All student response actions to polling questions in both presentation and interactive media.
Note that unlike the original Polling by User Report (above), this report may contain multiple row entries for each answer provided by a student if a student edited their poll response (polling slides only).
Input parameters:
start: start date (UTC, inclusive)end: end date (UTC, exclusive)
| Output | |
|---|---|
| mediaId | System ID (UUID) of the media |
| mediaName | Name of the media |
| sectionId | System ID (UUID) of the Echo360 section where the response occurred (if applicable) |
| sectionNumber | Number or other identifier of the Echo360 section where the response occurred (if applicable) |
| courseId | System ID (UUID) of the Echo360 course where the response occurred (if applicable) |
| lmsCourseId | LMS system ID for the LMS Course where the response occurred (if applicable) |
| courseIdentifier | Number or unique identifier as displayed in the UI for the Echo360 course where the response occurred (if applicable) |
| lmsCourseIdentifier | LMS course code or unique identifier as displayed in the UI for the LMS course where the response occurred (if applicable) |
| courseName | Name of the Echo360 course where the response occurred (if applicable) |
| 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 text or selection area of the poll (if applicable) |
| 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 of when the response was provided |
| answerId | System identifier (UUID) of the response given by user |
| answer | Response given by the user to this poll |
| userId | System identifier (UUID) of the user |
| firstName | User first name |
| lastName | User last name |
| Email address of the user | |
| role | Echo360 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 |
| 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.