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:

• US
• AP
• CA
• EU

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

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.

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

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": {"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.