# Metrics API

The Metrics API has two main purposes:

Integrating with your visualization tools
Data Activation - using your metrics data as inputs to other processes

All API calls require x-api-token Authentication.

In order to retrieve metric results, you'll need to know some identifiers for your filters.

# Retrieving filters

The /filter-definitions endpoint requires an API key with Read permissions. Learn More

GET https://app.aggregations.io/api/v1/filter-definitions

Example Response

status: 200 OK

[{
		"id": "abc123456",
		"filter": "@.eventName =='AppOpen' && @.environment == 'Production'",
		"groupings": [
			"@.device.type",
            "@.app.version"
		],
		"groupingItems":[
			{
				"grouping": "@.device.type", 
				"alias": "Device Type"
			},
			{
				"grouping": "@.app.version",
				"alias": null
			}
		],
		"intervalType": "MINUTE",
		"intervalCount": 15,
		"name": "App Opens by Version & Device Type",
		"organizationId": "zzZyx123",
		"aggregations": [
			{
				"id": 1,
				"calculations": [
					"APPROX_COUNT_DISTINCT"
				],
				"calculationField": "@.userId",
				"subFilter": null,
				"name": "Unique Users"
			},
			{
				"id": 2,
				"calculations": [
					"SUM",
					"MAX",
					"MIN",
					"AVG",
					"PERCENTILES"
				],
				"calculationField": "@.notificationCount",
				"subFilter": "@.notificationCount > 0",
				"name": "Notifications Count (for users with notifications)"
			},
			{
				"id": 3,
				"calculations": [
					"COUNT"
				],
				"calculationField": null,
				"subFilter": null,
				"name": "Open Count"
			}
		]
	}]

This provides you with the relevant details you'll need to retrieve metrics.

# Groupings

You may notice both groupings and groupingItems have similar information - groupings was the original field before adding in the ability for individual groupings to be aliased. It is there for backwards compatibility only, groupingItems should be used going forward.

In this example, an alias has been set to make @.device.type a little easier to use when visualizing results.

# Metric Results

The /metrics/results endpoint requires an API key with Read permissions. Learn More

POST https://app.aggregations.io/api/v1/metrics/results

Parameter	Required	Type	Description
filterId ^f	✅	`string`	`id` of filter
startTime	✅	`string`	Start time (UTC) of desired range as ISO-8601 formatted string
endTime	✅	`string`	End time (UTC) of desired range as ISO-8601 formatted string
aggregationId ^f	✅	`int`	`id` of desired aggregation
calculation ^f	✅	`string`	Calculation to be performed, one of `COUNT`, `SUM`, `MIN`, `MAX`, `PERCENTILES`, `APPROX_COUNT_DISTINCT` (and must be present on the corresponding aggregation)
percentile	if `PERCENTILES`	`float`	Number > 0 & <= 1, of percentile desired.
limit	if `limitType` is supplied	`int`	Number of items to retrieve per interval, if excluded all results will return.
limitType	if `limit` is supplied	`string`	Whether to take the `TOP` or `BOTTOM` items per interval
includeIncompleteIntervals		`boolean`	If `false` then intervals not yet complete will be excluded, with a 10s buffer. Default is `true`
groupingFilters		`groupingFilterOption[]`	Grouping filters or aggregations to perform (see below)
recalculatedInterval		`interval`	Indicates how to re-calculate / rollup aggregations from initial interval. (see below)

An ^f above indicates a value you should retrieve from the /filter-definitions call

# `interval` Object

