# Endpoints

Endpoints make it easy to incorporate your Aggregations data into your product, analytics or BI workflow. Building on top of Filters and the Metrics API, you can control (in the UI) what information you'll return without needing to understand all the intricacies of the API.

# Creating an Endpoint

An Endpoint has five key components:

#	Component	Description
1	Related Filter	Which of your filters will your endpoint source its results from?
2	Timing	Choose whether you're doing a single "Lookback" or want a Time Series return
3	Groupings	Define the behavior for groupings defined on your source filter
4	Return Fields	Which aggregations & calculations to return
5	Sort Settings	Control how many results are returned and in what order

Choose one of your filters to retrieve results for. You can create multiple endpoints referring to the same filter, in order to mix and match groupings, time periods, etc.

Changing Your Filter

When your endpoint is linked to a filter, changing your filter's definition may impact the results of your endpoint.

Be sure to read the considerations below for more details.

# Timing

Your endpoint can either be a Lookback or a Time Series.

# Lookback

A Lookback will show you aggregate results over a period of time.

# Duration

Choose a duration that is greater than or equal to the interval of your source filter. It is best to keep duration a multiple of your source interval.

For example, if your source interval is 60 minutes, a 90 minute duration will never contain more than 60 minutes worth of data. If you want a 90 minute duration sometimes and a 60 minute duration other times, it'd be best to set your filter up at 30 minutes.

See more about how duration calculations work below

# Offset

When retrieving the results for your endpoint, the default behavior is to start from now. You can instead define a buffer window or consistent offset to apply to all requests.

# Include Incomplete Intervals?

Decide whether you want "incomplete" data to be included in your lookback (default ON).

If your underlying filter has an hourly interval, and you query at 30 minutes past the hour:

With this setting ON those 30 minutes will be included in your results.
With this setting OFF those 30 minutes will not be included in your results, and your query will be shifted back 30 minutes, to ensure you still have a full duration.

# Time Series

A Time Series endpoint allows you to retrieve results at a specified interval.

# Time Series Interval

You can opt to override your source filter's interval, it just needs to be longer than the source's interval.

# Duration

Duration for a Time Series endpoint dictates how far back you'll go to get data points. Your duration must be greater than your interval.

# Offset

When retrieving the results for your endpoint, the default behavior is to start from now. You can instead define a buffer window or consistent offset to apply to all requests.

# Include Incomplete Intervals?

Decide whether you want "incomplete" data to be included in your Time Series (default OFF).

If endpoint interval is hourly (either due to override or the underlying filter) and you query at 30 minutes past the hour:

With this setting ON those 30 minutes will be included in your results.
With this setting OFF those 30 minutes will not be included in your results, and your query will be shifted back 30 minutes, to ensure you still have a full duration.

# Groupings

If your source filter has groupings specified, the Groupings panel controls how/if they are returned when querying your endpoint.

You'll see each of your filter's groupings defined with an option to filter them or aggregate them.

Your choices are:

Option	Behavior	Returns Values
Aggregate (Default)	Values for this grouping will be included in the aggregation but their grouping values ignored.	No
Fixed Filter	Provide a specified list of valid grouping values to be considered when querying	Optional
All Values	All grouping values will be included.	Yes
Query Time	You will provide one or more filter values to include when querying (see below).	Optional

New Groupings

If you add a new grouping to your filter, the default behavior for any associated endpoint will be to Aggregate them into existing grouping choices.

# Return Fields

Return Fields let you choose the Aggregations & Calculations that will be returned in your result set.

# Creating a new Return Field

A Return field consists of:

Name: The name should help you understand that that data represents. This name is used as a key in the resulting JSON payload, so it is important to have it be "system friendly" as well.
Source: Choose the aggregation on your source filter to calculate.
Calculation: Choose which calculation assigned to your aggregation to calculate.
Percentile: If you choose a PERCENTILES calculation, you need to choose the percentile value (0-1).
Advanced Time Settings: When creating a Lookback endpoint, you can override the duration, offset and incomplete interval handling.

# Sort Settings

By default, you will retrieve 1000 items from your endpoint (for Lookbacks).

You can enable sorting to have more fine-grained control over how much data you retrieve and the order they are returned in.

Time Series Sorting

Time Series endpoints will always be sorted in descending order time. Sorting controls how any groupings included in your return are ordered.

# Adding a Sort Field

When you add a new sort field, you can choose whether you're sorting by an unused grouping or return field in ascending or descending order.

# Grouping Limits

When you have multiple groupings defined, you can limit the number of inner grouping items that are returned, as well as the overall number of root items.

For example, if you want to display a leaderboard and have it representative of the top 5 players per team, you could group by player & team, set your grouping limits to:

# Querying Endpoints

Endpoints are accessed by POSTing a JSON payload to https://app.aggregations.io/api/v1/data/{id}

Authentication

All requests must be accompanied by an x-api-token header with an API Key having read permissions.

# Request Parameters

Parameters for your request include:

Parameter	Required	Description
`end`	No	A timestamp to use as the "end" point for your request. By default the current UTC time will be used.
`format`	No	Either `JSON` or `CSV`, `JSON` is the default.
`groupingFilters`	If you have any `Query Time` Groupings	Define the filter values for your `Query Time` groupings.

