# Insights API

The **Younium Insights API** provides access to Insights data entities using a standard **OData v4 interface**. This guide describes how to interact with the API and query KPI data.

> ⚠️ **Note**: This is a pre-release version of the API. Adjustments may be introduced in the future. We welcome feedback from our users.

### Current Endpoints

The following endpoints are available and returns KPI data per month, including all standard and custom fields. See [environments](https://developer.younium.com/documentation/environments) for base urls.

* **Recurring Revenue:**\
  **GET** `{evironment-base-url}/insights/Odata/recurringrevenue`
* **All Metrics:**\
  **GET** `{evironment-base-url}/insights/Odata/allmetrics`
* **Revenue Changes:**\
  **GET** `{evironment-base-url}/insights/Odata/revenueChanges`

### Authentication

Steps to authenticate can be found on [Get started](https://developer.younium.com/get-started)

> ⚠️ **Important**: Legacy/classic authentication methods are **not supported** for the Insights API.

### Query Parameters

Because responses can be very large, queries should be filtered using OData parameters:

* **`$format`**\
  Defines the response format.
  * Recommended:

    ```
    $format=application/json;odata.metadata=none
    ```
* **`$top`**\
  Limits the number of records returned.
  * Example:

    ```
    $top=1000
    ```
* **`$skip`**\
  Skips a defined number of records (useful for pagination).
  * Example:

    ```
    $skip=5000
    ```
* **`$orderby`**\
  Sorts results by a specific field.
  * Example:

    ```
    $orderby=AccountName desc
    ```
* **`$apply`**\
  Used for **filtering and grouping**.
  * Example:

    ```
    $apply=filter(YearMonth ge 202510 AND YearMonth le 202510)/
           groupby((AccountName,ChargeNumber,YearMonth), aggregate(ARR with sum as ARR))
    ```

***

### Example Request

A full query combining parameters:

```http
GET https://api.younium.com/insights/Odata/recurringrevenue
?$count=true
&$format=application/json;odata.metadata=none
&$orderby=AccountName desc
&$skip=0
&$top=1000
&$apply=filter(YearMonth ge 202501 AND YearMonth le 202501 AND ARR ne 0)/
        groupby((AccountName,ChargeNumber,YearMonth), aggregate(ARR with sum as ARR))
```

This query:

* Counts the records (`$count=true`)
* Returns JSON without OData metadata
* Orders results by account name (descending)
* Returns 1000 records starting from offset 0
* Filters data to January 2025 (`YearMonth ge 202501 AND YearMonth le 202501`)
* Excludes records where ARR = 0
* Groups results by `AccountName`, `ChargeNumber`, and `YearMonth`
* Aggregates ARR as a sum