Reach out with questions, bugs, or suggestions. We'll respond ASAP. Your message is sent! We'll respond via email shortly.


The user list view is one of the most powerful and unique features Heap has to offer. List shows us granular user-level data of how people are interacting with our app. The list view presents lists of users in reverse chronological order based on the most recent activity. For each person, Heap shows all user properties associated with that individual as well as all their events grouped by sessions.

List Example

The following query shows us a chronological feed of our users, sorted by the time we last saw them. Each individual user entry shows their complete activity history on our app: page views, clicks, form submissions, touch events, and everything else Heap tracks. Show Result

If we click 'Show Results', Heap presents the first user in the list of the resulting query. At the top of each user's activity is their unique identifier, which by default is the Heap User ID, but you can replace this with either an email address or a handle via our Custom Identify API. In this example, we see that the email address is and the user was last seen 13 minutes ago.

On the left hand side of each user entry, we can see all user properties associated with this person. Heap automatically tracks user attributes such as Initial Referrer, UTM Source and the date first seen by Heap as Date First Seen. For a full description of user properties captured by default, please read our Data Format Documentation. Also, any custom properties such as Plan or Permissions sent via our Identify API are available in this list of properties.

For each user, Heap presents a list of all sessions in reverse chronological order. Each session shows the number of events Heap captured during the session and the duration of the session itself. Beneath the session description, the list view highlights the most common defined events within the session. Taking a look at the first session for this user, we see that Heap tracked 31 events and the session lasted 13 minutes.

If we open up the session, the list view shows all events that Heap captures automatically, which includes both defined and raw events. If an event is a defined event, Heap shows the defined event with a title and color marker. If an event is raw or undefined, the list view presents the event as a translucent object with the raw event name as the title.

When we click on one of the defined events, the list view presents all event properties. By default, Heap captures event properties such as Path and Domain, but other properties such as Screen Dimensions can be included using our Snapshots feature.

If we click on one of the undefined events, Heap presents both the event properties as well as an input field to define the event. Show Result

For the raw event that I've selected, I want to define it as 'Click on Project ID'. Once I click 'Define', the event will be available in list view (Click Show Results) and all other Heap analysis views.

Extending List View

Although a simple query for all users provides deep insights into user behavior, we can make list view more valuable by making more specific queries. The list view allows you to graph any segment of users and to filter the results in the same manner as all other analysis views in Heap. For example, I may want to create a list of all Active Users that Google referred to my site. To form this query, select the segment Active Users from the initial dropdown and create a filter where Initial Referrer equals Show Result

The resulting list provides us a list of all users in the segment Active Users referred by You can explore an example user in this list by clicking show results.

If the list returned by your query has several results, you can always export the list as a .CSV, which includes the properties of the last 5,000 users that meet the query definition.

Next Topic: Graph