# Response Format

JSON Responses will include the following properties:

Property	When	Description
`dt`	Time Series endpoints only	The date/time of the interval value
`groupings`	If there are any groupings defined to return values	A map of grouping:value for the selected Groupings to return value.
`fields`	Always	A map of field_name:value (nullable numeric) for your Return Fields.

CSV Responses will include a header row and the order of columns will be:

dt if it is a Time Series endpoint
One column per grouping that is set to return a value, ordered by the order in your source filter.
One column per return field

# Example Requests/Responses

Request:

{}

Response

[
    {
        "groupings": {
            "@.grp1": "Grouping1",
            "@.grp2": "Grouping2"
        },
        "fields": {
            "field_1": 123,
            "field_2": 22.33
        }
    }
    ...
]

Request:

{
    "format": "CSV"
}

Response:

@.grp1,@.grp2,field_1,field_2
Grouping1,Grouping2,123,22.33

Request:

{
    "groupingFilters": {
        "@.grp1": ["GroupingValueIWant1", "GroupingValueIWant2"]
    }
}

Response:

[
    {
        "groupings": {
            "@.grp1": "GroupingValueIWant1"
        },
        "fields": {
            "field_1": 333
        }
    },
    {
        "groupings": {
            "@.grp1": "GroupingValueIWant2"
        },
        "fields": {
            "field_1": -100.7
        }
    }
]

# Considerations

# Filter Changes

Some changes to your filter are "safe" and others are not, so they are not allowed.

# Removing/Renaming a Grouping

If you remove a grouping from your filter that had Return Value enabled, your existing groupings will return, but all values going forward will be empty.

When you return to edit your Endpoint, you will notice the grouping is disabled and a message informs you that if you save, the grouping will no longer be returned in your endpoint response.

# Removing an Aggregation or Calculation

If you attempt to remove an aggregation (or a calculation in use on a field) you may be blocked from saving your filter change. This will happen if it is the only or last valid return field on an endpoint.

If you have other valid fields remaining on your endpoint, you'll be able to save - and any now invalid fields values will return null.

When you return to the edit your Endpoint, you will see the invalid return fields highlighted, and you'll need to edit or remove it befoe saving.

# Modifying your Interval

If your filter's interval becomes more frequent (ie: changing from daily to hourly) and you've created a Lookback endpoint, there is likely no impact.

If your filter's interval becomes more frequent (ie: changing from daily to hourly) and you're using a Time Series endpoint without overriding the Time Series Interval - your endpoint will return values at the newly defined interval.

If your filter's interval becomes less frequent (ie: changing from hourly to daily) you run the risk of losing correctness on your Endpoint.

It is not advisable to modify your filter's interval in this way.

You should ensure you update your Endpoint's duration(s) before modifying the source filter.

# Duration Calculations

The duration and offset concepts are best explained by example.

Let's assume we have ingested events with the values below:

Your underlying Filter is set to an interval of 2 Minutes

It is currently 2025-01-01 12:07:00

Raw Events

Aggregates

Timestamp	Count
`2025-01-01 12:00:00`	1
`2025-01-01 12:01:00`	10
`2025-01-01 12:02:00`	2
`2025-01-01 12:03:00`	8
`2025-01-01 12:04:00`	1
`2025-01-01 12:05:00`	2
`2025-01-01 12:06:00`	100

Timestamp	Count
`2025-01-01 12:00:00`	11
`2025-01-01 12:02:00`	10
`2025-01-01 12:04:00`	3
`2025-01-01 12:06:00`	100^*

# Scenarios:

Lookback endpoint with a 4 minute duration, Include Incomplete Intervals = ON
- Total = 103
Lookback endpoint with a 3 minute duration, Include Incomplete Intervals = OFF
- Total = 3
- Because 3 is not a multiple of the underlying interval and Include Incomplete Intervals is disabled, only the data point at 2025-01-01 12:04:00 is retrieved.
Lookback endpoint with a 6 minute duration, Include Incomplete Intervals = ON
- Total = 113
Lookabck endpoint with a 6 minute duration, Include Incomplete Intervals = OFF, 1 minute offset
- Total = 34
Lookabck endpoint with a 6 minute duration, Include Incomplete Intervals = OFF, 1 minute offset, end specified in query as 2025-01-01 12:04:00
- Total = 21

# Endpoints

# Creating an Endpoint

# Related Filter

Changing Your Filter

# Timing

# Lookback

# Duration

# Offset

# Include Incomplete Intervals?

# Time Series

# Time Series Interval

# Duration

# Offset

# Include Incomplete Intervals?

# Groupings

New Groupings

# Return Fields

# Creating a new Return Field

# Sort Settings

Time Series Sorting

# Adding a Sort Field

# Grouping Limits

# Querying Endpoints

Authentication

# Request Parameters

# Response Format

# Example Requests/Responses

# Considerations

# Filter Changes

# Removing/Renaming a Grouping

# Removing an Aggregation or Calculation

# Modifying your Interval

# Duration Calculations

# Scenarios: