Saved Cohorts

This guide assumes you are familiar with users and companies already. If not, please review the Introduction to User and Company Analytics

A saved cohort is a dynamic list of users (or companies) that match some specific criteria. That criteria can be specific user/company properties or based on what the user/company performed in terms of API calls and custom actions. Because these lists are dynamic, Moesif continuously updates them in the background.

Note that events may take up to 20 minutes to show up in the user analytics screens. If your data has not shown up, please try again later once the data has had time to filter over.

Some examples of cohorts might be:

  • Users who are exceeding rate limits in the last 24 hours
  • Users who accessed your API with over 10 distinct IP Addresses per hour
  • Companies who have unpaid invoices

Saved cohorts are extremely powerful as they can be used as targeting criteria through Moesif to accomplish things like:

Creating a cohort

To create a new cohort, press the Create New button on the left navigation pane and select either User Cohort or Company Cohort.

Create cohort from Create New button

Cohorts support filtering on both user/company fields along with the events that a user/company performed. Event fields also support how often the user or company performed the events within a period.

As an example, let’s say we want to create a cohort for users who were close to API rate limits at least 5 times in the last 24 hours.

To do so, we can add a filter response.headers.Ratelimit-Remaining < 10. We should also specify we only want to match uses who performed this at least 5 times in the last 7 days. When you add the filters, a preview of all users that match your criteria is shown. We can also add filters on user metadata such as the user’s plan is not an enterprise plan.

Create cohort of users approaching rate limits

You can also easily create a cohort when using either the user (or company) lookup and adding your customer targeting criteria. Once your chosen criteria is added, select Create Cohort at the top right and give your cohort a friendly name.

Filtering on event time

If you want to add a filter based on when an event occurred, you can use the field Occurrence Times. For example, if you want to create a behavioral cohort for all users who performed an event more than 24 hours ago, add a filter for Occurrence Times and set it to “is before 24 hours ago”.

The cohort may take up to 15 minutes to process before matching users/companies are added to automation workflows like behavioral emails and sampling.

Filtering based on billing period/term

In the Date Range dropdown (just under the Who performed section of the filter), you can also select the following values that can bucket results based on the user/company’s billing start and end dates:

  • Current Monthly Billing Period
    • This will only factor in events that have happened in the user/company’s current monthly billing period.
  • Last Monthly Billing Period
    • This will only factor in events that have happened in the user/company’s last billing period that has already passed.
  • Current Billing Term
    • This will only factor in events that have happened in the user/company’s current term. If their term is quarterly or yearly, this will show all of the events within that term. For monthly, it will display the same as the Current Monthly Billing Period option.

This can be especially useful for anyone using Moesif for API monetization since Governance Rules can be created from cohorts to control access to an API based on a users subscription terms. For example, you may create a governance rule where a users subscription tier only allows them to consume 10,000 API calls per month. By using the options above, specifically Current Monthly Billing Period in this case, cohorts can now be created to accurately ensure that users stay within their limits during based on their unique billing period start and end dates.

Accessing saved cohorts

Once a cohort is saved, you can view matching users/companies and modify targeting criteria by going to User Cohorts or Company Cohorts on the left navigation pane. From here, you can select a cohort to open it’s filter view.

View previously saved user cohort

From there, you can modify its filter criteria and then select Save Cohort at the top right.

Using cohorts

Now that your cohort is created, you can select it in any of Moesif’s automation features. For example, to set up a recurring email that reminds those users they are running into rate limit issues, go to Behavioral Emails on the left navigation pane. Here, we can select the cohort we created previously, Users who are exceeding rate limits in last 24 hours.

View previously saved user cohort

Advanced features

Numeric aggregations

Besides equality, event fields also support aggregations such as average, max, or distinct. For example, we can create a cohort of users who accessed your API with over 10 distinct IP Addresses per hour anytime over the last 7 days Similarly, you can create a cohort of users who’s average latency is over 1 second. This can be done like so:

Users with over 10 distinct IP addresses per hour in last 7 days

Grouping filters

You can also add groups of filters enabling order of operations. For example, we want to match users who either 1. Had an order 500 error only when they placed a buying order OR 2. made an explicit API call to decline. The group option AND is also available.

Saved cohort filters order of operations

Updated: