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 user actions. Because these lists are dynamic, Moesif continuously updates them in the background.
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:
- Trigger behavioral emails to warn customers of issues like rate limits
- Block API abusers and threats from accessing your API
- Dynamically sample customers based on their behavior
Creating a cohort
To create a new cohort, go to either user (or company) lookup and add your customer targeting criteria. 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 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.
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.
Accessing saved cohorts
Once a cohort is saved, you can view matching users/companies and modify targeting criteria by going to Saved Cohorts under the users or companies tab. From here, you can select a cohort to open it’s filter view.
From there, you can modify its filter criteria and then select Save Cohort at the top right.
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 under the Alerting & Governance tab. Here, we can select the cohort we created previously,
Users who are exceeding rate limits in last 24 hours.
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:
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.