Introduction to Large Group Reporting

Learnosity's aggregate reports are a sophisticated tool for analyzing the results of large cohorts up to 200,000 users. Aggregate reports provide a browsable view of assessment results, summarized into custom-defined groupings of users:

  • View summarized statistics for each group of users including mean, median, percentiles, standard deviation and more.
  • Explore, browse and drill down to compare results between groups, and see scores for individual users.
  • Define user groupings based on region, school, class, course, department, demographics, or any other arbitrary data. Groups are defined as a hierarchy to support drill down and summary functionality.
  • Retrieve raw data for any level of the group hierarchy to build custom reports, dashboards and comparisons.
View Aggregate Reports demo 


There are two kinds of aggregate reports, to support different methods of selecting the desired assessment data:

  • Activity summary by group: summarizes results using up to 10 activity identifiers. Each user's most recent attempt of the Activity is included.
  • Sessions summary by group: summarizes results using up to 50 specific session identifiers for each user.
Aside from the selection criteria, the two reports offer the same analytical capabilities.


For performance and scalability, aggregate reports are generated asynchronously via Data API and then retrieved in browser via Reports API. See the implementation guide for details.

Aggregate reports use the following terms:

    • Group: a set of users for whom aggregate data will be generated. The group report shows aggregated statistics for a set of groups. User-level data may also be requested during generation, allowing drill down to the specific results of individuals within a group.

    • Group hierarchy: groups are defined as a nested hierarchy. The top level groups have an implicit “root” parent. All groups below the top level have exactly one parent group. Each group implicitly contains all members of its descendent groups.

    • Group key: the string identifier for a level of the group hierarchy. For example, a group report for educational districts might define the following 3 group keys: "state", "district", "school".

    • Group label: the human readable name for a group key.

    • Group name: the human readable name for a specific group in the hierarchy. Each group name implicitly belongs to a group key, which identifies the group’s level in the hierarchy. For example, a group key of "state" may contain four group names: "arizona", "california", "oregon", "washington". Two groups may have the same name but different parent groups, as in the below example where Illinois and Oregon have district groups named "springfield" and school groups named "springfield_high":

      ["illinois", "springfield", "springfield_high"]
      ["oregon", "springfield", "springfield_high"]
    • Group path: a collection of group names identifying a path through the group hierarchy. A group path is written as a JSON array, starting with the top level group name. A group path can point to any level of the hierarchy. For example:

["washington", "seattle", "franklin_high"]
  • Group ID: a machine-generated unique identifier for a specific group path, formed as a one-way hash of the group path. The group ID is not human readable.

  • Dataset: the set of raw data files for a group report. A large dataset can consist of many thousands of files, each containing the aggregated results for a specific group of users. The dataset is generated asynchronously using Data API. Once completed, the dataset can be retrieved via Data API or rendered in-browser using Reports API.

The following limits apply to aggregate reports:

  • Maximum of 200,000 users in the entire aggregation. Duplicate user_ids are disallowed.
  • You must always specify adataset_idwhen initialising the dataset.   
  • Maximum of 5 group keys in the group hierarchy (ie. 5 levels in the group tree).
  • Maximum of 1000 immediate children for any parent group. For example, a 3 level group hierarchy may define <= 1000 states, with each state comprising <= 1000 districts, and each district comprising <= 1000 schools.
  • Maximum of 10 activities in the activity-summary-by-group report filters. This report uses Completed session status only. 
  • Maximum of 50 sessions per user in the sessions-summary-by-group report. This report uses Completed session status only. 
  • Maximum length for a group_key is 36 bytes (ie. a UTF-8 encoded uuid).
  • Maximum length for a group_name is 36 bytes (ie. a UTF-8 encoded uuid).
  • After a session is submitted, it will be approximately 1 hour before it is available for large group reporting.

Was this article helpful?

Did you arrive here by accident? If so, learn more about Learnosity.