> For the complete documentation index, see [llms.txt](https://developer.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.younium.com/documentation/developer-resources/insights-api.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.