# 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](/documentation/environments.md) 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](/get-started.md)

> ⚠️ **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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.younium.com/documentation/developer-resources/insights-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.