Parameter	Required	Type	Description
type	✅	`string`	One of `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `YEAR`
frequency	✅	`int`	The value representing how frequent you want the rollups.

For example, if you have an hourly metric and you want to roll up to the day, your recalculatedInterval would be:

{
	"type": "DAY",
	"frequency": 1
}

When using the recalculatedInterval option, you must ensure the requested rollup is greater or equal to the interval of the filter (you cannot turn a filter that is daily into hourly). Read more about intervals in the filter docs.

# Grouping Filters

The groupingFilters property defines how to handle any filtering / aggregating on individual groupings.

It is an array of objects like the following:

{
    "grouping": "@.device.type",
    "filters": ["ios", "android"],
    "returnGroupingValues": true
}

Parameter	Required	Type	Description
grouping	✅	`string`	the grouping value as defined on your filter.
filters		`string[]`	the list of values to be filtered as an array. `["$__agg"]` will result in all values being aggregated.
returnGroupingValues	✅	`boolean`	Whether or not to return grouping values in the response, or simply apply the filters to the provided groupings.

When considering your groupings, you can do 4 things:

Do not include a grouping key, the system will automatically include any defined groupings on the filter. This applies to (2-4) as well, if you do not specify behavior for a certain grouping, the default behavior is to include it.
Include a grouping, filtered to certain values, For example, the following value will include all @.app.version values where @.device_type is android

[{"grouping":"@.device.type", "filters": ["ios"], "returnGroupingValues":true}]

Include a grouping, filtered to certain values, but do not return the filtered values. For example, the following value will include all @.app.version values where @.device_type is android but the response won't include a key for @.device.type

[{"grouping":"@.device.type", "filters": ["ios"], "returnGroupingValues":false}]

Disregard a grouping by aggregating it. For example, the following will aggregate results per @.app.version only.

[{"grouping":"@.device.type", "filters": ["$__agg"], "returnGroupingValues":false}]

NOTE: $__agg as a filter value takes precedence over returnGroupingValues.

dark

Reminder, our @.device.type field has been aliased to Device Type - which is returned in the metric results.

Example Responses

[
	{
    "dt": "2023-10-16T19:30:00Z",
	"value": 9,
	"groupings": {
		"Device Type": "ios",
        "@.app.version":"1.0.0"
	    }
    },
	{
    "dt": "2023-10-16T19:30:00Z",
	"value": 5,
	"groupings": {
		"Device Type": "android",
        "@.app.version":"1.0.0"
	    }
    },
    {
	"dt": "2023-10-16T19:45:00Z",
	"value": 53,
	"groupings": {
		"Device Type": "ios",
        "@.app.version":"1.0.0"
        }
    },
    {     
	"dt": "2023-10-16T20:25:00Z",
	"value": 56,
	"groupings": {
		"Device Type": "ios",
        "@.app.version":"1.0.0"
	    }
    }
]

[
	{
    "dt": "2023-10-16T19:30:00Z",
	"value": 9,
	"groupings": {
		"Device Type": "ios",
        "@.app.version":"1.0.0"
	    }
    },
    {
	"dt": "2023-10-16T19:45:00Z",
	"value": 53,
	"groupings": {
		"Device Type": "ios",
        "@.app.version":"1.0.0"
        }
    },
    {     
	"dt": "2023-10-16T20:25:00Z",
	"value": 56,
	"groupings": {
		"Device Type": "ios",
        "@.app.version":"1.0.0"
	    }
    }
]

[
	{
    "dt": "2023-10-16T19:30:00Z",
	"value": 9,
	"groupings": {		
        "@.app.version":"1.0.0"
	    }
    },
    {
	"dt": "2023-10-16T19:45:00Z",
	"value": 53,
	"groupings": {		
        "@.app.version":"1.0.0"
        }
    },
    {     
	"dt": "2023-10-16T20:25:00Z",
	"value": 56,
	"groupings": {		
        "@.app.version":"1.0.0"
	    }
    }
]

[
	{
    "dt": "2023-10-16T19:30:00Z",
	"value": 14,
	"groupings": {		
        "@.app.version":"1.0.0"
	    }
    },	
    {
	"dt": "2023-10-16T19:45:00Z",
	"value": 53,
	"groupings": {		
        "@.app.version":"1.0.0"
        }
    },
    {     
	"dt": "2023-10-16T20:25:00Z",
	"value": 56,
	"groupings": {		
        "@.app.version":"1.0.0"
	    }
    }
]

# Rate Limits

The /metrics/results endpoint is limited to 150 requests every 10s per organization. If you need a limit increase, please contact us us to discuss your usecase.