Introduction

Aggregations are designed to help you monitor and analyze activities on your platform in real time. With aggregations, you're able to create advanced velocity checks that can detect suspicious patterns in all sorts of activities, both transaction and non-transaction. For example, compute the average transaction amount per user in the last 24h:

Example Aggregation: Average transaction amount per user in the last 24h

Example use-cases

Some examples of what Aggregations can be used for are:

Fake account creation: Aggregations can detect unusual patterns of new account registrations from the same IP address, device, or in a short time period, helping you identify and prevent fake account creation and potential spam activities.
Click to create
Content spamming: By monitoring the frequency and patterns of content submissions, such as comments, reviews, or posts, Aggregations can flag users who may be engaging in spamming or other abusive behaviors.
Password cracking attempts: Aggregations can track multiple failed login attempts or password reset requests within a specific time frame or from a single IP address, alerting you to potential brute-force or account takeover attempts.
Rate-limit abuse: If your platform imposes rate limits for certain actions (e.g., API calls or messaging), Aggregations can detect and flag users who repeatedly exceed these limits, indicating potential abuse of your system's resources.
Click to create

Creating Aggregations

Aggregations are created and managed from the Aggregations page in the Castle Dashboard, and any user that has the admin role will be able to access it. In this page here you'll find the list of existing Aggregations as well as the ability to create a new one.

Creating a new aggregation consists of a few parameters that make out the final definition. For those familiar with SQL, parameters for an Aggregation are overall very similar to the parts that make up a (streaming) SQL statement, e.g.

SELECT $count_unique(properties.referral_code)
FROM events
WHERE name = 'Redeem'
GROUP BY user.id
WINDOW (SIZE 1 HOUR)

Parameter	Description
Name	A short description of the Aggregation, like "Transactions per user". This will be used as a reference across the Castle Dashboard, e.g. when creating new filters and/or policies
Description	An optional longer description to communicate the intent with this Aggregation. This can be useful for other team members to better understand the behavior
Method	The aggregation method together with a potential argument. Available options are - Average ($avg) - Count Events ($count) - Count Unique ($count_unique) - First Value ($first) - Last Value ($last) - Max Value ($max) - Minimum Value ($min) - Sum ($sum)
Group By	An optional argument that describes a grouping for the aggregation. For example, you can pick `user.id` to split up transaction volume per user instead of computing it across the entire app.
Where	Define optional filters to apply before computing the aggregation. For example, you can filter by `$transaction` type events to count all transactions per user.

The output from each aggregation is a value (typically a number) that is persisted and available on each event. This means that if you e.g. created an aggregation with the name "Transactions per user", this value will be available to use in the filters dropdown. More on this in the next section.

Taking action

Once you've created and activated an Aggregation, it'll immediately be available to use in filters and policies. This means that you can use the Explore view to find an appropriate threshold for your new Aggregation value. For example, if you've created an Aggregation for "Invites sent per user per hour", you'll be able to try different thresholds on historic data, to find a value that best seem to represent fraudulent users.

Creating a Policy

Once you've found a filter setting in the Explore view that you're happy with (see next section for some useful tips), you can quickly create a Policy to instruct your app that users should be challenged or denied when this condition applies. Simply click "Create a Policy" in the top right corner:

Quickly create a Policy that uses an Aggregation

Tips for finding a good threshold

Use your business knowledge and intuition as a starting point: is it reasonable that a given user sends more than 1 invitation to a friend within one hour? more than 5, 10? There might even be two thresholds: one level which is suspicious and warrants additional investigation, and one which is clearly excessive and where the account should be suspended (see the section on webhooks for how to set up such automation).

While looking at data is very useful to guide the decision of setting thresholds, it's important to remember that you may not have enough recent historic data to find a good threshold, which could lead to overfitting. It is always a good idea to sanity check and adjust the number by using your expertise to apply more context. In the end, you'd want to provide a reasonable explanation for suspending or blocking users.

It might also be helpful to think if the threshold should vary with some other criteria, such as applying a stricter threshold for sending invites to newer accounts, or increasing the threshold when the users show signs of good behavior, such as verifying their identify.