# Getting Started

Complete the following steps to get fully set up and see your first aggregation results.

# 1 - Create a User Account

To start using Aggregatiopns.io, you must create a user account. Create an account on the login page at Aggregations.io, by selecting "Create a new account".

# 2 - Create an Organization

Once you've verified your email, you'll be asked to "Create a new Organization" or join an existing one. If you've been invited by another user, you will see an option to accept the invite.

Once you're in an organization, you will begin the "Getting Started" walkthrough.

# 3 - Generate an API Key

After the Welcome tab, a Personal API key will be automatically generated for you. Personal API keys are intended for testing. Download this key and keep it secure. You will not be able to retrieve it again.

For more details on API Keys, see API Keys.

# 4 - Configure Data Ingestion

Data ingestion is comprised of two components:

The event format is the JSON format you will adhere to when sending events to Aggregations.io. There are multiple formats available. Choose the one that matches your event producer:

Array of JSON Objects
Newline JSON
JSON Object with "Events" Array

To learn more about ingestion options, including integrations with upstream data producers, see Ingesting Event Data

Your aggregations will be based on your event timestamps. For most use cases, the Ingest timestamp is sufficient, which is generated when you POST events to Aggregations.io. Alternatively, you can select a custom timestamp using one of your event properties.

To learn more about timestamps and custom timestamps, see Timestamps

Once your ingest is configured, you will receive a POST URL, which will be used later to send events to ingest. If you leave early, you can find the URL and ID on the Organizations page.

# 5 - (Real Time Metrics) Creating Your First Aggregation

We will create an example based on the sample event payload below:

[
{
  "eventName": "AppOpen",
 "device": {
    "platform": "iOS",
    "model": "iPhone15,2"
  },
  "app": {
    "version": "1.0",
    "build": 124
  },
  "eventTimestamp": "2023-10-15T03:53:25.459Z"
  "environment": "prod"
}
]

Aggregations have four components: Filter, Grouping, Aggregation Inteveral, and Calculations.

Filters are the first step in deciding what data to aggregate. Filters are defined using JPath. To learn more about JPath, see JPath

For example, to retrieve the AppOpen events in the prod environment:

@.eventName == 'AppOpen' && @.environment=='prod'

Groupings provide the option to aggregate data sliced by properties in your event payload (up to 10 groupings per filter). When retrieving and visualizing data, you can exclude, filter, or roll up individual groupings.

For example, if we want to group our aggregations by platform and version, we'd add two groupings:

@.device.platform

@.app.version

Even if you group by @.device.platform and @.app.version, you can roll up results by just @.device.platform or @.app.version or neither when retrieving results later.

The aggregation interval controls how often data is aggregated, down to every 30 seconds.

For our example, if we want to monitor variations in traffic on a daily basis, we would select daily.

For more details on choosing the right interval for your use case, see
How to choose your Aggregation Level

Aggregations are comprised of a name, (optional) sub-filter, calculations, and a calculation field. You can add up to 10 calculations per filter.

For our example, if we want to know the number of AppOpens, we'd add a new calculation for COUNT, which will be groupable by device platform and app version.

# 6 - Choose a Plan

Before Aggregations.io can start successfully accepting events, you must choose a plan. Select your plan on the Organizations page.

# 7 - Start POSTing Events

Configure your upstream data producers to begin sending events to Aggregations.io using your POST URL and ID (found on the Organizations page). If you will be sending events via an integration, find the related integration instructions on the [integrations][/ingest/integrations] page to start sending events.

To send events using the Ingest API, send a POST request(s) to your ingest POST URL.

In your POST request, include your API key in the request header as x-api-token

POST Header Template
curl --location 'https://ingest.aggregations.io/{INSERT POST ID HERE}’\
--header 'Content-Type: application/json' \
--header 'x-api-token: {INSERT API KEY}' \
--data ‘[{}]'

Example POST Header
curl --location 'https://ingest.aggregations.io/abc12345' \
--header 'Content-Type: application/json' \
--header 'x-api-token: XXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data '[{}]'

To verify Aggregations.io will accept your events, you can use an API testing tool such as Postman or Insomnia.

Having issues with your POST? See Posting Events Limits & Troubleshooting

# 8 - Visualize Your Results in Grafana

The easiest and quickest way to start visualizing your results is with the Grafana plugin. To visualize or activate your aggregations results another way, see the Metrics API

To install the Grafana plugin, simply navigate to the Plugin page{target="_blank} on the Grafana site and choose Get Plugin.

After installing the plugin, take your API key created in Step 3 and paste it into the API Token field in the Data Source Configuration screen. You now have access to visualize your aggregation!

For production use cases, you should use an 'org-wide' key.

Complete! You are now set up on Aggregations.io!