Echo360 Reporting API

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:

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.

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.

Confusion by User Report

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:

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:

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.

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

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.

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: