Aggregations

This endpoint retrieves aggregated data related to a specific module identified by {module}. It allows querying and aggregation of data based on various parameters such as grouping, aggregation functions, sorting, filtering, and dimensions.

Endpoint

GET /api/modules/{module}/aggregations

This endpoint accepts a {module} path parameter (e.g., user, products) to specify the data source.

Request Parameters

All parameters are query parameters:

Parameter	Type	Description & Example
group-by	array of strings (comma-separated)	Specifies the fields to group the data by. /api/modules/orders/aggregations?group-by=customer_id,region
aggregates	array of strings (comma-separated)	Defines the aggregation functions to apply. See Supported Aggregation Functions below. /api/modules/products/aggregations?aggregates=count(id),sum(price),avg(rating),min(price),max(price),some(description)
limit	integer	The maximum number of aggregated results to return. Default: 1000 Minimum: 1
sort	array of strings (comma-separated)	Controls the sort order of the aggregated results. Fields can be prefixed with + for ascending or - for descending (e.g., +name, -total_sales) Alternatively, you can use the :asc or :desc postfix (e.g., name:desc, created_time:asc) /api/modules/user/aggregations?sort=-registration_date,+username
query	string	An alias for the query parameter.
dimensions	string	Used for specific dimensional filtering. /api/modules/sales/aggregations?dimensions=channel%20%3D%20%27online%27%20AND%20locale%20%3D%20%27en_US%27

Supported Aggregation Functions

The following aggregate functions are available in the aggregates parameter:

Function	Argument	Return Type	Description
count(<f>)	field or *	integer	Number of non-null values of <f>. count(*) counts all rows in the group.
sum(<f>)	numeric field	numeric	Sum of all non-null values of <f>.
avg(<f>)	numeric field	numeric	Arithmetic mean of all non-null values of <f>.
min(<f>)	comparable field	same as <f>	Smallest non-null value of <f>. Works on numeric, date, and string fields.
max(<f>)	comparable field	same as <f>	Largest non-null value of <f>. Works on numeric, date, and string fields.
some(<f>)	field	boolean	true if at least one record in the group has a non-empty value in <f>, otherwise false. For string fields, NULL and empty string ('') count as empty; for numeric, date, and boolean fields, only NULL counts as empty.

Aggregate function names are case-insensitive (COUNT, count, and Count are equivalent).

Response Structure (HTTP 200 OK)

The response will be a JSON object containing a result array. Each object within the result array represents a row of aggregated data, with keys corresponding to your group-by fields and the names of your aggregates.

{
  "result": [
    {
      "group_field_1": "value1",
      "group_field_2": "valueA",
      "count(id)": 150,
      "sum(price)": 15000.75,
      "avg(rating)": 4.32,
      "min(price)": 9.99,
      "max(price)": 499.00,
      "some(description)": true
    },
    {
      "group_field_1": "value2",
      "group_field_2": "valueB",
      "count(id)": 90,
      "sum(price)": 8000.20,
      "avg(rating)": 3.87,
      "min(price)": 14.50,
      "max(price)": 299.00,
      "some(description)": false
    }
  ]
}

Supported Fields

Only native and not list fields are fully supported in the group-by, aggregates, and sort parameters. Support for other fields and relationships is experimental and not guaranteed.