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
/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 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 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 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 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 |
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.
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 |
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
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 |
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 |
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.