> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/19.latest/management-api/analytics.md).

# Analytics

API endpoints for AI usage analytics and reporting.

The Analytics API provides aggregated usage statistics for AI operations. Use these endpoints to understand AI usage patterns, costs, and performance across your application.

## Endpoints

| Method | Endpoint                                                                                                                    | Description                                                 |
| ------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| GET    | [`/umbraco/ai/management/api/v1/analytics/usage-overview`](/ai-in-umbraco/19.latest/management-api/analytics/overview.md)   | Totals and a time series for a range and a comparison range |
| GET    | [`/umbraco/ai/management/api/v1/analytics/usage-breakdown`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown.md) | One page of usage per provider, model, profile, or user     |

The backoffice [Usage Analytics](/ai-in-umbraco/19.latest/backoffice/usage-analytics.md) dashboard uses these two endpoints.

## Base URL

```
/umbraco/ai/management/api/v1
```

## Common Query Parameters

Both endpoints take these parameters:

| Parameter     | Type   | Required | Description                                                                           |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `from`        | date   | Yes      | First local day of the range (`yyyy-MM-dd`)                                           |
| `to`          | date   | Yes      | Last local day of the range, inclusive (`yyyy-MM-dd`)                                 |
| `compareFrom` | date   | No       | First local day of a comparison range. Send it together with `compareTo`.             |
| `compareTo`   | date   | No       | Last local day of the comparison range, inclusive                                     |
| `timeZone`    | string | No       | Time zone ID the days are local to, for example `Europe/Copenhagen`. Defaults to UTC. |

## Analytics Concepts

### Raw Counts

Both endpoints return raw counts: requests, succeeded and failed requests, input, cached input, output, and total tokens, and time spent in milliseconds. Work out rates and averages from the sums. For example, the success rate is `succeeded / requests` and the average duration is `durationMs / requests`.

### Comparison Ranges

Send `compareFrom` and `compareTo` to get the same counts for a second range, such as the previous period. The response then holds both ranges, so you can show the change between them.

### Time Series

The overview endpoint returns a bucket for every hour, day, week, or month of the range. Buckets without usage hold zeros, so a chart has no gaps.

### Breakdowns

Breakdowns show how usage is distributed across a dimension:

* **Provider** - Which AI providers are used most
* **Model** - Which models consume most tokens
* **Profile** - Which profiles are most active
* **User** - Who uses AI features most

## Example: Dashboard Query

To fill a usage dashboard, call the overview endpoint once and the breakdown endpoint for each dimension you show:

{% code title="UsageDashboardQuery.cs" %}

```csharp
using System.Net.Http.Json;
using System.Text.Json;

public static class UsageDashboardQuery
{
    public static async Task PrintUsageAsync(HttpClient httpClient)
    {
        var range = "from=2026-11-06&to=2026-11-12&timeZone=Europe/Copenhagen";

        // Totals and a daily time series
        var overview = await httpClient.GetFromJsonAsync<JsonElement>(
            $"/umbraco/ai/management/api/v1/analytics/usage-overview?{range}&groupBy=Day");

        var totals = overview.GetProperty("current").GetProperty("totals");
        Console.WriteLine($"Requests: {totals.GetProperty("requests").GetInt32()}");

        // The ten models with the most requests
        var byModel = await httpClient.GetFromJsonAsync<JsonElement>(
            $"/umbraco/ai/management/api/v1/analytics/usage-breakdown?{range}&dimension=Model&take=10");

        foreach (var row in byModel.GetProperty("items").EnumerateArray())
        {
            var requests = row.GetProperty("current").GetProperty("requests").GetInt32();
            Console.WriteLine($"{row.GetProperty("key").GetString()}: {requests}");
        }
    }
}
```

{% endcode %}

The `HttpClient` needs a base address for your site and a Management API access token. For more information, see the [Authentication](/ai-in-umbraco/19.latest/management-api/management-api/authentication.md) article.

## Obsolete Endpoints

These endpoints still work, but they are obsolete and will be removed in version 20:

| Obsolete endpoint                                                                              | Use instead                                                                                                   |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [`usage-summary`](/ai-in-umbraco/19.latest/management-api/analytics/summary.md)                | [`usage-overview`](/ai-in-umbraco/19.latest/management-api/analytics/overview.md)                             |
| [`usage-time-series`](/ai-in-umbraco/19.latest/management-api/analytics/timeseries.md)         | [`usage-overview`](/ai-in-umbraco/19.latest/management-api/analytics/overview.md)                             |
| [`usage-by-provider`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown-provider.md) | [`usage-breakdown`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown.md) with `dimension=Provider` |
| [`usage-by-model`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown-model.md)       | [`usage-breakdown`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown.md) with `dimension=Model`    |
| [`usage-by-profile`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown-profile.md)   | [`usage-breakdown`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown.md) with `dimension=Profile`  |
| [`usage-by-user`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown-user.md)         | [`usage-breakdown`](/ai-in-umbraco/19.latest/management-api/analytics/breakdown.md) with `dimension=User`     |

## Related

* [Audit Logs](/ai-in-umbraco/19.latest/management-api/audit-logs.md) - Raw operation data
* [Usage Analytics Backoffice](/ai-in-umbraco/19.latest/backoffice/usage-analytics.md)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/ai-in-umbraco/19.latest/management-api/analytics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.